mlpi4MATLAB: Getting Started

What is MLPI?

MLPI is the acronym for Motion-Logic-Programming-Interface. It is an interface to access motion controllers and drives supplied by Bosch Rexroth AG.

mlpi4MATLAB is based on the Open Core Engineering concept provided by Bosch Rexroth AG. The functionality available in MATLAB and Simulink makes use of the functionality available with the MLPI-SDK (MLPI software development kit). The features of mlpi4MATLAB include functions, examples and documentation integrated as toolbox in the MATLAB environment.

What can the mlpi4MATLAB toolbox do?

The mlpi4MATLAB toolbox includes functionality to:

Connect MATLAB or Simulink to a MLPI device.
Get information about the connected device.
Get access to one or multiples axes in a motion controller.
Control these axes and receive information about them.
Read the diagnosis log of the controller.
Connect to a PLC program running on the MLPI device.
Read and write PLC variables.
Do a lot more.

Where can I find troubleshooting information?

Some fundamental information to troubleshoot potential problem with the toolbox can be found in the Troubleshooting section. For detailed information about the handling of problems in the context of the motion-controller target refer to its documentation.

Where can I get more information?

The mlpi4MATLAB toolbox ships with comprehensive documentation. There are the following levels of documentation inside and outside MATLAB available:

MATLAB documentation about mlpi4MATLAB
MLPI-SDK documentation about mlpiCore
IndraWorks XLC/MLC documentation about the engineering suite for MLPI devices and devices like IndraControl, IndraMotion and IndraDrives.

MATLAB and Simulink documentation about mlpi4MATLAB is integrated in the MATLAB environment.

MLPI-SDK documents will be installed automatically with the MLPI-SDK. It is available from the standard Windows program folders.

IndraWorks XLC/MLC documentation will be installed with IndraWorks. It is available from within IndraWorks or from the standard Windows program folders.

For more information, please refer to the publications at the Bosch Rexroth AG website or at the Bosch Rexroth AG media directory.

How should I start?

Your entry point depends on your knowledge about Bosch Rexroth motion controllers XLC/MLC. If you are not familiar with these systems and the engineering tools refer to the section First Steps (Erste Schritte) in IndraWorks. You will find this information when you open IndraWorks and click on HELP in the menue bar.

The following instructions are based on the assumption that IndraWorks and the motion controllers IndraMotion XLC/MLC are already known. Even if you are already familiar with the functionality of the MLPI-SDK like C/C++ programming, it is recommended to walk through the following sections available in the MATLAB helpbrowser. There are some particularites for MLPI functions in the mlpi4MATLAB toolbox which are different from the mlpiCore features.

Before starting with the MATLAB Quick Start instructions, walk through the fundamental sections of the User Guide.

Particularly the Fundamentals of MLPI Programming section should not be skipped. Following that one can return to the MATLAB Quick Start section to see some quick results.

Copyright

System Requirements

mlpi4MATLAB: System Requirements

The mlpi4MATLAB toolbox requires MATLAB® the MLPI-SDK version 1.11.1.0 or higher available from Bosch Rexroth AG.

The toolbox has been developed for Windows® XP and Windows® 7 operating systems. It provides a set of functions for MATLAB m-file developments as well as Simulink model developments.

The mlpi4MATLAB toolbox supports the development of NRT (non-real-time) and RT (real-time) applications.

For the development of NRT applications the following MathWorks products are required:

MATLAB (32bit) Version 7.14 or higher
Simulink Version 7.9 or higher

The toolbox supports code generation for NRT and RT applications from m-files or Simulink models. To use this functionality the following MathWorks products are required:

MATLAB (32bit) Version 7.14 or higher
Simulink Version 7.9 or higher
MATLAB Coder Version 2.2 or higher
Simulink Coder Version 8.2 or higher

The MATLAB Coder is necessary to generate code from m-files.

The Simulink Coder is necessary to generate code from Simulink models.

For the generation of executable code a compiler for the target platform is necessary as well. The mlpi4MATLAB toolbox supports code generation for Windows® XP or Windows® 7 32bit and VxWorks® target platforms.

For Windows XP® and Windows® 7 target platforms Microsoft Visual Studio® 2010 can be used as compiler.

