ROS2 Topics#

The WMX R2 application uses topics for real-time data streaming: encoder feedback from the robot and motion commands to the WMX engine. Topics are divided into published (output) and subscribed (input) categories.

Topic Summary#
Topic	Message Type	Direction	Rate	Node
`/wmx/engine/ready`	`std_msgs/Bool`	Published	On change	`wmx_engine_node`
`/joint_states`	`sensor_msgs/JointState`	Published	100 Hz	`joint_state_broadcaster`
`/isaacsim/joint_command`	`sensor_msgs/JointState`	Published	100 Hz	`joint_state_broadcaster`
`/gazebo_.../commands`	`std_msgs/Float64MultiArray`	Published	100 Hz	`joint_state_broadcaster`
`/wmx/axis/state`	`wmx_r2_message/AxisState`	Published	100 Hz	`wmx_core_motion_node`
`/wmx/axis/velocity`	`wmx_r2_message/AxisVelocity`	Subscribed	On demand	`wmx_core_motion_node`
`/wmx/axis/position`	`wmx_r2_message/AxisPose`	Subscribed	On demand	`wmx_core_motion_node`
`/wmx/axis/position/relative`	`wmx_r2_message/AxisPose`	Subscribed	On demand	`wmx_core_motion_node`

Custom Message Types #

Before reviewing the topics, here are the custom message type definitions from wmx_r2_message.

wmx_r2_message/msg/AxisState

std_msgs/Header header
bool[] amp_alarm           # Amplifier alarm active per axis
bool[] servo_on            # Servo enabled per axis
bool[] home_done           # Homing completed per axis
bool[] home_switch         # Home switch active per axis
bool[] negative_ls         # Negative limit switch active per axis
bool[] positive_ls         # Positive limit switch active per axis
bool[] motion_complete     # Motion finished / in position per axis
float64[] pos_cmd         # Commanded position per axis (radians)
float64[] velocity_cmd    # Commanded velocity per axis (rad/s)
float64[] actual_pos      # Actual encoder position per axis (radians)
float64[] actual_velocity # Actual velocity per axis (rad/s)
float64[] actual_torque   # Actual torque per axis (Nm)

wmx_r2_message/msg/AxisPose

int32[] index         # Axis indices to command
float64[] target      # Target positions (radians)
float64[] velocity    # Motion velocity per axis (rad/s)
float64[] acc         # Acceleration per axis (rad/s^2)
float64[] dec         # Deceleration per axis (rad/s^2)

wmx_r2_message/msg/AxisVelocity

int32[] index         # Axis indices to command
float64[] velocity    # Target velocity per axis (rad/s)
float64[] acc         # Acceleration per axis (rad/s^2)
float64[] dec         # Deceleration per axis (rad/s^2)

Important

Where the radians come from

The WMX engine works in user units, not radians. Positions, velocities, and accelerations on these topics are radians only because every shipped parameter file sets AxisGearRatioDenominator to 2π, which makes one user unit equal one radian. A parameter file with a different denominator silently rescales every value on every WMX topic and service. See Robot Parameter Configuration and Validation.

Danger

/wmx/axis/velocity, /wmx/axis/position, and /wmx/axis/position/relative command the drives directly. They bypass MoveIt, so no planning-time joint-limit check and no collision check applies — and WMX soft limits are disabled in the shipped parameter files. The velocity and acceleration values in the examples below illustrate the message format; they are not safe commissioning values. See Commissioning and First Motion.

Published Topics #

Engine Ready Signal#

/wmx/engine/ready#

Message Type	`std_msgs/msg/Bool`
Publisher	`wmx_engine_node`
Rate	Published on state change (not periodic)
Purpose	Signals to dependent nodes (`wmx_core_motion_node`, `wmx_io_node`, `wmx_ethercat_node`) that EtherCAT communication is active

data=true is published once StartCommunication succeeds. data=false is published on shutdown.

Example:

ros2 topic echo /wmx/engine/ready

Joint State Feedback#

/joint_states#

