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 Ubuntu | ROS 2 |
|---|---|
| 22.04 (jammy) | Humble |
| 24.04 (noble) | Jazzy |
ROS_ and the RMW must match the robot too.
- The domain ID is set in the
plemsettings (ros_indomain_ id ~/.).plem/ settings. yaml - The RMW is fixed to CycloneDDS (
rmw_).cyclonedds_ cpp plemwrites these values into your shell. Changing the shell variables does not change theplemsettings.
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/: rclpy,plem plem_,msgs plem_,rt_ msgs plem_) and the DDS settings.drive_ msgs - For non-interactive SSH commands and CI, run through
bash -lc '...'so the DDS settings are loaded too. source /opt/alone gives you rclpy and the message packages but not the DDS settings. Useplem/ setup. bash bash -lc '...'there as well.
~/. bashrcExporting ROS_, CYCLONEDDS_ or RMW_ 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/) applies to every domain (<Domain Id="any">).
To talk to other hosts, switch both the robot and the client to a real network interface.
- On the device, copy the default configuration file: to
/etc/for the whole device, or toplem/ cyclonedds. xml ~/.for your account only. If both exist,ros/ cyclonedds. xml ~/.wins.ros/ sudo install -d -m 0755 /etc/plem && sudo install -m 0644 /usr/share/plem/cyclonedds-localhost.xml /etc/plem/cyclonedds.xml - In the copy, change
loin<NetworkInterface name="lo" ...>to the real interface name (for exampleeth0). Edit only that part. Writing a new file drops tuning values such as buffer sizes. Set up the client the same way. - Run
plemagain and open a new terminal. Theplemlaunch log shows which configuration file was used. - 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 withsysctl -w net., and put it incore. rmem_ max=10485760 /etc/to keep it after reboot.sysctl. d/
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_, plem_ and plem_. 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_.
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:
- Add the ROS 2 apt repository for the device's distribution (table above). A full PLEM install (
install.) has already done this.sh - 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 -tover SSH. It fails where there is no terminal, such as CI.curl -fsSL https://depot.wimcorp.dev/jetson/setup.sh | sudo bash - Install the two packages. The names are
plem-msgsandplem-drive, notros-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_ and plem_.
Interfaces
Each robot's interfaces live under /{robot_, where robot_ 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_): directly undersensor/* /{robot_id}/
The tables below leave out /{robot_. Interfaces appear in stages during launch, with plem/ last. Wait for them with wait_ (Launching the stack).
Control
| Name | Type | Use |
|---|---|---|
plem/ | plem_ | Mode change. Required before motion |
plem/ | plem_ | Stop and recovery: reset_, protective_, release_, free_. Changes only the sub-mode and brakes, with no controller switch (Stops and safety) |
plem/ | plem_ | Trajectory planning |
joint_ | control_ | Trajectory execution (standard) |
gripper_ | control_ | Gripper (standard, same name for every vendor) |
ft_ | std_ | F/T sensor zero, stored in the sensor (below) |
plem/ plans deterministic industrial motion by default (DETERMINISTIC). Request collision avoidance with motion_. It is available only on ROS 2 Humble devices, and what it does and does not avoid is in Launching the stack.
Status
| Name | Type | Rate and notes |
|---|---|---|
joint_ | sensor_ | 100 Hz |
joint_ | sensor_ | 30 Hz. Only when topic_ is installed on the device; otherwise subscribe to joint_ |
joint_ | control_ | Tracking state (target, actual, error) for monitoring a running trajectory |
status_ | plem_ | Robot mode, 50 Hz |
status_ | plem_ | Safety state, 50 Hz |
gripper_ | plem_ | Gripper state (below) |
ft_ | geometry_ | F/T force and torque, 100 Hz |
ft_ | diagnostic_ | F/T sensor state, 5 Hz |
rt_ | plem_ | Discrete events such as faults and state changes. Look here for the cause of a stop |
rt_ | plem_ | Control-cycle diagnostics, aggregated over 1 s windows |
rt_ | plem_ | Raw data for every cycle, for analysis (below) |
gripper_:status connectedfalse means the gripper is not answering; check the cable and tool power. The other fields then hold the last values read.effortis always 0.0. Nothing is published until the driver gets the gripper's first answer, and gripper commands sent before that fail.rt_: BestEffort QoS, several samples per message,raw axis_joint values per sample. For live plots usecount rt_with PlotJuggler (Connect a servo drive).raw_ relay
/rt_ and /rt_ 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_, handle all five values. How the modes change is in Stops and safety.
F/T sensor
ft_ 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_, the sensor's measurement origin. Units are N and N·m.id>_ ft_ sensor_ frame - 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.
messageis a sentence to show an operator as is. In a program, branch onstateinvalues. Anything other thanOKmeans 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_. All values are strings. Look them up by key name, not by position.seq
level | state |
|---|---|
| OK | OK |
| WARN | STARTING, ZEROING, OVER_, OUT_ |
| ERROR | anything else (NOT_, FROZEN, NO_) |
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
ZEROINGstatus at all. - If the wrench went NaN, came back and the counter changed, the zero may have changed. Reset your force baselines and filters.
ZEROINGcan 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_ 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
nullJSON 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_ transforms the wrench through TF. It is in the force_ package, which is already installed. This example publishes values in robot_1_ on /robot_1/:
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/. release_ in plem/ 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:
- Enter TRAJECTORY with
plem/set_ mode - Plan with
plem/plan_ trajectory - Run the result's
trajectorywithfollow_joint_ trajectory
Trajectories you build yourself are not collision-checked
A trajectory you build yourself and send to follow_ without plem/ 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.
| Model | Goal tolerance | Meaning of SUCCEEDED |
|---|---|---|
| Neuromeka | None | Reported once time_ has passed. No guarantee the target was reached |
| Huayan Elfin | Per joint: 0.02 rad at the end, 0.5 rad along the path, goal_ 0.5 s | Ends as a failure (abort) outside the tolerances |
- With any model, check the final position in
joint_afterwards.states - A goal must name every joint (
allow_, the trajectory controller default).partial_ joints_ goal: false - 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_). For safety, set the last point's velocity to zero.nonzero_ velocity_ at_ trajectory_ end: true
Stopping and recovery
| You want | How |
|---|---|
| A controlled stop | Cancel the running goal |
| An immediate stop | protective_ in plem/ (engages the brakes), or plem/ |
Protective Stop and ERROR do not clear by themselves. Watch safety_ and robot_, clear with reset_, then enter a mode again. reset_ 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_ 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_, JointTrajectory.).
Units
Angles are in radians, distances in meters, rotations as quaternions. Field names carry the unit (for example MotionTarget.). Convert degrees with rad = deg × π / 180.
When plem/ set_ mode fails
| What you see | Causes |
|---|---|
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_, safety_ and rt_ tell them apart |
Checking message definitions
This page does not copy field layouts. The plem_, plem_ and plem_ 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