For VxWorks® target platforms like CML25, CML 45 or CML 65 motion-controller hardware the following compiler is necessary:

Wind River Workbench® V3.3 or higher

Copyright

Installation

mlpi4MATLAB: Installation

Installation

Before the mlpi4MATLAB toolbox can be used you have to install at least the following software components:

MATLAB (32bit)
MLPI-SDK
Windows SDK 7.1 or Microsoft Visual Studio 2010

For code generation information about compatible compilers are available on the MathWorks webpage (e.g. for R2014a).

If you want to build Simulink models with the mlpi4MATLAB toolbox you have to install Simulink as well. The toolboxes MATLAB Coder and Simulink Coder provided by MathWorks Inc. will allow you to generate C code from m-files including mlpi4MATLAB functions or Simulink models including mlpi4Simulink blocks.

The following instructions require that the three components are successfully installed on your computer.

Important note: The mlpi4MATLAB toolbox works only in combination with MATLAB 32bit versions.

The MLPI-SDK is a product provided by Bosch Rexroth AG. It must be installed on your computer to use the mlpi4MATLAB toolbox. This MLPI-SDK installs a directory called mlpi in a user specified directory with several subdirectories. One of these is the subdirectory mlpi4MATLAB in which you can find the file m4MInstall.p.

The installation must not be installed as a subfolder of the MATLAB root directory. To determine this root directory enter

matlabroot

in the MATLAB Command Window.

Start MATLAB and navigate with the frame Current Folder to this mlpi4MATLAB directory and call the function m4MInstall.p from within the Command Window frame. The function will identify the installation folder of the MLPI-SDK and the subdirectories relevant for the mlpi4MATLAB toolbox. The relevant paths will be added to the MATLAB search path so all MLPI functions will be accessible. If you want to check the path information you can enter pathtool in the Command Window to retrieve that information.

The function will also store the installation path in a file needed for the deinstallation. For installation administrator access rights are required.

Important note: Do not move the mlpi folder after the installation as the path information will be corrupted. Do not move the subdirectory mlpi4MATLAB relative to the root directory mlpi as the documentation of the toolbox includes links to the mlpiCore documentation.

During the installation of the MLPI-SDK a directory structure will be installed. The subdirectories for the mlpi4MATLAB toolbox are:

mlpi4MATLAB\bin
mlpi4MATLAB\doc\matlab\html
mlpi4MATLAB\include
mlpi4MATLAB\samples
mlpi4MATLAB\Simulink
mlpi4MATLAB\Simulink\blocks
mlpi4MATLAB\Simulink\VxWorks
mlpi4MATLAB\Simulink\Win32
mlpi4MATLAB\VxWorks

The directory mlpi4MATLAB\bin contains all executable MLPI functions as well as help functions for the Command Window. To each MLPI function you will find a small example that explains the MLPI function a bit more detailed.

The directory mlpi4MATLAB\doc\matlab\html contains the mlpi4MATLAB toolbox help in html format.

The directory mlpi4MATLAB\doc\matlab\pdf contains the mlpi4MATLAB toobox help in pdf format.

The directory mlpi4MATLAB\include contains a header file that has to be included for code generation projects.

The directory mlpi4MATLAB\samples contains application examples which are more complex than the sample files mentioned in the function help.

The directory mlpi4MATLAB\Simulink is the root directory of the mlpi4Simulink blockset coming with the mlpi4MATLAB toolbox.

The directory mlpi4MATLAB\Simulink\blocks contains Simulink block functions, the corresponding Simulink Target Language Compiler (TLC) files and sample models.

The directory mlpi4MATLAB\Simulink\VxWorks contains functions for code generation from Simulink models that include mlpi4Simulink blocks. The files here are those needed for target execution on a MLPI hardware target running Windriver VxWorks operation system.

The directory mlpi4MATLAB\Simulink\Win32 contains functions for code generation from Simulink models that include mlpi4Simulink blocks. The files here are those needed for host execution on the host running Microsoft Windows.

The directory mlpi4MATLAB\VxWorks contains functions for code generation from MATLAB m-files that include mlpi4MATLAB functions. The files here are those needed for target execution on a MLPI hardware target running Windriver VxWorks operation system.

Deinstallation

