Skip to main content

ROS 2 interfaces

A PLEM robot is controlled and read through standard ROS 2 topics, services and actions. This page covers how to connect, the interface list and the rules a client must follow.

Before you start​

The client uses the same ROS 2 distribution as the robot device.

Device UbuntuROS 2
22.04 (jammy)Humble
24.04 (noble)Jazzy

ROS_DOMAIN_ID and the RMW must match the robot too.

  • The domain ID is set in the plem settings (ros_domain_id in ~/.plem/settings.yaml).
  • The RMW is fixed to CycloneDDS (rmw_cyclonedds_cpp).
  • plem writes these values into your shell. Changing the shell variables does not change the plem settings.

On the robot device​

The easiest way is to work on the robot device itself, at its console or over SSH. Any new terminal is already set up:

ros2 topic list
  • Interactive shells already have the PLEM environment (/opt/plem: rclpy, plem_msgs, plem_rt_msgs, plem_drive_msgs) and the DDS settings.
  • For non-interactive SSH commands and CI, run through bash -lc '...' so the DDS settings are loaded too.
  • source /opt/plem/setup.bash alone gives you rclpy and the message packages but not the DDS settings. Use bash -lc '...' there as well.
caution
Do not put DDS values in ~/.bashrc

Exporting ROS_DOMAIN_ID, CYCLONEDDS_URI or RMW_IMPLEMENTATION from a shell startup file puts only that shell out of step with the robot.

If you changed the domain ID, restart plem and open a new terminal; terminals that are already open keep the old value. Other cases where ros2 does not see the robot: Troubleshooting.

From another host​

By default the device's DDS talks only over loopback (lo), which keeps large on-device data such as camera images stable. So ros2 topic list on another PC returns an empty list with no error. If remote access does not work, check this first.

Changing the domain ID does not lift this limit, because the configuration file (/usr/share/plem/cyclonedds-localhost.xml) applies to every domain (<Domain Id="any">).

To talk to other hosts, switch both the robot and the client to a real network interface.

  1. On the device, copy the default configuration file: to /etc/plem/cyclonedds.xml for the whole device, or to ~/.ros/cyclonedds.xml for your account only. If both exist, ~/.ros/ wins.
    sudo install -d -m 0755 /etc/plem && sudo install -m 0644 /usr/share/plem/cyclonedds-localhost.xml /etc/plem/cyclonedds.xml
  2. In the copy, change lo in <NetworkInterface name="lo" ...> to the real interface name (for example eth0). Edit only that part. Writing a new file drops tuning values such as buffer sizes. Set up the client the same way.
  3. Run plem again and open a new terminal. The plem launch log shows which configuration file was used.
  4. If creating a node fails on the client, the kernel receive buffer may be too small: the file asks for at least 10 MB (<SocketReceiveBufferSize min="10MB"/>). Raise it with sysctl -w net.core.rmem_max=10485760, and put it in /etc/sysctl.d/ to keep it after reboot.
This exposes the robot to the network

Lifting the loopback limit gives up the stability of large on-device transfers and exposes the robot to the network. Lift it only for as long as you need, and only on networks you trust.

Installing plem_msgs, plem_rt_msgs and plem_drive_msgs​

To use the PLEM-specific interfaces, the client needs plem_msgs, plem_rt_msgs and plem_drive_msgs. The robot device already has them. Standard interfaces alone are enough to read joint states and use the gripper, but moving the arm needs a mode change first (Mode first), and that interface is in plem_msgs.

Only registered Jetson devices can install them

The PLEM package repository (Depot) is private. It installs only on aarch64 Ubuntu 22.04 (JetPack 6) or 24.04 (JetPack 7) devices registered with the token from your WIM contact. For x86 PCs or other environments, ask your WIM contact.

On another Jetson device:

  1. Add the ROS 2 apt repository for the device's distribution (table above). A full PLEM install (install.sh) has already done this.
  2. Add the PLEM repository. It asks for the token without echoing it or saving it in shell history, so it needs a terminal: use ssh -t over SSH. It fails where there is no terminal, such as CI.
    curl -fsSL https://depot.wimcorp.dev/jetson/setup.sh | sudo bash
  3. Install the two packages. The names are plem-msgs and plem-drive, not ros-humble-plem-msgs.
    sudo apt install plem-msgs plem-drive # installs to /opt/plem; use with source /opt/plem/setup.bash

plem-drive installs whole, with the drive runtime and its shell setup, even if you need only plem_rt_msgs and plem_drive_msgs.

Interfaces​

