mlpi4MATLAB: Introduction
Design Guideline
The mlpi4MATLAB toolbox follows some basic design guidelines. These guidelines will help the user to get familiar with the toolbox. They include the following aspects:
- General structure
- Nomenclature of functions
- Definition of constants
- Definition of types, structures and enumerations
- Definition of input and output arguments
General Structure
The toolbox mlpi4MATLAB is structured in groups of functions that deal with similar features. The following groups of functions are available:
- API functions
- System functions
- Motion functions
- Logic functions
- Parameter functions
- Watchdog functions
- Task functions
- Trace functions
- I/O functions
- Container functions
- Utility functions
- Type definitions
- Constants
Nomenclature of Functions
The mlpi4MATLAB toolbox uses its own namespace in order to avoid collisions with other MATLAB® products. Each function shipped with the toolbox starts with m4M, Mlpi or M4M. The case of the characters indicates if the command is a standard MLPI function, a MLPI type or a MLPI constant, respectively.
According to the structure of the mlpi4MATLAB toolbox the initial characters of a function indicate the function group. E.g. all functions that are API functions start with m4MApi, all functions that are motion functions start with m4MMotion and so further for the other function groups.
As type definitions and constants can hardly be associated with particular function groups they do not necessarily have an indication following the initial characters Mlpi or MLPI. E.g. the type definition MlpiScalingMode is an enumeration that is related to a scaling mode of a drive or control parameter and therefore does not include an additional function group reference.
Definition of Constants
mlpi4MATLAB includes a set of globally defined constants that help software developers to write code easier and to write more robust code. Constants use capital characters and undercores to improve readability. The value of a constant is retrieved from the underlaying mlpiCore and can be seen be entering the constant name in the Command Window. The mlpi4MATLAB toolbox encapsulates MLPI constants in a class called M4M_CONST. The class contains a list of properties that contain the value of the constant. Type
M4M_CONST
in the Command Window to get the list of properties. If you want to use a constant in program code you can use the dot separator like M4M_CONST.INFINITY to get the numeric value of the symbolic definition of what mlpi4MATLAB functions consider as infinity. MATLAB will return:
ans =
4294967295
Constants have a type that should not be changed in cooperation with other mlpi4MATLAB functions. To get the type of a constant assign the value to a variable like
myInf = M4M_CONST.INFINITE
and use the command whos to get more detailed information about the variable. The command
whos myInf
will prompt:
Name Size Bytes Class Attributes
myInf 1x1 4 uint32
or use the buildin function class as follows
class(M4M_CONST.INFINITE)
Brief information about a constant can be obtained by calling
help M4M_CONST
Definition of Types, Structures and Enumerations
The mlpi4MATLAB toolbox can be used for MATLAB m-file and Simulink mdl-file developments as well as for code generation for C/C++ applications. MATLAB itself defines several types like int32 or char but the preferred and default type for numeric values is double. MLPI functions need to handle different kind of numeric values so the type of input arguments to MLPI functions needs to be considered. With respect to the code generation features and as C/C++ applications usually need clear type definitions this applies for MLPI function as well.
A list of fundamental data types defined by MLPI and a correspondance to MATLAB fundamental data types is available in the help function of MlpiType as enumeration.
The correspondance between MATLAB, IEC and mlpiCore data types is:
mlpiCore type MATLAB type IEC type
-------------------------------------------------------------
CHAR int8 SINT
UCHAR uint8 BYTE
SHORT int16 INT
USHORT uint16 WORD, UINT
LONG int32 DINT
ULONG uint32 DWORD, TIME, DATE,
DATEANDTIME, TIMEOFDAY,
UDINT
LLONG int64 (no direct support) LINT
1x2 array of uint32 for
handles
ULLONG uint64 (no direct support) LWORD, ULINT
1x2 array of uint32 for
handles
FLOAT single REAL
DOUBLE double LREAL
CHAR array matrix of int8 array of SINT
UCHAR array matrix of uint8 array of BYTE
SHORT array matrix of int16 array of INT
USHORT array matrix of uint16 array of WORD
LONG array matrix of int32 array of DINT
ULONG array matrix of uint32 array of DWORD
LLONG array (not supported) array of LINT
ULLONG array (not supported) array of LWORD
FLOAT array matrix of single array of FLOAT
DOUBLE array matrix of double array of DOUBLE
BOOL8 logical BOOL
BOOL8 array matrix of logical array of BOOL
CHAR_UTF8 no direct correspondance STRING[1]
(char)
CHAR_UTF16 no direct correspondance WSTRING[1]
(char)
CHAR_UTF8 array no direct correspondance STRING[1..n]
(matrix with char)
CHAR_UTF16 array no direct correspondance STRING[1..n]
(matrix with char)The function help includes documentation about the types of input and output arguments. More information about input and output arguments will be found further down. MATLAB supports numeric values with complex numbers. Within the context of input and output arguments of MLPI functions all numeric values must be real numbers except otherwise described.
Inside a motion-controller there is lot of information the user may need. In order to organise this information in a way the user can handle it as easy as possible, information that belongs strongly together is bundled in MLPI data types using structures. Several MLPI functions return these structures as output arguments.
The structure MlpiVersion is an easy example of a MLPI structure. The MLPI function m4MApiGetClientCoreVersion returns the version information of the MLPI core library on MATLAB side of the client server architecture. So calling the function with the command
myVersion = m4MApiGetClientCoreVersion()
will return
myVersion =
major: 1
minor: 2
bugfix: 0
patch: 0
build: 44
If a variable of this structure is needed it can be create using the structure definition entering
myVersion = MlpiVersion
which creates the variable myVersion that is an empty MlpiVersion structure. Each structure element will have a predefined type. In case of the MlpiVersion structure all elements will be of type uint32. Information about the types of elements in a structure can be retrieved by calling help followed by the structure name. If a variable has already been created the Workspace window will provide this information as well.
Definition of Input and Output Arguments
As described above, MLPI functions are type-sensitive. The most often used input argument to MLPI functions is the connection handle which is an object of the class MlpiConnection. Each MLPI function that will communicate with the MLPI server on the motion-controller needs an object of this class as first input argument. The input argument must be scalar as a MLPI function can access only one MLPI server on a motion-controller per function call. The function m4MApiConnect can be used to create this connection object and the function m4MApiDisconnect can be used to destroy the object. More information can be found in the linked function help.
Another important input argument is the reference to axes that is needed for almost all m4MMotion functions. In the documentation this argument is named axisRef. The argument can have two different forms. Either it is a scalar real numeric value or a Nx2 matrix. The argument defines the axis or axes that will be accessed. If the argument is just a scalar, the MLPI function interprets it as a 1x2 matrix while the first element will be set to zero. So finally the MLPI function uses always a Nx2 matrix but for ease of programming the functions accept also scalar input arguments. Within this matrix the first column defines the control number and the second column defines the axis number. This is because IndraMotion XLC/MLC supports distributed system architectures in which axes can be handled on different targets. MLPI functions are able to access these distributed axes. More information about the use of axes can be found in the function help of m4MMotion functions.
While most MLPI functions need a correct data type there are a few functions that cast the variable type to a specific type implicitly. axisRef is one of these exceptions where the function accepts numeric values and casts them to uint32 internally.
m4MMotion functions are the core of the mlpi4MATLAB toolbox. Therefore the form of the axisRef argument defines the form of many other variables. As already explained above axisRef can specify a set of axes while in each row of the argument a pair of control number and axis number specifies a dedicated axis. This means the argument is row-oriented. m4MMotion functions can execute the same function on several axes if axisRef is an Nx2 matrix. An example is the function m4MMotionMoveVelocity that commands a velocity controlled motion to one or multiple axes. In order to move several axes some motion parameters have to be specified. In this function it is the setpoint velocity, the acceleration limit, the deceleration limit and the jerk limit for this particular movement. For a single axis the command could be called as follows:
myCon = m4MApiConnect('192.168.1.2')
myAxis = 1
myVel = 1000
myAcc = 100
myDec = 50
myJerk = 0
mhdl = m4MMotionMoveVelocity(myCon, myAxis, myVel, myAcc, myDec, myJerk)
m4MApiDisconnect(myCon)
In this example all input arguments to the function are scalar because a movement of a single axis is called. The function has an output argument that is assigned to the variable mhdl which is a handle to the movement caused by this function. With this handle the user can check if the setpoint velocity is reached when using the functions m4MMotionGetAxisState to get the encoded axis state and m4MMotionDecodeAxisState to get a plain text structure MlpiAxisStateDecoder that shows if the axis has reached the setpoint velocity.
When applying the function to two axes with one function call the arguments could be as follows:
myCon = m4MApiConnect('192.168.1.2')
myAxis = [0,1;0,2]
myVel = [1000,900]
myAcc = 100
myDec = [50,40]
myJerk = 0
mhdl = m4MMotionMoveVelocity(myCon, myAxis, myVel, myAcc, myDec, myJerk)
m4MApiDisconnect(myCon)
In this example the axisRef input argument is a 2x2 matrix and the following arguments are either 2x1 or 1x1 matrices. This means that the user can specify an input argument for an axis individually or one value that applies to all axis to simplify writing code. The variable mhdl is a 2x1 matrix that contains two handles, one for each axis. This concept is valid for many MLPI functions. Each function help describes if and how this concept can be used. This concept is the reason why many functions accept column vectors as input arguments and return column vectors as output arguments. For ease of programming some functions accept a column vector or a row vector with the same number of elements to improve useability but the standard format is column vectors.
Internally MLPI functions use the mlpiCore dynamic link library (DLL) that can handle only scalar input parameters. This means that MLPI functions that are called with column vector inputs split the single function call in a MATLAB script internally in several function calls to the mlpiCore DLL. This means that if a function like the example of m4MMotionMoveVelocity is called with several axes, the effective movement calls in the motion-controller are not executed exactly at the same time. This is true for any MLPI function that is called with column vector inputs. However, there are methods to get or set isochronous data and synchronous motion of axis. These methods are explained in the mlpi4MATLAB tutorials.
As explained axisRef is an exception of an input argument that has in internal type casting. Another exception is the input argument kinGroup of m4MRobot functions. Many other input arguments are type-sensitive. This means that the user has to check if the argument has to be of a specific type or not. In the example using the function m4MMotionMoveVelocity there was no explicit type specification used for the input arguments velocity, acceleration and jerk as the internal data type must be double so there is no loss of precision if the arguments would be of any other numeric data type. For other input arguments it might be essential that the user specifies a correct type as an internal casting of types would impact precicion or hide manipulations of values.
Functions that need specific data types verify the correct data type before executing the command and throw an error in case of a type violation. As mentioned above data types might be native MATLAB data types or MLPI-specific data types.
Copyright
Legal notice and version: © 2017 Bosch Rexroth Corporation http://www.boschrexroth.com DC-AE/EAS1 (MGo) Library version: 1.26.2.0.0
mlpi4MATLAB: Fundamentals of MLPI Programming
The chapter Fundamentals of MLPI Programming contains fundamentals the user should be familiar with before starting to write code including MLPI functions.
Error Identification and Handling
The mlpi4MATLAB toolbox supports different kinds of error handling according to the use case the functions are used for. A convenient way of error handling in MATLAB is the use of try/catch statements. However, MATLAB does not support these statements in code generation. Therefore the two major use cases
- MATLAB script programming and
- code generation from MATLAB scripts
have to be distinguished.
MLPI functions are executed as remote procedure calls in the target device and the user would like to know if the function calls succeeded or failed. Therefore each MLPI function call can return an integer value of type int32 which indicates if the function has succeeded or failed. A return value is positive or zero if a function call succeeded and negative if a function call failed.
For details about error codes refer to the section About Return Values in the mlpiCore documentation. Here you will just find the documentation that is particular for mlpi4MATLAB.
Translating an error code to textual representation
There is an interesting possibility when dealing with error codes. It is possible to ask the connected device if it can convert the error code into a human readable textual description. This can be done by using the MLPI function m4MSystemConvertDiagnosisNumberToText. Please note, however, that you need an active MLPI connection to the device, as the conversion and description lookup is done on the server side of the MLPI, which means in the target device itself.
The following example
myCon = m4MApiConnect('192.168.20.10');
myDiagNumber = hex2dec('F02D1001');
myDiagText = m4MSystemConvertDiagnosisNumberToText(myCon,myDiagNumber);
disp(myDiagText);
m4MApiDisconnect(myCon)
will return the textual description of the error code hex2dec('F02D1001'):
'Kein Eintrag in Datenbank gefunden'
if the system language is set to german. It means the error code has no entry in the error code database.
The mlpi4MATLAB toolbox supports two error handling methods according to the two use cases mentioned. The error handling methods can be configured with the MlpiConnection object that is returned by the function m4MApiConnect. An object of this class has two properties named con and throwError. The first property contains the connection identifier and the second property is set to true as per default. If throwError is true it means that the MLPI functions will throw an error exception if the function fails to execute the remote procedure call. The following example will show the result if a function fails. Let's assume there is no axis number 10 configured in the motion controller but the user wants move this axis by mistake. So he calls the following command with a valid connection object myCon whose property throwError is true.
[myHdl, result] = m4MMotionMoveVelocity(myCon,10,10,10,10,0)
MATLAB prompts:
Error using m4MMotionMoveVelocityMex
Failed to set velocity. (0xF017EA01: Kein Eintrag in Datenbank gefunden)
Error in m4MMotionMoveVelocity (line 57)
[motionHandle,result] = m4MMotionMoveVelocityMex(connection, axisRef,velocity, acceleration, deceleration, jerk);
The text Failed to set velocity. (0xF017EA01: Kein Eintrag in Datenbank gefunden) contains the error code 0xF017EA01 and no values are assigned to the output arguments. The text Error in m4MMotionMoveVelocity (line 57) is irrelevant here as it just indicates that the error was caused by the internal call of m4MMotionMoveVelocityMex in the shadow-function m4MMotionMoveVelocity that the user cannot access.
Let's assume there is an axis 1 configured in the target and the user calls the command
[myHdl,result] = m4MMotionMoveVelocity(myCon,1,10,10,10,0)
MATLAB will prompt:
myHdl =
17179869208
result =
524288
This means the motion-handle is assigned to myHdl and the positive error code is assigned to result. If the error code is positive normally the value is not interesting and can be skipped. So calling the function with
myHdl = m4MMotionMoveVelocity(myCon,1,10,10,10,0)
is sufficient.
If the user wants to apply an error handling procedure he can easily use a try/catch environment to do this. This might look as follows.
try
myHdl = m4MMotionMoveVelocity(myCon,10,10,10,10,0)
catch err
disp(err.identifier)
disp(err.message)
end
In this case err contains the error exception that the user can analyse in a user defined function in order to apply an adequate procedure.
However, this try/catch environment cannot be used for code generation using MATLAB's Coder toolboxes. Therefore the propery throwError of the connection object can be set to false. There is two ways of changing the default value to false. The easiest way is to change the property after creation of the object with the following syntax:
myCon.throwError = false
If the user calls the invalid command as explained above again with
[myHdl,result] = m4MMotionMoveVelocity(myCon,10,10,10,10,0)
MATLAB will prompt:
Warning: Failed to set velocity. (0xF017EA01: Kein Eintrag in Datenbank gefunden)
myHdl =
NaN
result =
-266868223
Instead of an error a warning is displayed and values are assigned to the output arguments. As the function failed the motion-handle does not contain a valid number. This is indicated by the assignment of MATLAB's not a number NaN. But the output result contains the valid error code which is negative for a failed function call. The user can call the function m4MSystemConvertDiagnosisNumberToText if the connection object is still valid.
m4MSystemConvertDiagnosisNumberToText(myCon,result)
ans =
'Kein Eintrag in Datenbank gefunden'
With a if/then environment the user can check positive or negative result values and can branch to a dedicated error handling. This can also be used for code generation with MATLAB's Coder toolboxes.
The second way of changing error handling is the use of the connection option suppressThrow already when creating the connection object. The syntax of connection options is described in the help documentation of m4MApiConnect. As an example the creation of a connection object with this function
myCon = m4MApiConnect('192.169.20.10 -suppressThrow=true')
will prompt
myCon =
MlpiConnection handle
Properties:
con: 665589512
throwError: 0
Methods, Events, Superclasses
The value following con: is the connection identifier that is individual for each connection object. As shown the property throwError is set to false, so 0 as logical value.
When writing MATLAB functions or scripts it is recommended to start working with the option suppressThrow=true and usage of the output argument result for each function.
Note: Particularly when writing MATLAB code that will be used for code generation a return value NaN is difficult to use. Therefore most of the mlpi4MATLAB functions (m4M) return their output arguments with default values according to their size and data type defintion when used in code generation but if the output argument result is negative, other output arguments are invalid.
The mlpi4MATLAB toolbox supervises the syntax of m4M-functions and throws an error accordingly. This means even if the connection handle throwError is set false a function call with invalid syntax in the arguments will prompt an error. This feature helps to avoid unexpected effects with code generation. This means that throwError affects valid remote procedure calls with negative result value.
m4M*Mex functions - which shall not be used by the user directly - supervise the syntax as well, but assess the throwError property. The following example will demonstrate it. First create a valid connection handle:
myCon = m4MApiConnect('192.169.20.10 -suppressThrow=true')
Now let's call a function with an invalid syntax:
m4MSystemSetDateAndTimeUtc(myCon,123)
It will will prompt an error as follow:
Error using m4MSystemSetDateAndTimeUtc (line 56)
Not enough input arguments.
This is because the syntax of the function m4MSystemSetDateAndTimeUtc is supervised. However, calling the mex-function again with the same invalid syntax:
m4MSystemSetDateAndTimeUtc(myCon,123)
will prompt the following warning:
Warning: m4MSystemSetDateAndTimeUtc: Eleven input arguments required. (0xF0360001: MLPI:
Allgemeiner Fehler)
ans =
-264896511
An invalid connection handle will always prompt an error.
Note: Do not use the mex-functions directly as they are underlaying functions. Particullarly they do not support code generation.
Error Identification and Handling with mlpi4Simulink
The permission and user management for mlpi4Simulink is similar to what is described above. However, there are some items which are slightly different.
In mlpi4Simulink almost all blocks have two standard inputs and two standard outputs. These are the ports labeled connection and result. The input port connection is directly fed through to the output port connection and will not be modified be the block. This is because blocks can be daisy-chained easier.
As described above, almost each mlpi4MATLAB function returns an output argument result. But the mlpi4Simulink blocks do also have an input port result. This helps to build models with blocks that are executed sequentially. E.g. to move a real axis, first the power has to be switched on and if the MLPI target failed to switch on the power, the following motion block should not be executed. Therefore almost each block has an input port result that controls the execution of the internals of the block. If the input port result is negative the block will not be executed and the input port result is directly fed through to the output port result. This avoids sequences of errors. Other output ports will keep the same value as in the previous iteration of the solver.
If the input port result is non-negative, the block will be executed and the result of this execution will be available at the output ports. Particullarly the value of the output port result normally is different than the input port as it belongs to the execution of the internal functionality. Other output ports will have the values according to the block functionality.
If the execution of the internal functionality fails, the output port result will be negative and the other output ports will be invalid. However, the output port connection will not be changed as it is just a feed through information.
Note: The output signals of mlpi4Simulink blocks are invalid if the output signal result is negative.
In one aspect mlpi4Simulink blocks differ from mlpi4MATLAB functions. This is the throw of an exception. The function m4MApiConnect accepts the option suppressThrow=value in which value can be true or false. The block m4SApiConnect ignores this option and always uses suppressThrow=false. This is because the try / catch environment is not support with Simulink. For an error handling of mlpi4Simulink blocks all of them provide the output port result. As an example calling a motion block like m4SMotionMoveVelocity with a real axis that has no power should not terminate the model rather than creating an error that can be managed by an adequate error manager component.
Permission and User Management
The MLPI has the possibility of user specific account management based on function layer, which means a user logged into an MLPI device is owner of a fix set of permissions which allow him to execute a fix set of MLPI functions in the system. MLPI functions are bundled as function groups, where each group is assigned to one explicit permission.
During establishment of the connection by m4MApiConnect the user account itself and the maximum number of logins of this user account will be checked by the system. Therefore, you have to define the username and password of the account you want to login to with the function m4MApiConnect. In case of successful validation the user will get the corresponding permissions for the complete session of this connection. If the maximum number of logged in users is reached the function m4MApiConnect will return the error MLPI_E_LIMIT_MAX. In case of the user is not the owner of a permission of a function group the user will get the error MLPI_E_PERMISSION on the invalid call of a function of this group.
A connection can be closed by a different connection by use of the functions m4MApiCloseConnectionByUid, m4MApiCloseConnectionsByUser or m4MApiCloseConnectionsByUri to protect dead locks caused by reaching the maximum number of concurrent logins. To prevent the closing of your connection by another connection use the attribute protection within your user account or your connection string of the function m4MApiConnect (see MlpiApiProtection). If a connection runs in protected mode the functions m4MApiCloseConnectionByUid, m4MApiCloseConnectionsByUser or m4MApiCloseConnectionsByUri returns the error MLPI_E_RD_WR_PROTECTION.
The user account list, the attributes and the permission sets are defined in the manifest accounts.xml which is located on the oem partition (target search path) and the system partition (alternative target search path) of the control (MLPI_PATH_OEM, MLPI_PATH_SYSTEM). The control parses this manifest once at boot up sequence. Changes on the manifest will be recognize only on reboot or if explicitly triggered by the MLPI function m4MApiUserAccountControlReload.
The manifest contains a factory preset of user accounts and permissions, which have to be adapted by the system integrator. The adaption of the user account definition file accounts.xml will be supported by the XML scheme file accounts.xsd, which is located on the system partition of the control (MLPI_PATH_SYSTEM). Use it to simplify editing and to verify the contents of your account configuration.
Note: The development environment IndraWorks uses the account indraworks and needs the factory settings of permissions for faultless operation. A modification of the permissions of this account will block the login to the device from IndraWorks.
The functions groups and the corresponding permissions are documented within the chapter Version and Permission of the corresponding mlpiCore library documentation (e.g. LogicLib: Version and Permission). The function groups of a library can be enabled at once by using the library-global permission key MLPI_*LIB_PERMISSION_ALL.
For setting up a user account on the control refer to the section Permission and user management in the mlpiCore documentation.
Working with the PLC and the I/O configuration
For details of using PLC and I/O configuration refer to the section Working with the PLC and the I/O configuration in the mlpiCore documentation.
Accessing symbolic variables through LogicLib
For details of accessing symbolic variables through the Logic function group refer to the section Accessing symbolic variables through LogicLib in the mlpiCore documentation.
Copyright
Legal notice and version: © 2017 Bosch Rexroth Corporation http://www.boschrexroth.com DC-AE/EAS1 (MGo) Library version: 1.26.2.0.0
