Universal Robots Client Library

The library provides several ways to interact with Universal Robots:

• RTDE Interface: Fully supported via the RTDEClient. This is the primary method used by the ROS/ROS 2 drivers.
• Dashboard Interface: Access the Dashboard server directly through helper functions.
• Custom Motion Streaming: Supports data streaming through custom sockets for motion command streaming.
• Primary/Secondary Interface: Limited support. The PrimaryClient does not support all features, and package parsing is not implemented for most packages. You can use comm::URStream to open a connection and send data, or use the producer/consumer pipeline (see examples/primary_pipeline.cpp).

When using SPLINE trajectory points, you can achieve higher precision for velocities and accelerations using the MULT_VEL_ACC multiplier (1e-8 resolution).

Requirements for High Precision:

• The robot's control script must define the matching multiplier using the {{VEL_ACC_REPLACE}} placeholder.
• If this placeholder is not present in the user-supplied script, the library falls back to using MULT_JOINTSTATE for encoding spline velocities and accelerations.

Warning: Using the coarser MULT_JOINTSTATE scaling for spline velocities/accelerations can cause quantized, jagged acceleration profiles, which may trigger controller faults. Values exceeding the maximum magnitude (~21.47 rad/s or rad/s²) are rejected by the library.

The library uses a producer/consumer architecture to handle data streams from the robot.

1. Producer: Reads data from a stream, parses that data, and places it into a queue.
2. Consumer: Reads data from the queue and performs its intended task (e.g., logging, processing, or executing commands).
3. Pipeline: Orchestrates the connection between a producer and a consumer. You can optionally provide an INotifier to handle pipeline start and stop events.

The ScriptCommandInterface allows you to send predefined commands to a Universal Robot while a URScript (such as external_control.urscript) is actively running and connected to the robot.

To use this interface effectively, you must ensure that the robot is running a script that establishes a connection to the ScriptCommandInterface. In a typical driver setup, the UrDriver forwards calls from the ScriptCommandInterface to the robot.

Because the script command connection is part of the larger external control loop, you must maintain the connection by sending regular keepalive signals (often handled by the driver's control loop) to prevent the script from terminating.

// Example of accessing the interface via the driver
g_my_robot->getUrDriver()->zeroFTSensor();

Direct torque control mode (available since PolyScope 5.23.0 / 10.10.0) allows commanding joint torques directly to the robot using control mode 8 (TORQUE).

Key details:

• Gravity Compensation: Target torques are provided after gravity compensation. A vector of zeros will maintain the current position if the payload is correctly known to the controller.
• Safety Warning: This is a very low-level interface. High torques in free space can cause rapid, unexpected movement that may trigger safety faults (joint velocity or TCP speed violations).

The ReverseInterface class opens a TCP port to implement a custom protocol between the robot and the control PC. It is primarily used for high-frequency motion command streaming, such as sending joint positions or velocities.

To use ReverseInterface in an application, you must ensure a corresponding URScript is running on the robot to interpret the incoming commands. A reference implementation can be found in the external_control.urscript resource.

Depending on the selected control mode, you use different methods to send data:

• write(): Used for SERVOJ, SPEEDJ, SPEEDL, POSE, and TORQUE modes.
• writeTrajectoryControlMessage(): Used for FORWARD (trajectory interpolation) mode.
• writeFreedriveControlMessage(): Used for FREEDRIVE mode.

The TrajectoryPointInterface is used to transfer trajectory points from an external control PC to the robot for execution. It is designed to be used alongside the ReverseInterface during trajectory forwarding.

Workflow:

1. The TrajectoryPointInterface forwards trajectory points to the robot.
2. Execution is triggered by sending a start command via the ReverseInterface.
3. Once execution completes (success, failure, or external cancellation), the robot sends a response back to the control PC via the trajectory socket.

Important Constraints:

• The interface simply forwards points; the robot executes them using standard URScript functions like movej or movel.
• All parameters and restrictions of those URScript functions apply. For example, if a segment duration (time) > 0 is provided, velocity and acceleration parameters will be ignored.

While multiple clients can connect to a robot, only one client is permitted to write data. To create a client that only reads data, initialize the RTDEClient with an empty input recipe. This can be done by passing an empty list of strings or an empty filename string.

Note that when using a read-only client, all attempts to use the RTDEWriter will return false.

// Create with an empty input recipe (read-only)
rtde_interface::RTDEClient my_client(ROBOT_IP, notifier, OUTPUT_RECIPE, {});

// Alternatively, using an empty filename
// rtde_interface::RTDEClient my_client(ROBOT_IP, notifier, OUTPUT_RECIPE_FILE, "");

my_client.init();
auto data_pkg = std::make_unique<rtde_interface::DataPackage>(my_client->getOutputRecipe());
my_client.start();

while (true)
{
  if (my_client.getDataPackage(data_pkg, READ_TIMEOUT))
  {
    std::cout << data_pkg->toString() << std::endl;
  }
}

Communication with the primary/secondary and RTDE interfaces follows a producer/consumer pattern:

• Producer: Reads data from the socket, parses the contents, and stores parsed packages into a pipeline queue.
• Consumer: You can implement custom consumers to process the packages provided by the producer.

An example of a consumer implementation can be found in include/ur_client_library/comm/shell_consumer.h.

To ensure reliable operation and prevent missing RTDE messages, it is critical to use real-time scheduling:

1. RTDE Receive Thread: This thread is automatically scheduled with real-time priority if the system allows. If it fails, an error is raised at startup.
2. Application Thread: The main thread calling getDataPackage() must be manually scheduled with real-time priority by your application.

Refer to doc/real_time.rst for detailed setup instructions.