Open Core Interface - MLPI
MLPI-MotionLogicProgrammingInterface(mlpi4Java)  1.26.2
Fundamentals of MLPI Programming

About return values

Every MLPI function call returns an integer value of type MLPIRESULT which indicates if the function has succeeded(>=0) or not(<0). The return value is positive or zero if the call has succeeded and negative if the function call has failed. You may want to use either the MLPI_FAILED or the MLPI_SUCCEEDED macro for quick evaluation of the return value.

Example
...
MLPIRESULT result = any mlpi call here...;
if (MLPI_FAILED(result)){
printf("failed with 0x%08x", (unsigned)result);
}else
printf("SUCCESS");
}

In most cases, the return value not only holds information about success or failure, but also information about the cause of a failure. In the mlpi header mlpiGlobal.h, there is a list of definitions with some generic and most likely error codes.

Define Value Description
MLPI_S_OK 0x00360000 Return code "everything okay".
MLPI_E_FAIL 0xF0360001 General error during function call.
MLPI_E_NOTSUPPORTED 0xF0360002 The given function is not supported yet.
MLPI_E_INVALIDARG 0xF0360003 Invalid argument given to method.
MLPI_E_OUTOFMEMORY 0xF0360004 Out of memory.
MLPI_E_TIMEOUT 0xF0360005 Timeout during function call.
MLPI_E_SERVEREXCEPTION 0xF0360006 System exception on control side.
MLPI_E_CONNECTFAILED 0xF0360007 Connection failed.
MLPI_E_CREATEERROR 0xF0360008 Error creating the resource.
MLPI_E_SYSTEMERROR 0xF0360009 System error during execution.
MLPI_E_BUFFERTOOSHORT 0xF036000A Given buffer is too short.
MLPI_E_INVALIDSIGNATURE 0xF036000B Invalid signature.
MLPI_E_STARTERROR 0xF036000C Error during start of functionality.
MLPI_E_WATCHDOGWARNING 0xF036000D Watchdog warning occurred.
MLPI_E_WATCHDOGERROR 0xF536000E Watchdog error occurred.
MLPI_E_UNIMPLEMENTED 0xF036000F The given function is not implemented on this specific device.
MLPI_E_LIMIT_MIN 0xF0360010 The minimum of a limitation is exceeded.
MLPI_E_LIMIT_MAX 0xF0360011 The maximum of a limitation is exceeded.
MLPI_E_VERSION 0xF0360012 Version conflict.
MLPI_E_DEPRECATED 0xF0360013 Deprecated. The lib or function is no longer supported.
MLPI_E_PERMISSION 0xF0360014 Request declined due to missing permission rights.
MLPI_E_TYPE_MISSMATCH 0xF0360015 Type mismatch, present type doesn't match requested type.
MLPI_E_SIZE_MISSMATCH 0xF0360016 Size mismatch, present size doesn't match requested size.
MLPI_E_INVALID_HANDLE 0xF0360017 Invalid handle argument or NULL pointer argument.
MLPI_E_NOCONNECTION 0xF0360018 The connection is not established, no longer established or has been quit by peer.
MLPI_E_RD_WR_PROTECTION 0xF0360019 Request declined due to read or write protection.
MLPI_E_INVALID_FLOATINGPOINT 0xF036001A Invalid floating point numer given to method.
MLPI_E_NOTINITIALIZED 0xF036001B Object not initialized yet.
MLPI_E_STREAM_OUT_OF_SYNC 0xF036001C Send / Receive stream out of synchronization.
MSL_E_INVALID_PRIVATEKEY_FILE 0xF036001D The given private key file is broken or not existing.
MSL_E_INVALID_CERTIFICATE_FILE 0xF036001E The given certificate key file is broken or not existing.
MSL_E_KEYPAIR_MISSMATCH 0xF036001F The given certificate does not match the given private key.
MSL_E_TLS_HANDSHAKE_FAILED 0xF0360020 The TLS handshake was not successful.
MLPI_E_GENERAL_AC_ERROR 0xF0360021 General Access Control Error.
MLPI_E_POLICY_VIOLATION_AC 0xF0360022 A violation in the user policies occurred.
MLPI_E_USER_ALREADY_EXISTS 0xF0360023 The given username is already in use.
MLPI_E_GROUP_ALREADY_EXISTS 0xF0360024 The given groupname is already in use.
MLPI_E_MEMBERSHIP_ALREADY_EXISTS 0xF0360025 The given user is already member of the given group.
MLPI_E_USER_NOT_EXISTING 0xF0360026 The given user does not exist on the control.
MLPI_E_GROUP_NOT_EXISTING 0xF0360027 The given group does not exist on the control.
MLPI_E_MEMBERSHIP_NOT_EXISTING 0xF0360028 The given user is not member of the given group.

Please note that this is not a complete list of all possible return values a MLPI function might return. Besides these common error codes, there are also many device specific error codes. These error codes are specific to the facility (for example, Motion, Logic, sercos, drive...) of the connected device and not directly part of the MLPI. Still, all these error codes are unique and based on the idea that a failure message is a negative value (0xFxxxxxxx) and a success message is a positive value (0x0xxxxxxx). The difference to the errors listed above is that you won't find the description of the error code within this documentation, but within the documentation of the MLPI device you are connected to. For example, if you are connected to a XLC/MLC device, you will probably find more help on the error code by looking into the XLC/MLC diagnostics documentation which is not directly part of the MLPI SDK. In most cases, you will find the documentation included in an IndraWorks installation or you may want to download an up-to-date version from the http://www.boschrexroth.com homepage.