Message Type	`sensor_msgs/msg/JointState`
Publisher	`joint_state_broadcaster`
Rate	100 Hz (set by the `joint_feedback_rate` parameter)
Configurable	Topic name set via `encoder_joint_topic` parameter
Source	`joint_state_broadcaster.cpp:publishJointState()`

The primary joint state topic used by MoveIt2, RViz, and other ROS2 consumers. Publishes encoder feedback for all 6 robot joints plus 2 gripper finger joints.

Message Fields#
Field	Type	Description
`header.stamp`	`builtin_interfaces/Time`	Current ROS2 time (set before publishing)
`header.frame_id`	`string`	Empty (default)
`name`	`string[]`	8 joint names: `["joint1", "joint2", "joint3", "joint4", "joint5", "joint6", "picker_1_joint", "picker_2_joint"]`
`position`	`float64[]`	8 values: 6 joint positions (`actualPos` from encoder, radians) + 2 gripper positions (from I/O bit)
`velocity`	`float64[]`	8 values: 6 joint velocities (`actualVelocity` from encoder, rad/s) + 2 gripper velocities (always `0.0`)
`effort`	`float64[]`	Empty (not populated)

The gripper positions (indices 6 and 7) are derived from the EtherCAT digital I/O output bit 0 via Io::GetOutBit(0, 0). When the gripper is closed (bit=1), they report the gripper_close_value parameter (default 0.045); when open (bit=0), the gripper_open_value parameter (default 0.00).

Example – Monitor joint states:

ros2 topic echo /joint_states

Example – Check publishing rate:

ros2 topic hz /joint_states

Expected: approximately 100 Hz (the configured joint_feedback_rate).

Example – View only joint positions:

ros2 topic echo /joint_states --field position

Simulator Integration Topics#

/isaacsim/joint_command#

Message Type	`sensor_msgs/msg/JointState`
Publisher	`joint_state_broadcaster`
Rate	100 Hz (same timer as `/joint_states`)
Configurable	Topic name set via `isaacsim_joint_topic` parameter
Platform	Orin config only (Intel config does not set this topic)
Purpose	Mirror joint states for NVIDIA Isaac Sim integration

Same data content as /joint_states (8 joint names, positions, velocities).

Note

This topic is published before the header.stamp is set in the encoderJointStep() callback. The timestamp in the Isaac Sim message will be unset (zero). This is an implementation detail of the publish order in the source code.

Example:

ros2 topic echo /isaacsim/joint_command

/gazebo_position_controller/commands#

Message Type	`std_msgs/msg/Float64MultiArray`
Publisher	`joint_state_broadcaster`
Rate	100 Hz (same timer as `/joint_states`)
Configurable	Topic name set via `gazebo_joint_topic` parameter
Platform	Intel config only (Orin config does not set this topic)
Purpose	Mirror joint positions for Gazebo simulation integration

Publishes 8 position values (6 joint positions + 2 gripper positions) as a flat Float64MultiArray. The array is pre-sized to 8 elements.

Message Fields#
Field	Type	Description
`data`	`float64[]`	8 values: 6 joint positions in radians (`actualPos`) + 2 gripper positions (`gripper_close_value` or `gripper_open_value`)

Example:

ros2 topic echo /gazebo_position_controller/commands

Axis State Monitoring#

/wmx/axis/state#

Message Type	`wmx_r2_message/msg/AxisState`
Publisher	`wmx_core_motion_node`
Rate	100 Hz (hardcoded `rate_=100`)
Axis Count	2 (hardcoded `axisCount_=2`)
Source	`wmx_core_motion_node.cpp:axisStateStep()`
Purpose	Detailed per-axis status from the WMX CoreMotion API

Publishes comprehensive axis status including servo state, alarm status, limit switches, commanded vs. actual positions, velocities, and torques.

Important

The axis count is hardcoded to 2 in wmx_core_motion_node.hpp (axisCount_=2). This means the arrays in AxisState contain 2 elements each, monitoring axes 0 and 1 only.