If you want to deinstall the mlpi4MATLAB toolbox or if you want to move the mlpi folder use the function m4MUninstall.p. The function will remove the mlpi4MATLAB path information from the MATLAB search path but it will not delete any file. To deinstall the mlpi4MATLAB completely use the MLPI-SDK functionality to uninstall SDK components.

Copyright

Features

mlpi4MATLAB: Features

The mlpi4MATLAB toolbox includes functions for the following tasks in the context of motion-logic programming of industrial drives:

Configuration of MLPI devices (IndraMotion XLC/MLC) offered by Bosch Rexroth AG.
Configuration and commanding of several axes types like virtual, real, encoder, controller and link axes using sercos drives.
Control of PLC applications running on MLPI devices.
Read and write access to variables in PLC applications.
Read and write access to fieldbus devices connected to MLPI devices. Fielbusses PROFIBUS, PROFINET, DeviceNET, EtherNet/IP and sercos are supported.

The mlpi4MATLAB toolbox is structured according to four major use cases:

Development of non-real-time applications as MATLAB m-files.
C-code generation from m-files for the development of real-time applications.
Development of non-real-time applications as Simulink mdl-files.
C-code generation from mdl-files for the development of real-time applications.

Generated C-code can be used to write Windows® 32bit applications for standard PC or VxWorks applications for IndraMotion XLC/MLC targets.

Copyright

MATLAB Quick Start

mlpi4MATLAB: MATLAB Quick Start

This section contains some descriptions to start working with MLPI functions of the mlpi4MATLAB toolbox.

Preconditions

To start working with MLPI for MATLAB it is assumed that the following software components are properly installed on your computer:

IndraWorks 13VRs or higher
MATLAB (32bit) Version 7.14 or higher
MLPI-SDK

To use MLPI for MATLAB you also need a XLC/MLC motion-controller with a firmware that supports mlpiCore functionality. The computer running MATLAB and IndraWorks and the motion-controller (MLPI device) must be connected via a network. The following documentation considers that the MLPI device and the computer are connected to a local area network (LAN).

If you want to process the following MATLAB Quick Start instructions, it is recommended to reset the MLPI device to factory settings and disconnect any peripherals from the MLPI device. Refer to the IndraWorks help to cleanup the MLPI device.

After powering up the MLPI device check that the Ethernet settings in the MLPI device are properly set. The Ethernet settings of the MLPI device can be checked or edited using the push-buttons at the device display. If you change the Ethernet settings switch off the device and switch it on again to activate the new settings.

Check that the MLPI device can be accessed from MATLAB using the ping command. Enter the following code in the MATLAB Command Window

!ping a.b.c.d

while a.b.c.d must be replaced by the IP address of your device. MATLAB will prompt the results of the ping command in the Command Window. In case the command failed to ping the MLPI device check your network settings of the computer and the MLPI device or contact your network administrator.

A positive ping result confirms that the MLPI target and the computer are ready to communicate via the network but it does not mean that you can already send MLPI functions to the MLPI device. For using MLPI functions - normally starting with the prefix m4M - a connection to the MLPI device must be established. The basic MLPI functions for connection handling are m4MApiConnect and m4MApiDisconnect to attach to a MLPI device or to detach from the device, respectively.

Example 1 (Read system temperature from MLPI device)

As very simple Quick Start example we want to read the system temperature from a MLPI device. The example contains three steps:

Connect to a MLPI device
Read the system temperature using a MLPI function
Disconnect the MLPI device

To realise this task we have to create a connection handle by entering the following code in the Command Windows:

myHdl = m4MApiConnect('a.b.c.d -user=guest -password=guest')

The MLPI function returns either the following lines:

myHdl =

MlpiConnection handle

Properties:
con: 98980072
throwError: 1

Methods, Events, Superclasses

which indicates a successful execution of the MLPI function or the error message:

Error using m4MApiConnectMex
Failed to connect. (0xF0360014: )

which indicates a failed execution of the MLPI function. The error message may be caused by unexpected long communication time - which is quite unusual - or by the permission and user management setting of the MLPI device. However, with a MLPI device reset to factory settings the user guest with the password guest should be available.