Each robot's interfaces live under /{robot_id}/, where robot_id is the robot profile name chosen in plem.

  • PLEM-specific interfaces: under /{robot_id}/plem/
  • Standard ros2_control interfaces and the F/T sensor (ft_sensor/*): directly under /{robot_id}/

The tables below leave out /{robot_id}/. Interfaces appear in stages during launch, with plem/plan_trajectory last. Wait for them with wait_for_server (Launching the stack).

Control​

NameTypeUse
plem/set_modeplem_msgs/action/SetModeMode change. Required before motion
plem/control_commandplem_rt_msgs/srv/SetControlCommandStop and recovery: reset_error, protective_stop, release_brake, free_drive. Changes only the sub-mode and brakes, with no controller switch (Stops and safety)
plem/plan_trajectoryplem_msgs/action/PlanTrajectoryTrajectory planning
joint_trajectory_controller/follow_joint_trajectorycontrol_msgs/action/FollowJointTrajectoryTrajectory execution (standard)
gripper_action_server/gripper_commandcontrol_msgs/action/GripperCommandGripper (standard, same name for every vendor)
ft_sensor/zerostd_srvs/srv/TriggerF/T sensor zero, stored in the sensor (below)

plem/plan_trajectory plans deterministic industrial motion by default (DETERMINISTIC). Request collision avoidance with motion_intent=COLLISION_AWARE. It is available only on ROS 2 Humble devices, and what it does and does not avoid is in Launching the stack.

Status​

NameTypeRate and notes
joint_statessensor_msgs/msg/JointState100 Hz
joint_states_throttledsensor_msgs/msg/JointState30 Hz. Only when topic_tools is installed on the device; otherwise subscribe to joint_states
joint_trajectory_controller/statecontrol_msgs/msg/JointTrajectoryControllerStateTracking state (target, actual, error) for monitoring a running trajectory
status_broadcaster/robot_modeplem_msgs/msg/RobotModeRobot mode, 50 Hz
status_broadcaster/safety_modeplem_msgs/msg/SafetyModeSafety state, 50 Hz
gripper_statusplem_msgs/msg/GripperStatusGripper state (below)
ft_sensor/wrenchgeometry_msgs/msg/WrenchStampedF/T force and torque, 100 Hz
ft_sensor/statusdiagnostic_msgs/msg/DiagnosticStatusF/T sensor state, 5 Hz
rt_eventsplem_rt_msgs/msg/RtEventDiscrete events such as faults and state changes. Look here for the cause of a stop
rt_diagnosticsplem_msgs/msg/RtDiagnosticsControl-cycle diagnostics, aggregated over 1 s windows
rt_rawplem_rt_msgs/msg/RtRawBatchRaw data for every cycle, for analysis (below)
  • gripper_status: connected false means the gripper is not answering; check the cable and tool power. The other fields then hold the last values read. effort is always 0.0. Nothing is published until the driver gets the gripper's first answer, and gripper commands sent before that fail.
  • rt_raw: BestEffort QoS, several samples per message, axis_count joint values per sample. For live plots use rt_raw_relay with PlotJuggler (Connect a servo drive).
Bags recorded with earlier versions

/rt_raw and /rt_events bags recorded before this version cannot be read in this version, because the message package and fields changed. Analyze them with the version that recorded them.

Mode values​

RobotMode: BRAKED=0 STOPPING=1 TRAJECTORY=2 FREEDRIVE=3 ERROR=-1
SafetyMode: NORMAL=0 PROTECTIVE_STOP=1

If you subscribe to robot_mode, handle all five values. How the modes change is in Stops and safety.

F/T sensor​

ft_sensor/* exists only on robots whose profile names an F/T sensor. Values, zeroing, states and what to do about each state are in F/T sensor. This section covers what a program needs.

wrench​

  • The frame is <robot_id>_ft_sensor_frame, the sensor's measurement origin. Units are N and N·m.
  • Values are in sensor coordinates, relative to the last zero, with no gravity compensation and no frame change.
  • When a value cannot be trusted, all six axes are NaN. They are never filled with the previous or an estimated value. The cases are the states other than OK.

status​

  • Published at 5 Hz as soon as the adapter starts. No status means the adapter is missing or disconnected.
  • message is a sentence to show an operator as is. In a program, branch on state in values. Anything other than OK means the wrench is NaN.
  • Other keys in values: utilization (load against the rating, 1.0 = rated), error_flag, overload_byte, wrapped_axes, sent_cycles, zero_seq. All values are strings. Look them up by key name, not by position.
levelstate
OKOK
WARNSTARTING, ZEROING, OVER_RATED, OUT_OF_RANGE
ERRORanything else (NOT_RESPONDING, FROZEN, NO_RELAY)

zero_seq​

A counter that goes up by 1 each time a zero command may have reached the sensor, including when delivery was not confirmed. It starts at 0 when the stack launches.

  • While a zero command runs (usually under 1 s, a few seconds at most) the wrench is NaN, and the counter goes up the moment the command ends.
  • The wrench (100 Hz) carries no counter; it comes with status (5 Hz). So a new counter can show up to 0.2 s after values return, and a short zero can pass with no ZEROING status at all.
  • If the wrench went NaN, came back and the counter changed, the zero may have changed. Reset your force baselines and filters.
  • ZEROING can also show briefly when a command could not be sent. The counter then stays the same.
  • A torque plugin gets the value, state and counter in the same cycle. Valid values with the same counter share the same zero.

ft_sensor/zero is refused while the robot is moving, among other cases. When it is refused, and what success: true means: F/T sensor.

ros2 topic echo /robot_1/ft_sensor/wrench
ros2 service call /robot_1/ft_sensor/zero std_srvs/srv/Trigger
warning
Web clients (rosbridge) get NaN as null

JSON has no NaN, so it becomes null, and Number(null) is 0: used as is, an invalid value shows as 0 N. Subscribe with CBOR (compression: 'cbor') or treat null as invalid.

In other frames​

The standard ROS 2 node wrench_transformer_node transforms the wrench through TF. It is in the force_torque_sensor_broadcaster package, which is already installed. This example publishes values in robot_1_tcp on /robot_1/ft_sensor/robot_1_tcp/wrench:

ros2 run force_torque_sensor_broadcaster wrench_transformer_node --ros-args \
-r __ns:=/robot_1/ft_sensor \
-r /robot_1/ft_sensor/fts_wrench_transformer/wrench:=/robot_1/ft_sensor/wrench \
-p target_frames:="['robot_1_tcp']"
  • Remap the input topic with an absolute name.
  • It moves the axes and the torque reference point (r × F), but does no gravity compensation.
  • It needs TF, so run it while the robot stack is up.

Client rules​

Mode first​

The robot takes trajectories only in TRAJECTORY mode. A FollowJointTrajectory goal sent in any other mode is rejected (accepted == False).

Seeing the action in ros2 action list does not mean goals will be accepted. The trajectory controller comes up inactive and is activated when the robot enters the mode.

Always enter TRAJECTORY with plem/set_mode(TRAJECTORY). release_brake in plem/control_command also switches to that mode, but it does not activate the trajectory controller, so the robot is not ready to run trajectories.

The usual order:

  1. Enter TRAJECTORY with plem/set_mode
  2. Plan with plem/plan_trajectory
  3. Run the result's trajectory with follow_joint_trajectory

Trajectories you build yourself are not collision-checked​

Send only verified trajectories

A trajectory you build yourself and send to follow_joint_trajectory without plem/plan_trajectory gets no collision or path check at all. Use it only for verified motion, with people outside the work area and the Emergency Stop button within reach.

Success does not mean the target was reached​

What SUCCEEDED on FollowJointTrajectory means depends on the robot model.

ModelGoal toleranceMeaning of SUCCEEDED
NeuromekaNoneReported once time_from_start has passed. No guarantee the target was reached
Huayan ElfinPer joint: 0.02 rad at the end, 0.5 rad along the path, goal_time 0.5 sEnds as a failure (abort) outside the tolerances
  • With any model, check the final position in joint_states afterwards.
  • A goal must name every joint (allow_partial_joints_goal: false, the trajectory controller default).
  • Do not send trajectories beyond the servo limits, such as one with a far too short time_from_start.
  • A goal is accepted even if the last point's velocity is not zero (allow_nonzero_velocity_at_trajectory_end: true). For safety, set the last point's velocity to zero.

Stopping and recovery​

You wantHow
A controlled stopCancel the running goal
An immediate stopprotective_stop in plem/control_command (engages the brakes), or plem/set_mode(BRAKED)

Protective Stop and ERROR do not clear by themselves. Watch safety_mode and robot_mode, clear with reset_error, then enter a mode again. reset_error is accepted in any state and requests both a drive fault reset and a Protective Stop clear. Steps: Stops and safety and Fault reset.

Joint order​

The name order in joint_states is not fixed (one real example: joint0,1,2,5,3,4). Never assume an index; always look joints up by name. The same goes for commands (joints_rad, JointTrajectory.joint_names).

Units​

Angles are in radians, distances in meters, rotations as quaternions. Field names carry the unit (for example MotionTarget.joints_rad). Convert degrees with rad = deg × π / 180.

When plem/set_mode fails​

What you seeCauses
The goal is rejected (accepted == false, no result message)Already in that mode · the safety state forbids the change · another mode goal is still running (send mode goals one at a time)
Accepted, then fails (reason in the result message)EtherCAT link problem (robot power, cable) · the Jog lane did not stop in time · a controller switch failed. These look the same; robot_mode, safety_mode and rt_events tell them apart

Checking message definitions​

This page does not copy field layouts. The plem_msgs, plem_rt_msgs and plem_drive_msgs packages are the reference, so query them directly:

ros2 interface show plem_msgs/action/SetMode
ros2 interface show plem_msgs/action/PlanTrajectory # Goal = MotionTarget target (+ optional start_joints_rad)
ros2 interface show plem_msgs/msg/MotionTarget # motion target fields such as move_type, speed_scale
ros2 interface show plem_rt_msgs/srv/SetControlCommand