mlpi4MATLAB Toolbox
Trademarks
MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand names may be trademarks or registered trademarks of their respective holders.
Wind River® Workbench and VxWorks® are registered trademarks of Wind River Systems Inc.
Patents
MathWorks products are protected by one or more U.S. patents. Please see www.mathworks.com/patents for more information.
Documentation Overview
*Important Note*
Before you start working with the mlpi4MATLAB toolbox in combination with a real machine, make sure you have read and understood the safety precautions for using electric drives and controls. Safety information is shipped with each device or can be obtained from the device vendor.
Also see Open Core Engineering on the Bosch Rexroth AG website.
Version Information
mlpi4MATLAB toolbox is based on Open Core Engineering SDK. For information about server version of the MLPI and the corresponding firmware version refer to the section Server versions of MLPI.
General License Terms
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: 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
Legal notice and version: © 2017 Bosch Rexroth Corporation http://www.boschrexroth.com DC-AE/EAS1 (MGo) Library version: 1.26.2.0.0
mlpi4MATLAB: Examples
Contents
Preparation
Almost each MLPI function includes an example file that shows how the function can be used in a context. The filenames of these files are m4M*_Sample.m. Many sample files need a particular project configuration in the motion-controller. In the installation folder of the mlpi4MATLAB toolbox you will find in the folder .\mlpi\mlpi4MATLAB\samples\SampleProject an IndraWorks project that has to be used to configure the motion-controller prior to executing sample files. In order to set-up the motion-controller with this project you have to execute the following steps using MLPI functions or IndraWorks in the listed order:
Now the MLPI device is reset to factory settings and can be configured with the sample project. For the following steps you need IndraWorks. Execute the steps in the following order:
- open the sample project (_File/Open/Project)
- enter the correct IP address in the opened project (mouse right click on the control node to open the context menue and select Properties.... Select the tab-sheet Configuration and enter your MLPI device IP address in the corresponding edit field.)
- switch the project online to configure the motion settings (Project/Switch devices online)
- login to the PLC (Debug/Login)
With these operations you reset the motion-controller to factory settings and upload the project configuration. However, with these settings the permission and user management sets the access rights to default which means that most of the MLPI functions can not be accessed. Trying to call an MLPI function like m4MSystemReboot will return an error message. When trying to call example files make sure you use the correct user name and corresponding password as explained below. When using the mlpi4MATLAB toolbox the first time, it is recommended to use an account.xml file that grants full access to all functions. Refer to the section Permission and User Management for details.
These operations will configure the motion-kernel and PLC runtime to be able to execute the sample files properly. The reason why this project configuration is necessary is because the sample files will do things like reading an actual position from an axis which implies that a configured axis is available in the motion controller.
The sample files are kept as simple as possible to show the use of a the corresponding MLPI function but this also means that they are not very fault tolerant.
The structure of each sample is a header cell that contains the function help followed by a section that contains a check if the sample is executed in silent mode. The sample itself is contained in the cell starting with %% sample code. In any case, the cautions must not be ignored.
Note: The sample projects required contains two virtual axis (axis no. 1 and 2) and needs one real axis with the axis number 3 and interpolation in the motion-controller. The motion-contoller is an IndraControl CML45. If your physical configuration is different, the sample files will not work properly. You need to modify your project configuration to fit to this configuration or you have to adapt the sample files according to your personal configuration but the sample files can still be used as templates.
Instructions
A link to the example of the function is included in each function help. Enter the following command in the Command Window to display the function help of the function m4MSystemGetName.
help m4MSystemGetName
The help includes a section Example Files with a hyperlink to open the sample code in the MATLAB editor and a second hyperlink to execute the sample code.
Example Files:
- edit m4MSystemGetName_Sample
- run m4MSystemGetName_Sample(myIP)
In order to execute the sample a MLPI device has to be accessible from MATLAB. Therefore create the variable myIP and assign the IP address of your MLPI device as char array to this variable. Enter the following text in the Command Window while the number between the quotes must be replaced by your IP address.
myIP = '192.168.1.2'
Before executing the example check that the MLPI device is accessible by entering
!ping '192.168.1.2'
A positive ping response indicates that the MLPI device is reachable in in the network. If you have defined a user and a password on the MLPI device - which is the case if you have reset the device to factory settings as mentioned above - you have to indicate it in the char array as well. For example:
myIP = '192.168.1.2 -user=batman -password=gothamcity'
For more details about the connection parameters refer to the help of m4MApiConnect.
Now you can click on the hyperlink following - run in the help text of the function to start the sample. The screen will be cleared and the following text will be prompted by default.
********************************************************
******************* *******************
*************** !!! CAUTION !!! ***************
******************* *******************
********************************************************
Continuing will call a script of MATLAB functions for a
motion-controller. The motion-controller might execute
operations that result in dangerous situations.
Dangerous situations might be:
- movement of axes,
- disabeling safety precautions,
- electrical power on or off,
- hazardous environments,
- other dangerous situations not listed here.
Make sure that safety precautions are installed to prevent
any injuries of human beings or animals as well as damage
of material.
Do NOT continue if insufficient safety mechanisms are
installed.
Use the function 'more on' to execute the sample in
paged mode.
Enter 'Y' to continue or any other input to abort the script:
If you are sure that the execution of the example will not cause a dangerous situation confirm it by entering Y. After confirmation there is a break of 3 seconds during which you can enter CTRL-c to cancel the confirmation again. Then the example script will continue and can hardly be interrupted.
In most examples MATLAB will try to connect to the MLPI device. The example script will prompt all function calls showing which functions are used and the return values of these functions.
Instead of starting the example from within a help function you can simply call the corresponding m-file by entering
m4MSystemGetName_Sample('192.168.1.2')
or
m4MSystemGetName_Sample('192.168.1.2 -timeout_connect=2000 -timeout_send=2000 -timeout_receive=2000')
that avoid to long timeouts.
Important Note
If the MLPI device is accessible in the network but the string provided in myIP is not valid the example will try to connect to this invalid IP address or with invalid connection options. This may result in a locked MATLAB window if the timeout setting is too long. This process cannot be interrupted with CTRL-c so you have to wait until the function returns. It is recommended not to set the timeout value to infinity.
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: Demos
Demos are not yet available.
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: General License
Copyright (c) 2013 Bosch Rexroth. All rights reserved.
Redistribution and use in source and binary forms of this MLPI software (SW) provided to you, with or without modification, are permitted without prior approval provided that the following conditions are met:
- Redistributions of source code of SW must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form of SW must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- User recognizes and acknowledges that it acquires no right, title or interest in or to any of the names or trademarks used in connection with the SW (Names) by virtue of this License and waives any right to or interest in the Names. User recognizes and acknowledges that Names of companies or names or products of companies displayed in the documentation of SW to indicate the interoperability of products with the SW are the Names of their respective owners. The use of such Names in the documentation of SW does not imply any sponsorship, approval, or endorsement by such companies of this product.
- Modified code versions, i.e. any addition to or deletion from the substance or structure of the original code of the SW running the MLPI must be plainly marked as such and must not bemisrepresented as being original SW.
- The SW may only be used in connection with a Bosch Rexroth product.
THIS INFORMATION IS PROVIDED BY BOSCH REXROTH CORPORATION "AS IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING (BUT NOTLIMITED TO) ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, OR NON-INFRINGEMENT. WHILE THE INFORMATION PROVIDED IS BELIEVED TO BE ACCURATE, IT MAY INCLUDE ERRORS OR INACCURACIES. SUBJECT TO COMPULSORY STATUTORY PROVISIONS OF THE GERMAN LAW AS THE APPLICABLE LAW FOR THIS LICENSE BOSCH REXROTH CORPORATION WILL NOT BE LIABLE FOR ANY DAMAGES OF ANY KIND ARISING FROM THE USE OF THE SOFTWARE DISTRIBUTED HEREUNDER, INCLUDING BUT NOT LIMITED TO DIRECT, INDIRECT, INCIDENTAL, PUNITIVE, AND CONSEQUENTIAL DAMAGES.
Copyright
Legal notice and version: © 2017 Bosch Rexroth Corporation http://www.boschrexroth.com DC-AE/EAS1 (MGo) Library version: 1.26.2.0.0