In case of a successful connection you can use some MLPI functions. Each MLPI function is subject to supervision of the user account management. This means that the user guest is allowed to use just a few functions which are non-critical for the device operation. This is a part of the security concept of the MLPI interface. For details refer to the section Permission and user management in the mlpiCore documentation.

The MLPI function m4MSystemGetTemperature from the Systems Functions group is a non-critical function so we can read the system temperature using the guest account by entering:

myTemp = m4MSystemGetTemperature(myHdl)

Almost all MLPI functions need as first input argument the connection handle myHdl that was return earlier above. The variable myTemp contains the value of the system temperature. The numeric value depends on the unit (scaling) defined inside the MLPI device and can be degree Celsius or degree Fahrenheit. For details about the temperature scaling refer to IndraWorks help.

The MLPI function m4MSystemGetTemperature can return two output arguments when entering the following code in the Command Window:

[myTemp,myResult] = m4MSystemGetTemperature(myHdl)

The function returns the following output:

myTemp =

45


myResult =

3538944

Again myTemp contains the actual system temperature. The second output argument myResult contains a numeric value indicating the success of the function call. Semi-positive values indicate the successful operation of the function while negative values indicate a failed function call. For more information about the error handling refer to the section Fundamentals of MLPI Programming.

A connection to a MLPI device should be detached when it is no longer used. Use the MLPI function m4MApiDisconnect to detach the connection by entering the following code in the Command Windows:

m4MApiDisconnect(myHdl)

The function returns with a positive numeric value indicating the successful operation.

However, the user can also delete the variable myHdl entering the code:

clear myHdl

This will clear the variable myHdl but will also prompt the following warning:

Warning: Object deleted but connection handle still existing on the
target. Use m4MApiClose* functions to close the connection on the
target side.

It is recommended to detach the MLPI device from MATLAB using the function m4MApiDisconnect because clearing the variable in MATLAB will not free the memory allocated for the connection management on the MLPI device.

Copyright

Simulink Quick Start

mlpi4MATLAB: Simulink Quick-Start

This section contains some descriptions to start working with MLPI functionality of the mlpi4MATLAB toolbox designed particularly for the Simulink environment. The MLPI blocks for Simulink are also referred to as mlpi4Simulink or m4S blocks. This blockset is an integral part of the mlpi4MATLAB toolbox. Therefore it is recommended to start with the document mlpi4MATLAB MATLAB Quick Start before working with the Simulink blockset.

Preconditions

To start working with MLPI blocks for Simulink it is assumed that the following software components are properly installed on your computer:

IndraWorks 13VRs or higher
MATLAB (32bit) Version 7.14 or higher
Simulink (32bit) Version 7.9 or higher
MLPI-SDK

First, work through the preconditions explained in the MATLAB Quick Start document.

Example 1 (Read system temperature from MLPI device)

As very simple Quick Start example we want to read the system temperature from a MLPI device using Simulink. The example contains three steps:

Check or create the MATLAB workspace variables m4SIpAddress, m4STsample, m4SStopTime and m4SEnableSimAutoStop
Open the example model with Simulink
Run the simulation of the example model with Simulink

The mentioned workspace variables will be created during the installation with m4MInstall if they do not already exist. If they exist, it will be checked if their type and dimensions are correct. Values can not be validated. In this section the variable definition will be done explicitly.

So let us assume the MLPI target device has the IP address a.b.c.d and is accessible via LAN. Th eMATLAB workspace variable m4SIpAddress can be created by entering the following code in the MATLAB Command Window:

m4SIpAddress = 'a.b.c.d -user=guest -password=guest'

This is because the example model used further down has a variable name m4SIpAddress as default entered in the MLPI block m4SApiConnect.

The model shall be executed with a fixed-step solver as already pre-defined in the Simulink Configuration Parameters dialog. Most of mlpi4Simulink blocks inherit the sample time due to the value -1 pre-configured in their dialog parameter Sample time. However, in some blocks this block parameter or the Configuration Parameters dialog parameter Fixed-step size (fundamental sample time) are pre-defined with workspace variable m4STsample. Entering the following code in the MATLAB Command Window will create the variable and set the sample time to 0.1s:

m4STsample = 0.1