Message Fields#
Field	Type	Description
`amp_alarm`	`int32[]`	Amplifier alarm active per axis (`1` = fault)
`servo_on`	`int32[]`	Servo drive enabled per axis (`1` = on)
`home_done`	`int32[]`	Homing procedure completed per axis (`1` = done)
`in_pos`	`int32[]`	Axis has reached commanded position (`1` = in position)
`negative_ls`	`int32[]`	Negative limit switch triggered per axis (`1` = triggered)
`positive_ls`	`int32[]`	Positive limit switch triggered per axis (`1` = triggered)
`home_switch`	`int32[]`	Home switch triggered per axis (`1` = triggered)
`pos_cmd`	`float64[]`	Commanded position per axis (radians)
`velocity_cmd`	`float64[]`	Commanded velocity per axis (rad/s)
`actual_pos`	`float64[]`	Actual encoder position per axis (radians)
`actual_velocity`	`float64[]`	Actual velocity per axis (rad/s)
`actual_torque`	`float64[]`	Actual torque per axis (Nm)

The callback clears all vectors before each publish cycle and rebuilds them from the CoreMotion::GetStatus() result.

Example – Monitor axis state:

ros2 topic echo /wmx/axis/state

Example – Check for alarms:

ros2 topic echo /wmx/axis/state --field amp_alarm

Subscribed Topics (Motion Commands)#

These topics accept motion commands and are subscribed to by the wmx_core_motion_node (source: wmx_core_motion_node.cpp). Publishing to these topics directly controls the WMX engine and moves real motors.

Warning

Publishing to these topics will cause immediate physical motion. Ensure the robot workspace is clear and all safety precautions are in place.

/wmx/axis/velocity#

Message Type	`wmx_r2_message/msg/AxisVelocity`
Subscriber	`wmx_core_motion_node`
Callback	`axisVelCallback()`
Purpose	Command continuous velocity motion on specified axes

For each axis in msg->index, the callback:

Sets velocity_.axis to the axis index
Sets the velocity profile to ProfileType::Trapezoidal
Sets velocity, acceleration, and deceleration from the message
Calls CoreMotion::StartVel(&velocity_)

The axis must be in velocity mode (see ROS2 Services for /wmx/axis/set_mode with data=[1]).

Example – Rotate axis 0 at 1.0 rad/s:

ros2 topic pub --once /wmx/axis/velocity wmx_r2_message/msg/AxisVelocity \
  "{index: [0], velocity: [1.0], acc: [10.0], dec: [10.0]}"

Example – Stop axis 0:

ros2 topic pub --once /wmx/axis/velocity wmx_r2_message/msg/AxisVelocity \
  "{index: [0], velocity: [0.0], acc: [10.0], dec: [10.0]}"

/wmx/axis/position#

Message Type	`wmx_r2_message/msg/AxisPose`
Subscriber	`wmx_core_motion_node`
Callback	`axisPoseCallback()`
Purpose	Command absolute position motion on specified axes

For each axis in msg->index, the callback:

Sets position_.axis to the axis index
Sets position_.target to the target position
Sets the profile to ProfileType::Trapezoidal
Sets velocity, acceleration, and deceleration from the message
Calls CoreMotion::StartPos(&position_) – absolute positioning

The target values are absolute positions in radians relative to the home position.

Example – Move axis 0 to 1.5 radians:

ros2 topic pub --once /wmx/axis/position wmx_r2_message/msg/AxisPose \
  "{index: [0], target: [1.5], velocity: [5.0], acc: [10.0], dec: [10.0]}"

/wmx/axis/position/relative#

Message Type	`wmx_r2_message/msg/AxisPose`
Subscriber	`wmx_core_motion_node`
Callback	`axisPoseRelativeCallback()`
Purpose	Command relative position motion on specified axes

For each axis in msg->index, the callback:

Sets position_.axis to the axis index
Sets position_.target to the relative displacement
Sets the profile to ProfileType::Trapezoidal
Sets velocity, acceleration, and deceleration from the message
Calls CoreMotion::StartMov(&position_) – relative movement

The target values are relative displacements in radians from the current position.

Example – Move axis 0 by +0.5 radians from current position:

ros2 topic pub --once /wmx/axis/position/relative wmx_r2_message/msg/AxisPose \
  "{index: [0], target: [0.5], velocity: [5.0], acc: [10.0], dec: [10.0]}"