Translating an error code to textual representation
There is another 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 mlpiSystemConvertDiagnosisNumberToText. 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 on the device itself. Below is an example.
Example
...
ULONG myValue = 0;
// try to read a sercos parameter for a device which does not exist. The following line will
// almost certainly return an error code.
MLPIRESULT result = mlpiParameterReadDataUlong(connection, 99, MLPI_SIDN_S(4090), &myValue);
if (MLPI_FAILED(result)) {
// let's try to get a textual description of what went wrong.
// Will only work if still connected to the device.
WCHAR16 description[MLPI_DIAGNOSIS_STRING_LEN] = {0};
if (MLPI_SUCCEEDED(mlpiSystemConvertDiagnosisNumberToText(connection, result, description, _countof(description)))) {
// show the error code and the textual description. :-)
printf("Failed to read parameter with 0x%08X: %s", result, W2A16(description));
}
else {
// we tried, but only have the error code. :-/
printf("Failed to read parameter with 0x%08X and could not retrieve a textual description", (unsigned) result);
}
}

Running this program and having no device with address 99 will result in the following output:

Failed to read parameter with 0xF02D8097: SERCOS, Device does not exist

For more insight into debugging and the system, you may want to have a look at TraceLib and its usage.

See also
TraceLib.

Server versions of MLPI

Each functionality on the client side needs a related functionality on the server side, meaning on the control. The following table shows the implemented server version of the MLPI at a certain firmware version of the control. You can find out the MLPI server version of your control by mlpiApiGetServerCoreVersion. You can read out the firmware version of your control by mlpiSystemGetVersionInfo.

Server version of MLPI Firmware version of control
1.0.16.0 13V02
1.0.20.0 13V04
1.3.2.0 13V06
1.3.2.0 13V08
1.3.2.1 13V08 Patch 4
1.4.0.0 13V10
1.6.5.0 13V12 Patch 1
1.6.5.0 13V14
1.11.3.0 14V06
1.17.0.0 14V18
1.20.0.0 14V20

Client versions of MLPI

The Motion Logic Programming Interface (MLPI) supports a wide range of programming languages and environments. Starting at version 1.17.0, the SDK supports data integrity during communication and management of security services located at the target device. Integrity of the communication data is supported by MLPIS. Management of security services consists of two MLPI libraries named SecurityLib and AccessControlLib.

The following symbols specify the availability of MLPI and MLPIS Communication (see Security in MLPI) and SecurityLib and AccessControlLib.

MLPI Libraries
Library Location Library Communication Libraries
MLPI MLPIS SecurityLib AccessControlLib
mlpiCoreClient mlpiCoreClient\lib win_pharlap-vs2005
X
-
X
X
wince-vs2005sp1-x86
win-vs2005sp1-x86
win-vs2005sp1-x64
vxw69-gcc-ATOMgnu_RTP
android-ndk_gcc-armv7
macosx-xcode-x86_64_i386
ios-xcode-arm64_armv7
ios-xcode-x86_64_i386
ios-xcode-x86_64_i386_arm64_armv7
mlpiCoreClient\bin win_pharlap-vs2005sp1-x86
X
-
X
X
win_pharlap-vs2005sp1-x64
wince-vs2005sp1-x86
win-vs2005sp1-x86
win-vs2005sp1-x64
vxw69-gcc-ATOMgnu_RTP
win-vs2012-x86
X
win-vs2012-x64
linux-lvrt2014_gcc-x64
linux-lvrt2014_gcc-armv7
linux-gcc-x86
linux-gcc-x64
linux-gcc-armv7hf
linux-gcc-armv7
mlpi4Java mlpi4Java\bin win-vs2005sp1-x86
X
-
X
X
win-vs2005sp1-x64
win-vs2012-x86
X
win-vs2012-x64
linux-gcc-x86
linux-gcc-x64
linux-gcc-armv7hf
linux-gcc-armv7
android-ndk_gcc-armv7
mlpi4Lua mlpi4Lua\bin win_luadist-any-x86
X
X
X
X
win-any-x86
win-any-x64
mlpi4COM mlpi4COM\bin wince-vs2005sp1-x86
X
-
-
-
win-vs2005sp1-x86
win-vs2005sp1-x64
mlpi4LabVIEW mlpi4LabVIEW\bin\win-labview2016-any\mlpi4LabVIEW_NativeInterface win_pharlap-vs2005sp1-x86
X
-
X
-
win-vs2005sp1-x86
win-vs2005sp1-x64
win-vs2012-x86
X
win-vs2012-x64
linux-lvrt2014_gcc-x64
linux-lvrt2014_gcc-ARMv7
mlpi4MATLAB mlpi4MATLAB\bin dllmlpiwin32.dll
X
-
-
-
mlpi4Modelica mlpi4Modelica\lib\mlpi4Modelica\Resources\Library win32
X
-
-
-
win64
Symbol Definition
X Supported
- Unsupported