The variable m4SEnableSimAutoStop is used in some m4S sample models to control if the model stops after a successful execution of the function. For the sample described here the model shall read the system temperature and stop after a successful execution. So m4SEnableSimAutoStop shall be true. Entering the following code in the MATLAB Command Window will create the variable and set the auto-stop true:

m4SEnableSimAutoStop = true

Alternatively, the variable could be set false. In this case the model continous reading the system temperature from the MLPI target device until the defined solver stop-time is reached.

The variable m4SStopTime is used in some m4S sample models to set the solver stop-time. Entering the following code in the MATLAB Command Window will create the variable and set the stop-time to 30 seconds:

m4SStopTime = 30

For this easy sample model the use of m4SEnableSimAutoStop and m4SStopTime is just for compatibility reasons. For more sophisticated use cases like automatic code generation or parameter variation studies these two variables have the advantage to access these simulation parameters directly without the need to manipulate the model settings through the Configuration Parameters dialog.

The example model that is descibed here is available in the folder ./mlpi/mlpi4Simulink/blocks. Open it by clicking on this link:

m4SSystemGetTemperature_Sample.mdl

The example model is shown here:

The model consists of multiple blocks. The block named m4SApiConnect is of type m4SApiConnect. It belongs to the API block group. Its function is to create a connection to the MLPI device and provide a connection identifier at its output connection. With the output result it can signalize if the block succeeded executing its functionality. If the value of output result is positive the block succeeded. This block handles also automatically the disconnection from the target once the model execution is stopped or interrupted by an error.

Both outputs of the block m4SApiConnect are connected to a second block named m4SSystemGetTemperature. This block is of type m4SSystemGetTemperature. It belongs to the System block group and reads the actual CPU temperature of the connected MLPI target. This block has only these two standard inputs. At the input connection the block gets the mandatory connection identifier from the first block. At the second input result the block gets an information if the block shall execute its functionality. Some MLPI blocks might need the successful execution of another block to execute its own function. E.g. here in the example the block m4SSystemGetTemperature shall only be executed if the connection was successfully established.

If the valid connection identifier is applied at the input connection which is indicated by a positive result value at the second input, the block m4SSystemGetTemperature reads the CPU temperature and provides three outputs. The two standard output ports are connection and result as explained. This means blocks can be daisy-chained and if one block in this chain fails the execution of the following blocks will not be started in that iteration cycle.

The block named Digital Clock is just used to display the execution time in combination with the display block sim_time.

The block m4SUtilRealTime is used to slow down the fixed step solver almost to real time. This is done to get a simulation time almost equal to the really elapsed time because normally the solver will simulate the model as fast as possible. By use of this block the simulation model runs nearly in sync with real world. However, if simulation of the model takes longer than time elapsed in real, the block will have no effect and prompts a warning in the MATLAB Command Window. There is only one block of m4SUtilRealTime allowed per model.

In this example simulation time is set to m4SStopTime as shown in the toolbar and the workspace variable m4SEnableSimAutoStop used in the block stopManager is true. So after a successful connection and reading of the temperature, this model will stop. If the connection would fail or if the temperature could not be read, the simulation will stop after the time defined by m4SStopTime. The block m4SApiConnect will try to disconnect the MLPI target latest.

Note: The variable m4SIpAddress may also include a timeout setting for the connection handling. If the model is not able to connect to the target and the timeout setting is longer than m4SStopTime the model ends when the timeout expires. Refer to the documentation of m4SApiConnect for details about the timeout handling.

The subsystem stopManager includes some simple logic to stop simulation if the inputs In1 and In2 are positive values and if the workspace variable m4SEnableSimAutoStop is true.

The following figure shows the dialog box when double-clicking on the m4SApiConnect block.

The block has two parameters. As explained above, for the parameter IP address the default variable m4SIpAddress is entered. Instead of using the workspace variable one can enter the connection string (IP address plus options) as char array as well.

Obviously, if settings are wrong, the model execution will fail. The following dialog is displayed if the workspace variable was not created before starting the simulation. This is typical mistake that can be resolved following the instructions above.

If Simulink seems to stop execution after pressing Start simulation or Ctrl+T, most likely the target can not be reached and the block m4SApiConnect blocks simulation and waits for the timeout to expire. This can be avoided by checking the preconditions explained in MATLAB Quick Start.

Copyright