This repo is a module that implements the rdk:component:arm API resource to allow control over Universal Robots arms. Currently the following models are supported:
- UR3e, as
viam:universal-robots:ur3e - UR5e, as
viam:universal-robots:ur5e - UR7e, as
viam:universal-robots:ur7e - UR20, as
viam:universal-robots:ur20
This model can be used to control a universal robots arm from a machine running a viam-server. We recommend that the machine running the viam-server is using a wired ethernet connection for the best performance of this module. The following attribute template can be used to configure this model:
{
"host": <arm ip address string>,
"speed_degs_per_sec": <float or 6-element array>,
"acceleration_degs_per_sec2": <float or 6-element array>
}The following attributes are available for viam:universal-robots arms:
| Name | Type | Inclusion | Description |
|---|---|---|---|
host |
string | Required | The IP address of the robot arm on your network. Find this in the network settings on the arm's teach pendant. |
speed_degs_per_sec |
float or array | Required | Set the maximum desired speed of the arm joints in degrees per second. Can be a single value (applied to all joints) or a 6-element array for per-joint limits. |
acceleration_degs_per_sec2 |
float or array | Required | Set the maximum desired acceleration of the arm joints. Can be a single value (applied to all joints) or a 6-element array for per-joint limits. |
max_trajectory_duration_secs |
float | Optional | Maximum allowed trajectory duration in seconds. Trajectories exceeding this duration will be rejected. Default 600s (range: 0.1 - 3600) |
trajectory_sampling_freq_hz |
float | Optional | Sampling frequency for trajectory generation in Hz. Higher values produce smoother trajectories but require more computation. Default 10 Hz (range: 1 - 500) |
path_tolerance_delta_deg |
float | Optional | Tolerance for path waypoint deviations in degrees. Used during trajectory generation to smooth paths while staying within tolerance. Default 5.73 degrees (0.1 radians) (range: > 0, <= 12) |
reject_move_request_threshold_deg |
float | Optional, but required for streaming moves | Rejects move requests when the difference between the current position and first waypoint is above threshold |
stream_limit_tolerance_ratio |
float | Optional | Factor by which the velocities and accelerations on streamed trajectory points may exceed the configured speed_degs_per_sec and acceleration_degs_per_sec2 limits, to allow for slight numerical drift from the planner. A point that exceeds a limit stops the streamed move. Must be >= 1. Default 1.01 |
robot_control_freq_hz |
float | Optional | Sets the processing frequency for communication with the arm in cycles/second. If the machine running this model is using WiFi, we recommend configuring this to a lower frequency, such as 10 Hz. Default 100 Hz |
segmentation_threshold |
float | Optional | Threshold for detecting direction reversals (cusps) in waypoint paths. The trajectory planner segments the path at points where the cosine similarity between consecutive direction vectors is close to -1 (i.e. |dot(ab, bc) + 1| < threshold). Lower values detect only sharp reversals; higher values are more sensitive. Default 0.005 (range: > 0, <= 0.01) |
enable_new_trajectory_planner |
bool | Optional | Enables the trajex/TOTG trajectory generator. Default true |
enable_legacy_trajectory_planner |
bool | Optional | Enables the legacy trajectory generator. When enable_new_trajectory_planner is also true, the legacy generator is only used if the new one fails to produce a trajectory. At least one of the two generators must be enabled. Default false |
prefer_precomputed_accelerations |
bool | Optional | When true, trajectory points are sent to the robot with precomputed accelerations from the TOTG planner, enabling higher-order spline interpolation and continuous acceleration at waypoints. Only takes effect when enable_new_trajectory_planner is also true. Default true |
worker_sched_fifo_priority |
bool or int | Optional | Runs the arm worker thread under SCHED_FIFO real-time scheduling. Set to true to use the module's default priority of 90, which is the recommended setting. Set to an integer from 1 to 99 to choose the priority yourself, for example 99 on a host with enough cores that the worker and the UR client library's RTDE reader thread can each run on their own core. Intended for Linux hosts. This requires real-time scheduling privileges for the module process (root, CAP_SYS_NICE, or a sufficient RLIMIT_RTPRIO). If the request fails, the module logs a warning and continues with default scheduling. A PREEMPT_RT kernel is recommended but not required. Default false |
telemetry_output_path |
string | Optional | Path for writing telemetry data files (waypoints, trajectories, joint positions, failure diagnostics). Files are written in CSV and JSON formats with ISO8601 timestamps. Default: VIAM_MODULE_DATA environment variable |
telemetry_output_path_append_traceid |
bool or string | Optional | Controls whether and how the trace ID from the current span is appended to the telemetry output path. When set to true, appends the raw trace ID as a subdirectory. When set to a template string containing {trace_id}, the placeholder is replaced with the actual trace ID, giving full control over the subdirectory name (e.g. "tag={trace_id}", "{trace_id}-run", "traces/{trace_id}/data"). Default: false |
traceid_metadata_key |
string | Optional | The request-metadata field to read the trace ID from. When set, the value of that field is used directly as the trace ID; keys for metadata propagated by RDK are prefixed with viam-metadata-. When unset (and telemetry_output_path_append_traceid is set), the trace ID is parsed from the traceparent header instead. |
{
"host": "10.1.10.84",
"speed_degs_per_sec": 120,
"acceleration_degs_per_sec2": 8
}{
"host": "10.1.10.84",
"speed_degs_per_sec": 120,
"acceleration_degs_per_sec2": 8,
"robot_control_freq_hz": 10
}{
"host": "10.1.10.84",
"speed_degs_per_sec": [90, 90, 120, 180, 180, 180],
"acceleration_degs_per_sec2": [6, 6, 8, 10, 10, 10]
}{
"host": "10.1.10.84",
"speed_degs_per_sec": 120,
"acceleration_degs_per_sec2": 8,
"max_trajectory_duration_secs": 300,
"trajectory_sampling_freq_hz": 25
}{
"host": "10.1.10.84",
"speed_degs_per_sec": 120,
"acceleration_degs_per_sec2": 8,
"telemetry_output_path": "/var/log/arm_telemetry",
"telemetry_output_path_append_traceid": true
}{
"host": "10.1.10.84",
"speed_degs_per_sec": 120,
"acceleration_degs_per_sec2": 8,
"telemetry_output_path": "/var/log/arm_telemetry",
"telemetry_output_path_append_traceid": "trace-{trace_id}"
}set_vel or set_vel_degs_per_sec will update the speed_degs_per_sec maximum speed for joints, in deg/sec. Accepts either a single value (applied to all joints) or a 6-element array for per-joint limits. The value will reset back to the configured maximum when the arm is reconfigured.
{
"set_vel": <float or 6-element array>
}Examples:
{"set_vel": 100}
{"set_vel_degs_per_sec": [90, 90, 120, 180, 180, 180]}set_acc or set_accel_degs_per_sec2 will update the acceleration_degs_per_sec2 maximum acceleration for joints, in deg/sec^2. Accepts either a single value (applied to all joints) or a 6-element array for per-joint limits. The value will reset back to the configured maximum when the arm is reconfigured.
{
"set_acc": <float or 6-element array>
}Examples:
{"set_acc": 8}
{"set_accel_degs_per_sec2": [6, 6, 8, 10, 10, 10]}get_tcp_forces_base and get_tcp_forces_tool will return the current forces and torques on the end effector, if available. The forces are measured in Newtons(N) and torques are measured in Newtonmeters(Nm). Measurements are at the tool flange with the orientation of the arm's base or tool coordinate system, respectively.
{
"get_tcp_forces_base": ""
}example output:
{
"TRy_Nm": -0.002283915120630059,
"Fx_N": 2.860603275894862,
"Fz_N": -1.7602239771400954,
"TRz_Nm": 0.030823427258229515,
"Fy_N": 2.0520459818874928,
"TRx_Nm": -0.08206897295825417
}clear_pstop will clear an active protective stop on the arm. If there is no active protective stops or the arm is disconnected, this will throw an error.
{
"clear_pstop": ""
}zero_ftsensor zeroes (tares) the wrist force/torque sensor at the controller, so subsequent get_tcp_forces_base/get_tcp_forces_tool readings are relative to the current load and pose. This is an e-Series-only command (UR5e/UR10e/etc.); it is not supported on CB-series robots. The arm must be in a controllable state, otherwise the command will not work. For an accurate tare, the robot must be stationary and not in contact with anything when the command is called.
{
"zero_ftsensor": ""
}is_controllable_state returns a boolean that informs a user whether the arm is in a controllable state and ready to receive commands.
{
"is_controllable_state": ""
}get_state_description returns the description of the arm's current state, such as whether the arm is controllable or whether the arm is in a stopped or disconnected state.
{
"get_state_description": ""
}First ensure that your machine is displaying as Live on the Viam App. Then you can interact with your Universal Robots arm in a couple ways:
- To simply view data from and manipulate your arm, use the CONTROL tab of the Viam App. For more information, see Control Machines.
- More advanced control of the arm can be achieved by using one of Viam's client SDK libraries
Model viam:universal-robots:ft_sensor exposes a UR arm's wrist force/torque reading as a Viam sensor. It depends on a configured UR arm and reads through it.
{
"arm": "my-ur-arm"
}GetReadings returns the arm's get_tcp_forces_tool reading: forces in Newtons and torques in Newton-meters at the tool flange, in the tool coordinate system (Fx_N, Fy_N, Fz_N, TRx_Nm, TRy_Nm, TRz_Nm). To zero the sensor at the controller, use the arm's zero_ftsensor DoCommand.
For development purposes, you can either build directly on your development machine, or within a docker container, or with conan. The advantage of the docker container is that it comes with the required runtime libraries preinstalled. However, the module.tar.gz that is produced will only run on an Ubuntu Jammy (22.04) machine which already has the necessary runtime libraries installed, and it is unlikely that this matches your development machine. The advantage to building directly on your development machine is that the module.tar.gz that is built will work on that machine. However, you are required to install the necessary support libraries first. The advantage of conan is that it will build you a self-contained binary and will handle installing all of the dependencies. The resulting module.tar.gz should run on any system offering a system ABI compatible with the machine on which you built it (for instance, build on Debian 12 Bookworm, and it should run on Debian 13 Trixie).
Clone this repository to your machine and from the newly created folder start a new Docker container using the following commands:
git submodule update --init
docker pull ghcr.io/viam-modules/universal-robots:amd64
docker run --net=host --volume .:/src -it ghcr.io/viam-modules/universal-robots:amd64
If you are working on an ARM based machine, use the arm64 images:
docker pull ghcr.io/viam-modules/universal-robots:arm64
docker run --net=host --volume .:/src -it ghcr.io/viam-modules/universal-robots:arm64
Once inside the docker container build the binary using:
cd /src && make module.tar.gz
Install the prerequisite support libraries. These include, but are not limited to:
- Abseil
- Boost
- Eigen
- Protobuf
- Viam C++ SDK
- Xtensor
- gRPC
First, if you don't already have it, you will need to install conan. On macOS this is as easy as brew install conan. On systems where the system package manager does not provide it, you will most likely need to create a virtualenv and then run python -m pip install conan. Or use your python project/package management system of choice. If you have not used conan before, create a default profile with conan profile detect.
Next, run the ./bin/setup.sh script. It exports the Viam C++ SDK recipe into your conan cache (the SDK is not on conancenter) and adds the viamconan remote to your conan configuration. That remote hosts prebuilt binaries of the SDK and its heavy dependencies (gRPC, Protobuf, Boost, Abseil, OpenSSL), so the build downloads them instead of compiling them.
Finally, run the bin/build.sh script to build the Universal Robots driver and produce module.tar.gz. On macOS it uses etc/conan/macos.profile and etc/conan/linux.profile on Linux. With the viamconan remote this should take a few minutes; any dependency without a matching prebuilt binary is compiled from source. You can run it repeatedly to rebuild the driver.
If you would rather not use the viamconan remote, run VIAM_CONAN_NO_REMOTE=1 ./bin/setup.sh instead. Conan then builds the SDK and its dependencies from conancenter sources, which takes about an hour the first time; later builds reuse your local conan cache.
The prebuilt Linux binaries are only used when your compiler matches the profile (gcc 11, as on Ubuntu Jammy). With a different compiler, the dependencies are compiled from source.
Prebuilt binaries are only used when the dependency versions exactly match the ones the SDK release was built with. conan.lock pins those versions. When bumping viam-cpp-sdk in conanfile.py, regenerate it starting from the conan.lock attached to that SDK release on GitHub:
gh release download releases/v<version> -R viamrobotics/viam-cpp-sdk -p conan.lock -O sdk.lock
conan lock create . <the profile and settings from bin/build.sh> --lockfile=sdk.lock --lockfile-partial --lockfile-out=conan.lock
Run the conan lock create once per platform (Linux amd64, Linux arm64, macOS) with --lockfile-out set to a separate file each time, then combine them with conan lock merge --lockfile <file> ... --lockfile-out=conan.lock. For the Linux runs, pass -s:a arch=x86_64 or -s:a arch=armv8.
Also update etc/conan/linux.profile and etc/conan/macos.profile if the SDK changed the toolchain it publishes with.
Use one of the above techniques to produce module.tar.gz. Then, follow the instructions to add a local module to add the local instance of the universal-robots module to your machine.
Note
Simply running make install inside the docker image is a faster way to build but creates an executable that must be run from within the Docker container, per the above notes. If you are interested in making and testing many quick changes to this module it will likely be faster to only build this way and then run viam-server from within the Docker container, pointing to a config file that has a local instance of this module wih an executable path of build/install/bin/universal-robots. To download and run viam-server this way run:
wget https://storage.googleapis.com/packages.viam.com/apps/viam-server/viam-server-stable-x86_64
chmod +x ./viam-server-stable-x86_64
./viam-server-stable-x86_64 -config {PATH_TO_VIAM_CONFIG}
If the module fails to start successfully look through the error logs coming from viam-server. Some common issues errors are shown below along with solutions
| Error | Solution |
|---|---|
| "Command is not allowed due to safety reasons..." | Use the UR pendant to switch the robot from Local Control to Remote Control |
| "Did not receive answer from dashboard server in time..." | It is possible that the host address provided is not correct, or that the E-stop has been pressed on the UR pendant |
- integration tests
- address sanitizer support