RoboDK API

RoboDK API

The RoboDK API (Application Program Interface) is a set of routines and commands that RoboDK exposes through a programming language which allow programming any robot using a unique programming language.

Compared to vendor-specific robot programming, with the RoboDK API it is possible to simulate and program any robot using a unique/universal programming language such as Python. The main page provides an overview and a video showing offline programming with the API.

The RoboDK API is available for Python, C# and Matlab. Any of these programming languages can be used to simulate and program any robot.

Tip: Are you unsure of what programming language to use? We recommend using Python! If you installed RoboDK using the default settings you already have Python installed and you are ready to start. Python is a widely used high-level programming language for general-purpose programming. Most RoboDK examples and documentation are based on Python programs.

Note: RoboDK provides a user friendly Graphical User Interface (GUI) to simulate and program industrial robots. Programming experience is not required to simulate and program robots using the GUI. The Program section provides more information about programming robots using the GUI. On the other hand, by using the RoboDK API there are no limitations for simulation and offline programming.

Note: The API can be implemented in any programming language. The API consists of a TCP/IP protocol implemented in RoboDK. When RoboDK is running it behaves like a server and it exposes a set of commands through TCP/IP protocol.

The RoboDK API can be used for the following tasks:

1.    Automate the simulation: Create macros to automate specific tasks within the RoboDK simulator, such as moving objects, reference frames or robots.

