Since version 14 the Commonplace Robotics (CPRog) / igus Robot Control (iRC) can be extended by apps. This repository contains guides, APIs and examples for creating your own apps.
Note that the version of the API that you are using should not be newer than the software version of the robot control, new functions will not work on older robots unless they are updated.
- Simple C++ and Python API
- Runs on the robot control or any other device on the network
- Add new functions to robot programs
- User interface integration into igus Robot Control / CPRog, e.g. for configuration or monitoring
- UI definition via a simple XML structure
- Display message dialogs, e.g. for info or error messages
- Read/write program variables
- Read the robot's state
- Position
- Current cartesian velocity
- Digital IOs and global signals
- Hardware and kinematic error codes
- Referencing state
- Temperatures
- Program states
- etc.
- Read the system info
- Robot software version
- Robot type and owner
- Cycle time statistics
- Axis and IO module count
- etc.
- Initialize the robot
- Enable/disable joints
- Reference joints
- Set velocity of external axes in velocity mode (e.g. conveyors)
- Get/set digital outputs, global signals and digital inputs (including setting digital inputs in simulation)
- Programs
- Load program files
- Start/stop/pause motion and logic programs
- Get/set program variables for parameterizing pre-defined programs
- Define simple programs (not all commands are supported, structural commands are not supported yet). This is intended for defining short motion paths, set IOs and call pre-defined sub-programs.
- Move-To: Move to absolute or relative joint or cartesian positions
- Kinematics
- Transform positions between joint and cartesian values
- Define, list and query user frames
- Tool change
- Files
- Upload/download files
- List files on the robot control (e.g. list all programs)
- Licensing: Query whether a feature is enabled by the robot control's licensing system
- And more...
This is just a summary, please read robotcontrolapp.proto, AppClient.h or AppClient.py for a list of all features.
The following features are planned or considered to be added in future:
- App UI
- Text styling (font size, bold, italic, etc.)
- Multi line text
- Assign icons to the buttons in the ribbon above the 3D view
- Define images to be loaded by the iRC PC software instead of having to send them by the app
- Split Python API into a Python package (currently we recommend copying the files to your project)
The robot control provides a gRPC interface that allows calling functions and transmitting data between the robot control and the app. With the gRPC protocol file robotcontrolapp.proto you can generate the API for several different programming languages. In this repository you will find classes for C++ and Python that you can use for a quick start.
The app configuration file rcapp.xml is used to register the app at the robot control. It defines the binaries or scripts to execute and the functions that are available to the program editor. The app can also run on a different device, e.g. if more performance is required.
The UI definition file ui.xml defines the user interface that integrates into iRC / CPRog using a simple XML structure. UI events are sent to the app and the app can request value and visibility changes.
All files are packed as a zip file that can be installed via iRC / CPRog.
Warning: Apps can run arbitrary code and can cause damage e.g. to the robot control or the network. Only use apps that you trust and do not connect the robot to the internet or your company network if you can avoid it!
The MinimalApp is our example and API (available in C++ and Python) that you can use as a base for your own app. The class AppClient provides a simple interface for the most common functions. Create a class derived from AppClient and override the methods AppFunctionHandler() and UiUpdateHandler(). The former is called when the robot program calls a function of your app, the latter is called on UI events.
Read main.cpp or app.py and class MinimalApp for examples and replace these to create your own robot control app.
The MinimalApp.xml file is a sample robot program that calls the pow function of the sample apps and creates some program variables for the apps to read and write. Observe their values in the variables section below the 3D view.
This app is an example for reading and displaying the robot's state.
This app is an example for controlling a robot via an app.
This app extends the robot control by new math features like calculating the distance between two position variables. With some Python knowledge you should be able to easily extend the robot control's programs with your own functions.
We recommend using the C++ or Python Minimal App as a starting point for your own app.
- Copy the code to a new folder
- Change the name of
MinimalApp.c++/.horMinimalApp.pyand the app's name in these files - Change the app's name in
rcapp.xml - Remove or adapt the examples in
MinimalApp.c++/.horMinimalApp.pyandmain.cpp
Refer to the MinimalApp Readme on how to continue.
See the README.md files and the source code comments in the example directories.
The documentation directory contains further explanations.