RoboDK Plug-In Interface
RoboDK Plug-In Interface Introduction

Introduction

This help document is an introduction to develop Plug-Ins for RoboDK. RoboDK Plug-Ins allow extending RoboDK by using the RoboDK Interface and the RoboDK API. Contrary to the default RoboDK API (provided in Python, C#, C++, Matlab, etc), this RoboDK Plug-In interface is linked natively into the core of RoboDK. Therefore, when the RoboDK API is used inside the Plugin Interface (using IItem and IRoboDK) the speed is faster than using the default API Timing tests. However, all RoboDK Plug-In applications must exist within RoboDK's environment.

Some RoboDK Example plugins are available here:

Each example includes the robodk_interface folder. This folder is required by every plug-in and defines the interface to RoboDK.

These examples include a customized robot panel applying robot forward and inverse kinematics, a real-time example, a plugin simulating the gravity and an OPC-UA interface based on Open62541 (Server and Client examples).

Double click the PluginExample.pro file to start the project with Qt. Make sure to follow the installation requirements section (Installation Requirements) to install Qt as a C++ development environment.

RoboDK Plug-In Structure

Plug-In interface (IAppRoboDK)

Each plugin must implement the IAppRoboDK class. The IAppRoboDK defines the interface to the RoboDK application.

Contrary to the standard API, the Plug-In interface allows you to interact with RoboDK's main window and customize the appearance of RoboDK through the IAppRoboDK class. The toolbar, the menu bar and windows can be customized by using the IAppRoboDK class.

plugin-example.png

You can load one of the sample plug-ins by selecting:

  • Tools - Plug-Ins
plugin-load.png

RoboDK API inside a Plug-In

IRoboDK (RoboDK)

The IRoboDK class (or RoboDK) defines the interface to the RoboDK API. This RoboDK API is the same available by default (https://robodk.com/doc/en/RoboDK-API.html#RoboDKAPI). However the RoboDK API is faster when you use it inside a RoboDK Plug-In: Timing tests. When the plugin is loaded using class: IAppRoboDK::PluginLoad it passes a pointer to IRoboDK which is the interface to the RoboDK API.

RoboDK and IRoboDK are exactly the same type of class. RoboDK is used in the default examples to make it compatible with the standard C++ RoboDK API.

More information about the RoboDK API is available here:

IItem (Item)

The IItem class (or Item) can be used to operate on any item available in the RoboDK tree. Use functions such as class: IRoboDK::getItem or class: IRoboDK::getItemList to retrieve items from the RoboDK station tree. Item is a pointer to IItem. Items should be deleted using class: IItem::Delete (not using the class destructor).

More information about the RoboDK Item class (based on the Python API) is available here:

RoboDK types file

The robodktypes.h file defines a set of types used by the RoboDK API. Including:

  • Mat class for Pose manipulations.
  • tJoints class to represent robot joint variables
  • tMatrix2D data structure to represent a variable size 2D matrix (mostly used for internal purposes)

Plug-In Interface vs. RoboDK API

The RoboDK API is a generic set of commands that allows you to interact with RoboDK and automate tasks. The RoboDK API is used by default when macros are used in RoboDK. The RoboDK Plug-In interface includes an interface to the RoboDK API.

The main advantages of using the RoboDK API through a Plug-In Inteface are the following:

  • The RoboDK API is much faster because it is loaded as a library (a RoboDK Plug-In is actually a library loaded by RoboDK).
  • You can customize the appearance of RoboDK's main window (including the menu, toolbar, and add docked windows).

You should pay attention to the following when using the RoboDK API inside a Plug-In:

  • Items (Item/IItem) are pointers, not objects. You can check if an item is valid or not by checking if it is a null pointer (nullptr). More information here: ItemValid.
  • You must call class: IRoboDK::Render every time you want to update the screen (for example, if you change the position of a robot using class: IItem::Joints). Updading the screen is not done automatically.
  • Plug-Ins can only be deployed as C++ code using Qt libraries.

Timing tests

The PluginExample application shows how to implement a basic plugin. Among other things it performs some timing tests to calculate the speed of RoboDK on a specific computer. By selecting the "Plugin Speed Information" button you'll obtain the timing statistics.

sampleoutput.png

These statistics are generated by class: PluginExample::callback_information. For example, forward and inverse kinematics are usually under 2 micro seconds and 10 micro seconds respectively (1 micro second = 1e-6 seconds).

Requirements

Each RoboDK Plug-In must be developed using the Qt Creator and follow Qt's project guidelines. It is recommended to use the PluginExample project to get started with your new RoboDK Plug-In (double click PluginExample.pro to open it with Qt Creator).

RoboDK must be installed to develop Plug-Ins. The free version of RoboDK is enough to develop a Plug-In as a proof of concept.

Installation Requirements

Requirements to make RoboDK Plug-Ins work:

  • It is required to install RoboDK (v3.5.4 or later): https://robodk.com/download
  • Make sure you properly run your plugin using the following version of Qt:
    • Qt version 5.11.2 on Windows. Make sure to use Qt built for MSVC2017.
    • Qt version 5.12 on Mac.
    • Qt version 5.12 on Linux.
  • It is possible to run in Run in Debug mode debug mode on Windows.
qttoolkit.png
  • Place your plugin files in the folder: C:/RoboDK/bin/plugins/ (DLL files). This is set by default in the PluginExample.pro file (as shown in the following image)
  • Start RoboDK (C:/RoboDK/bin/RoboDK.exe) and pass the command line argument: -PLUGINSLOAD as shown in the following image.
    • Alternatively, you can pass the argument "-PLUGINLOAD=path-to-your-plugin.dll" if the DLL is not placed in the default path. The value can be the path to the library, the name of the file in the plugins folder or the name of the plugin (PluginName).
    • You can also start RoboDK using the BAT file: C:/RoboDK/RoboDK-Allow-Plugins.bat. The example plugins will be displayed.
    • Select Tools-Plug-Ins for more options. Future RoboDK versions of RoboDK will load plugins located in C:/RoboDK/bin/plugins automatically
  • For development purposes, make sure to start the plugin with RoboDK and pass the -PLUGINSLOAD argument as shown in the following image.
    You can load one of the sample plug-ins by selecting:
  • Tools - Plug-Ins

The default location for RoboDK plugins is C:/RoboDK/bin/plugins

qtrun.png

Run in Debug mode

Your Plug-In release and debug binaries should not be mixed with RoboDK's release and debug binaries. RoboDK debug binaries are not provided by default.

To properly run your plugin in debug mode you should use the RoboDK debug binary files:

  • Contact us to get the debug version of RoboDK (bind folder).
  • Unzip the bind folder in C:/RoboDK/bind/.
  • Select Projects-Run-Run Settings and set Executable to C:/RoboDK/bind/RoboDK.exe (as shown in the following image, don't forget the d).

Important: Mixing a debug DLL with a release DLL will not work (a message will be provided as console output). Make sure you update this setting every time you switch debug and release modes.

Important: If you experience strange plugin loading issues, try to delete all plugins and build them again (all files in C:/RoboDK/bin/plugins and C:/RoboDK/bind/plugins).

plugin-run-debug-setting.jpg
  • Select the Debug build and you can start debugging as usual.
plugin-debug-example.jpg

Qt Tips

RoboDK Plug-Ins must be created using the Qt Plugin Framework. Qt is based on C++, therefore, it is required to program the RoboDK Plug-In in C++.

Qt is a set of useful libraries for C++ and Qt Creator is the default development environment (IDE) for Qt. We recommneded using Qt Creator as development environment for programming a RoboDK Plug-In.

This list provides some useful links and tips for programming with Qt:

  • Double click the PluginExample.pro file to open the example project using Qt Creator.
  • Use Qt signal/slots mechanism for action/button callbacks (http://doc.qt.io/qt-5/signalsandslots.html). Signals and slots are thread safe.
  • Wrap your strings using tr("your string") or QObject::tr("your string") to allow translation using Qt Linguist. For more information: http://doc.qt.io/qt-5/qtlinguist-index.html.
  • If you experience strange build issues it may be useful to delete the build folder that is automatically created to force a new build.
  • If you experience strange plugin load issues in RoboDK it is recommended to delete the libraries and create the plugin library with a new build.
  • More information about Qt: https://www.qt.io/.

Useful Links

Useful links involving the RoboDK API: