Authors: Martin Rytter and Ebbe Overgaard Fuglsang
Authors: Martin Rytter and Ebbe Overgaard Fuglsang
Client libraries are software packages that you can use to monitor or control a cobot.
You can use client libraries to build software that runs on a normal computer, an industrial PC or any other external hardware that has an ethernet connection to the cobot.
It’s also possible to use client libraries when developing software packaged as a URCap. In this case your software is still running on the cobot, but the use of the client library is the same.
We will also look at a ROS driver, which is special kind of client library designed to monitor and control a cobot from a ROS system.
In most cases you don’t need a client library. Things are usually simplest when you can connect all necessary equipment to your robot using normal IOs and fieldbusses, and when you can control everything from your robot program on the teach pendant. In this case you can avoid expensive hardware and avoid the complexity of integrations.
However, there are situations where client libraries are practical or even necessary:
External monitoring and modification of registers while a robot program is running. This scenario allows an external process to participate while the user is still starting and stopping programs using the teach pendant. All communication takes the form of reading and writing registers. An example could be an external vision system for part detection that continuously updates a register with the best pickup position. It’s a common pattern for URCaps to include a process that monitor and modify registers while a robot program is running.
External loading, starting and stopping of programs. This scenario allows an external process control what program a robot is using. This is sometimes practical when the robot is controlled from an external user interface. An example of this could be a simple external user interface that allow the user to choose between parts and then load the appropriate program into the robot.
External motion control. This scenario allows an external process to continuously send new motions for the robot to perform. This is an advanced use case that is only needed by a few applications. An example could be a bin picking application that uses an external path planning component.
In summary, if you are developing an external software with a need to a) monitor or modify registers, b) control loading, start and stopping, or c) control motion, then you want to consider a client library.
Are you making your external software in C++? If yes, then we recommend these client libraries:
Universal Robots Client Library for C++. This is a powerful library that covers all the usage scenarios discussed in the previous section. Its development is sponsored by Universal Robots and developed in collaboration with FZI. Library, documentation and examples are available on GITHub: https://github.com/UniversalRobots/Universal_Robots_Client_Library
Universal Robots ROS2 Driver. This ROS2 driver is developed on top of the Universal Robots Client Library and it is maintained by the same group of people. Library, documentation and examples are available on GITHub: https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver
If you can use one of the libraries above, then you are probably good to go. However, there are more libraries out there. You might encounter some of these libraries in older software, but there can also be reasons to use them in new projects.
RTDE libraries only implement the Realtime Data Exchange protocol. You can use these if your only need is monitoring and modifying registers:
RTDE Client Library is a Python-based library provided by Universal Robots. It’s been around for a long time. It works on all E-series robots and CB3 robots with SW 3.4 or newer. The software is available on GITHub: https://github.com/UniversalRobots/RTDE_Python_Client_Library. Supplementary documentation is available here: https://www.universal-robots.com/articles/ur/interface-communication/real-time-data-exchange-rtde-guide/.
UR RTDE is a library developed at University of Southern Denmark. It is based on C++ and bindings for Python are also available. The library is available on Github: https://gitlab.com/sdurobotics/ur_rtde
Dashboard server is a protocol you can use to load, start and stop programs. You might encouter libraries that implement both RTDE and Dashboard server protocols:
Sintef Client Library is a library implemented at the Norwegian company Siftef. It supports both RTDE and Dashboard server. It’s based on Python and is available on Github: https://github.com/SintefManufacturing/python-urx
These are probably the most widely used libraries right now. Please let us know if there is something new and exciting out there that we should pay attention to. We love developers coming up with new things.
We recommend that you first try one of the libraries above. However, you are also free to develop your own. If you decide to follow that path, then you want to study the protocols that your library will use to communicate with the robot. The most important protocols are:
RTDE (Realtime Data Exhange) on TCP port 30004 for monitoring and controlling registers. Find more information here: https://www.universal-robots.com/articles/ur/interface-communication/real-time-data-exchange-rtde-guide/
Dashboard server on TCP port 29999 for loading, starting and stopping programs. Find more information here: https://www.universal-robots.com/articles/ur/dashboard-server-e-series-port-29999/
Interpreter mode on TCP port 30020 for motion control. Find more information here: https://www.universal-robots.com/articles/ur/programming/interpreter-mode/
Primary, secondary and real-time interfaces are based on a protocol that can do a lot of different things. They areIused inside UR’s software for communication between the user interface part and the control part of the software. Anyone can use them, but they are not the simplest thing to use, and please don’t make too strong assumptions about what this protocol can do in the future. Find more information here: https://www.universal-robots.com/articles/ur/interface-communication/remote-control-via-tcpip/
If you need to monitor or control the cobot using a programming language not supported by the available libraries, or if you have a very special need, them it can make sense to use one of these protocols to develop your own library. However, remember that most people have the same problems most of the time. If you’re like the most of us, we’re probably better off using a tried and tested library.
Before we end it is important to mention the UR forum (https://forum.universal-robots.com/). Here you will find developers that have used or contributed to the libraries we discussed in this article. Everyone is friendly and wants to help, so don’t hesitate to post your question.