2.    Offline programming: Programming robots offline from a universal programming language. RoboDK will generate specific programs for a specific robot controller when the API is used (such as a program in Python or C#). The robot program is generated according to the post processor selected for a specific robot. The Offline Programming with Python section of this document provides more information and examples.

3.    Online Programming: Programming robots online using a universal programming language: It is possible to move robots and retrieve their current position from the RoboDK API. RoboDK will drive the robots using robot drivers. The Online Programming with Python section in this document provides more information and examples.

In other words, the same program that is used for simulation (1) can be used to generate robot programs (2, Offline Programming) and to move the robot in real time (3, Online Programming).

Note: When the robot simulation is created from a generic programming language using the RoboDK API, the robot motion commands are automatically used to generate programs offline when the simulation is ready. Furthermore, the same program can be used to move the robot in real time if the robot is connected using the robot driver.

This document covers the following topics:

o   The Python API with examples for Simulation, Offline Programming and Online Programming

o   The C# API with examples for Simulation, Offline Programming and Online Programming

o   The Matlab API with a Simulink example for simulation

o   The Command line options to start RoboDK

Note: This document does not cover the Post Processors, required for offline programming.

Note: This document does not cover the Robot Drivers, required for online programming.


 

Python API

Python is a widely used high-level programming language for general-purpose programming. Python is a programming language that lets you work faster and integrate your systems more effectively. Python's syntax allows programmers to express concepts in fewer lines of code compared to other languages, making it friendly and easy to learn.

The previous section explains the advantages of using the RoboDK API with a widely used programming language for robot programming such as Python.

Python is automatically installed and integrated with RoboDK by default. Select ToolsOptionsOther to change the default settings (Python location and Python Editor).

Tip: It is possible to use a specific text editor other than the Python IDLE (used by default), such as Notepad++ or PyCharm. Enter the location of the text editor as shown in the following image.

The RoboDK API for Python is divided in the following two modules:

o   The robolink module (robolink.py): The robolink module is the interface between RoboDK and Python. Any object in the RoboDK Station Tree can be retrieved using a Robolink object and it is represented by the Item object. It is possible to perform different operations on that item according to the Robolink.Item class.

o   The robodk module (robodk.py): The robodk module is a robotics toolbox for Python that allow operating with pose transformations and obtain Euler angles for different robot vendors. All post processors depend on this robodk module.

The Python modules are located in the folder C:/RoboDK/Python/ and they are copied to the Python folder path automatically when RoboDK is installed or when Set default Python settings is selected (see previous image).

The following subsections show how to create a simple program for simulation, offline programming and online programming respectively. More examples are available in the Python API for RoboDK page. Also, the RoboDK library comes with sample Python macros in the folder C:/RoboDK/Library/Macros/.


 

Python Simulation

Follow these steps to set up a sample project using a UR robot and simulate a movement with the robot.

1.    Select File Open

2.    Open the UR10 robot

3.    Select File Open

4.    Open the Paint_gun.tool file

5.    Open the sample Python program SampleOfflineProgramming.py from C:/RoboDK/Library/Macros/

Tip: More information to set up a RoboDK station in the Getting started section.

Tip: Select ProgramAdd Python program to create a new Python program.

6.    Double click the SampleOfflineProgramming item to run the simulation. The robot should draw a hexagon around the current location of the robot and the trace of the TCP will be displayed in yellow.           
Alternatively, right click the program and select Run Python Script.

7.    Right click the  SampleOfflineProgramming item and select Edit Python Script. We should see the program as shown in the following image.

The SampleOfflineProgramming macro will draw a polygon of side n_sides and radius R at the current location of the robot, with respect to the robot reference frame. If desired, move the robot to a different location changing the polygon dimensions and re-run the program.

This example is similar to the program displayed in the offline programming section of the website (video included).

Tip: It is possible to run a program from the Python editor by selecting RunRun. A new window will appear showing all the print commands or any errors.


 

Python OLP

Python programs can be generated offline using the same Python code used to simulate the robot (as shown in the previous Python Simulation section). Offline Programming allows generating robot programs that can be executed on a specific robot controller:

1.    Right click a Python program

2.    Select Generate robot program (F6)

In this case the program is not simulated but executed quickly to obtain the result: a robot program specific to a robot controller.

Tip: Right click a robot and select Select Post Processor to specify a different post processor for offline programming (as shown in the Post Processor section).

 

Note: The Generate robot program option will automatically set the RunMode of the RDK/Robolink connection to RUNMODE_MAKE_ROBOTPROG. In other words, it is possible to programmatically generate the vendor-specific program instead of simulating it if the Python program is being executed outside of RoboDK’s GUI. For example:

RDK = Robolink()

RDK.setRunMode(RUNMODE_MAKE_ROBOTPROG)


 

Python Online Programming

Python programs can be directly executed on the robot using the same Python code used to simulate the robot (as shown in the Python Simulation section). Online programming allows running a generic program on a specific robot controller using Robot Drivers:

1.    Right click a Python program

2.    Select Run on robot

The program will run on the robot as it the Python program is executed.

Important: A connection between the PC and the robot is required by using Robot Drivers (right click a robot, then, select Connect to robot…). More information in the Robot Drivers section.

Note: The Run on robot option will automatically set the RunMode of the RDK/Robolink connection to RUNMODE_RUN_ROBOT. In other words, it is possible to run the robot movement commands outside the RoboDK’s GUI. For example:

RDK = Robolink()

RDK.setRunMode(RUNMODE_RUN_ROBOT)

Tip: The macro SampleOnlineProgramming.py from the C:/RoboDK/Library/Macros/ folder provides a full example to test it with the same hexagonal path used in the Python simulation section.

Note: More information about using robot drivers through the API in the Robot Drivers section.


 

C# API

C# (pronounced "C sharp") is a programming language developed by Microsoft and designed for building a variety of applications that run on the .NET Framework. C# is simple, powerful, type-safe, and object-oriented.

The main section of this document explains the advantages of using the RoboDK API with a widely used programming language such as C# for robot programming.

The RoboDK API for C# is a RoboDK.cs source file that contains the RoboDK class (similar to Python’s Robolink class), the RoboDK.Item class (similar to Python’s Robolink.Item class API), and other tools for robotics such as a Matrix class (RoboDK.Mat) for matrix operations to operate with pose transformations.

The RoboDK API for C# is provided with a sample project as shown in the following image (the complete source code is included).

Select Load File to open a RoboDK station or any other file supported by RoboDK. If a robot is loaded, the ROBOT variable will be updated accordingly (same as using Select Robot).

The following video shows an overview of the C# sample project using the RoboDK API:
https://www.youtube.com/watch?v=1hRRYr9bEsY

Note: Microsoft Visual Studio is required to load and run the sample project. The Visual Studio Community (Express) version is free.


 

C# Simulation

C# programs are simulated by default when robot commands are used (such as MoveJ, MoveL or setDO). When the sample C# project is started, the simulation mode is also selected by default.

This means the robot movements will be simulated in RoboDK. For example, we can move the robot by steps of 10 mm selecting the buttons on the right (+Tx, -Tx, …), or we can select Run Test Program to run a hexagonal movement around the current location of the robot.

Set any breakpoints to debug your application and inspect robot targets. Robot targets can be defined as joint coordinates or Mat variables (4x4 pose Matrices) and they can be inspected as XYZWPR format to troubleshoot program issues. More information about reference frames in the Reference Frames section.

It is also possible to change the Run Mode to Offline Programming or Online Programming (Run on Robot), as shown in the following sections.


 

C# OLP

C# programs can be generated offline using the same C# code used to simulate the robot (Offline Programming). Follow these steps to test this feature:

1.    Select Offline Programming in the Run Mode section

2.    Select Run Test Program or any other combination of movements

3.    Select Generate Prog to obtain the vendor-specific robot program

In this case the program is not simulated but quickly executed to obtain the result: a robot program specific to a robot controller. The Run Mode will be changed back to Simulation once the program is generated.

Tip: Right click a robot and select Select Post Processor to specify a different post processor for offline programming (as shown in the Post Processor section).

Note: The robot will not move when the Offline Programming mode is active as this changes the RunMode to RUNMODE_MAKE_ROBOTPROG, as shown in the Python OLP section.


 

C# Online Programming

C# programs can be directly executed on the robot using the same C# code used for simulation. Online programming allows running a generic program on a specific robot controller using Robot Drivers. Follow these steps to test this feature using the C# sample project:

1.    Select Run on Robot in the Run Mode section

2.    Select any other commands that will make a robot move

The movements will run on the real robot and the simulator will synchronize the movements with the robot.

Important: A connection between the PC and the robot is required by using Robot Drivers (right click a robot, then, select Connect to robot…). More information in the Robot Drivers section.

Note: The RunMode of the RDK/Robolink connection is changed to RUNMODE_RUN_ROBOT so that the movements can be executed on the robot. Example:

RDK = Robolink();

RDK.setRunMode(RUNMODE_RUN_ROBOT);

Tip: The macro SampleOnlineProgramming.py from the C:/RoboDK/Library/Macros/ folder provides a Python example for online programming outside the RoboDK GUI.

Note: More information about using robot drivers through the API in the Robot Drivers section.


 

Matlab API

Matlab is a proprietary programming language developed by MathWorks. Among other things, MATLAB allows matrix manipulations, plotting of functions and data and implementation of algorithms.

The main section of this document explains the advantages of using the RoboDK API with a widely used programming language such as Matlab for robot programming.

The RoboDK API for Matlab is available after RoboDK is installed in C:/RoboDK/Matlab/. The API is provided as a set of m files, including:

o   Robolink.m is a class that interfaces with RoboDK. Any object in the RoboDK Station Tree can be retrieved using the Robolink object and it is represented by the RobolinkItem object (same as Python’s Robolink class).

o   RobolinkItem.m is a class that represents a RoboDK item in the Station Tree. It is possible to perform different operations on that item (same as Python’s Robolink.Item class).

o   transl.m, rotx.m, roty.m and rotz.m are functions that create pose matrices given an XYZ translation vector or rotations along a specific axis.

o   Pose_2_XYZRPW.m an XYZRPW_2_Pose.m allow converting poses to XYZ position and RPW Euler angles and vice versa. More information in the Reference Frames section.

Sample code is available in the following page:       
https://robodk.com/Matlab-API

Simulink Example

A Simulink project is available as an example. In the simulation, the robot is moved along a set of XYZ coordinates generated arbitrarily.

The following video shows the result of running the simulation:       
https://www.youtube.com/watch?v=7DDBMwa0-Oc


Command Line Options

This section describes the command line options available when RoboDK is started.

The following call is a generic call with some arguments:

Robodk.exe /[option1] /[option2] open_fileA /[option3] open_fileB ...

All file formats supported by RoboDK can be provided as arguments. Including the following formats:

o   RDK    ➔ RoboDK station file: This file holds a whole project in one file, including any dependencies (robots, tools, NC files, …).

o   robot    ➔ Robot file: Loading a robot file will also create a reference frame for that robot.

o   tool      ➔ Tool file: Automatically attached to the last robot added.

o   stl/wrl/step/stp/iges/igs/sld ➔ Object (3D geometry): Objects can easily be converted to tools.

o   apt/gcode/cnc ➔ NC program file: RoboDK automatically prepares a milling project (Utilities➔Milling Project).

Important: NC files will be linked to the active reference frame and tool reference frame in the RoboDK station.

Note: It is possible to start RoboDK from the API by passing some arguments. Example using the Python API:

RDK = Robolink(args='/ADDFRAME "/RENAME=Main Ref " load_object.stl')

Available command line Options:

/NOSPLASH

Removes the RoboDK splash image on start.

/DEBUG

Creates a RoboDK.debug.txt file in the bin folder that allows debugging the application.

/SETTINGS=filepath

Loads the arguments from a text file. Each line of that text file is considered as a one single argument.

/NOSHOW

Hides all windows while RoboDK is loading files and updating programs.

/NO_WINDOWS

Hides all windows that are usually shown automatically when loading an NC file.

/PORT=20501

Forces the API communication through the given port (TCP/IP protocol). Default port is 20500.

/ADDFRAME

Adds a new reference frame. Any new objects loaded will be placed in this reference frame.

/RESET

Forces that if a new object is loaded it will be placed at the station reference frame (not the last added frame).

/RENAME=Name

Changes the name of the last reference frame or object that was added.

/MOVE=x;y;z;rx;ry;rz

Moves the last reference frame that was added (in mm and degrees).

/UPDATE_APT=YES

Will override any robot machining projects that have the same APT file

/UPDATE_APT=NO

Does not override any robot machining projects (will create duplicate projects if there is a name match).

/UPDATE=file.apt

Loads or updates the APT file and generates the robot program if there are no issues.

/REPLACE_ITEMS=YES

Updates existing tools and objects when new files are loaded and there is a name match.

/REPLACE_ITEMS=NO

Never overrides tools and objects when new files are loaded.

/SETCOLOR=steelblue

Set the color of the last loaded object (object, tool, robot or mechanism). The color can be a named color or a hexadecimal color.

Note: It is not possible to select objects with more than 50% transparency using a single click.

 

/AUTOGEN_MAINPROG=Prog

Generates a main program that calls the programs linked to loaded APT files sequentially.

/SELECTTOOL=#1

Set the first robot tool (or corresponding number) available as the active tool (the tool used when a new program is loaded).

/SELECTTOOL=tool name

Select the active tool using a name match.

/ADDCUTTER=length|path/cutter name.stl

Addcutter allows adding the geometry of a cutter with respect to a tool holder. A cutter is treated as a tool in RoboDK, holding the geometry of the cutter. The geometry of the cutter must be an STL file (ASCII or binary) with the origin at the tip of the tool. The length must be given in mm with respect to the tool holder (the positive Z axis of the tool holder must point outside).

/SELECTCUTTER=cutter name

Selectcutter has the same effect as SELECTTOOL, cutters are treated as tools.

/SHOW

Shows the RoboDK window. This is automatically done when all files have been loaded and machining projects have been updated.

Using one of the following options will alter the visibility provoked by the /SHOW command.

/HIDDEN

Avoids the automatic /SHOW once RoboDK has finished loading. The only way of showing the window afterwards is by using the API.

/QUIT

Exits the program if there are no error messages.

/END

Exits the program even if there are any error messages.