Differential Drive Topics #

The differential_drive_controller node drives a two-wheel mobile base. It is built and installed by default, and launched by wmx_r2_diffbot_navigation.launch.py with diffbot_navigation_config.yaml.

The wheel axes must be in velocity mode. diffbot_wmx_parameters.xml sets AxisCommandMode = 1 on axes 0 and 1 for this reason — see Robot Parameter Configuration and Validation.

/cmd_vel_safe (Subscribed)#

Message Type	`geometry_msgs/msg/TwistStamped`
Subscriber	`differential_drive_controller`
Configurable	Topic name set via `cmd_vel_topic` parameter (default `/cmd_vel_safe`)
Purpose	Receive linear/angular velocity commands for the mobile base

The control timer (at rate Hz, default 100) then:

Checks engine state is Communicating
Checks for amplifier alarms and servo status on both wheel axes
Computes wheel angular velocities using differential drive kinematics:
- left_omega = (2 * linear.x - angular.z * wheel_to_wheel) / (2 * wheel_radius)
- right_omega = (2 * linear.x + angular.z * wheel_to_wheel) / (2 * wheel_radius)
Calls CoreMotion::StartVel() for each wheel axis

Note

cmd_vel_timeout (default 0.25 s) zeroes the wheels when no command arrives within the window. This is a functional stale-command timer, not a safety function — see Safety Functions and Responsibility.

/omega_enc (Published)#

Message Type	`std_msgs/msg/Float64MultiArray`
Publisher	`differential_drive_controller`
Configurable	Topic name set via `encoder_omega_topic` parameter
Purpose	Publish actual wheel angular velocities from encoder feedback

Publishes 2 values: [left_velocity, right_velocity] read from the CoreMotion::GetStatus() result for the left and right wheel axes.

/odom_enc (Published)#

Message Type	`nav_msgs/msg/Odometry`
Publisher	`differential_drive_controller`
Configurable	Topic name set via `encoder_odometry_topic` parameter
Purpose	Publish encoder-based odometry (pose and twist), dead-reckoned from encoder position deltas

Twist is computed from the wheel angular velocities:

linear_vel = (right_omega * wheel_radius + left_omega * wheel_radius) / 2
angular_vel = (right_omega * wheel_radius - left_omega * wheel_radius) / wheel_to_wheel

Pose is integrated from per-cycle encoder position deltas and published in pose.pose.position and pose.pose.orientation. pos_unit_scale converts actualPos to wheel radians and is 1.0 when the WMX parameter file already scales to radians. A jump guard (jump_guard_tol, default 0.5 rad) re-baselines the integration when a position delta disagrees with the measured velocity, rejecting homing and encoder-rollover jumps.

TF (odom → base_link) is published only when publish_tf is true. It defaults to false so the localization EKF owns the transform.

/odom_deltas and /odom_accel (Published)#

Message Types	`geometry_msgs/msg/TwistStamped` (`/odom_deltas`), `geometry_msgs/msg/AccelStamped` (`/odom_accel`)
Publisher	`differential_drive_controller`
Configurable	`odom_deltas_topic` / `odom_accel_topic`
Purpose	Per-cycle pose deltas, and a rate-limited, low-pass-filtered acceleration estimate (`accel_publish_rate` default 10 Hz, `accel_alpha` default 0.3)

ROS2 Topics#

Custom Message Types#

Published Topics#

Engine Ready Signal#

/wmx/engine/ready#

Joint State Feedback#

/joint_states#

Simulator Integration Topics#

/isaacsim/joint_command#

/gazebo_position_controller/commands#

Axis State Monitoring#

/wmx/axis/state#

Subscribed Topics (Motion Commands)#

/wmx/axis/velocity#

/wmx/axis/position#

/wmx/axis/position/relative#

Differential Drive Topics#

/cmd_vel_safe (Subscribed)#

/omega_enc (Published)#

/odom_enc (Published)#

/odom_deltas and /odom_accel (Published)#

See Also#

Custom Message Types #

Published Topics #

Differential Drive Topics #

See Also #