wmx_r2_package#

Overview#

The wmx_r2_package is the main application package of the WMX R2 system. It contains all executable nodes, launch files, and configuration files for driving robots — such as the Dobot CR3A and CR5A manipulators — through the WMX motion control engine over EtherCAT.

The package provides two groups of nodes:

General nodes – wmx_engine_node, wmx_core_motion_node, wmx_io_node, and wmx_ethercat_node expose the WMX engine, axis, I/O, and EtherCAT interfaces as ROS2 services and topics. They are robot-agnostic.
Manipulator controllers – joint_state_broadcaster, joint_trajectory_controller, and gripper_controller add joint-state feedback, MoveIt2 trajectory execution, and gripper control for a specific robot, configured from a per-robot YAML file.

Package Metadata:

Package Name	`wmx_r2_package`
Version	0.1.0
License	MIT (source code only; the WMX engine and SDK it links against are proprietary — see Licensing)
Build Type	`ament_cmake`
C++ Standard	C++17

Package Structure#

wmx_r2_package/
├── CMakeLists.txt
├── package.xml
├── include/
│   ├── wmx_engine_node.hpp               # WmxEngineNode class definition
│   ├── wmx_core_motion_node.hpp          # WmxCoreMotionNode class definition
│   ├── wmx_io_node.hpp                   # WmxIoNode class definition
│   └── wmx_ethercat_node.hpp             # WmxEtherCatNode class definition
├── src/
│   ├── wmx_engine_node.cpp               # Engine lifecycle node
│   ├── wmx_core_motion_node.cpp          # Axis control + parameter node
│   ├── wmx_io_node.cpp                   # Digital I/O node
│   ├── wmx_ethercat_node.cpp             # EtherCAT diagnostics node
│   ├── joint_state_broadcaster.cpp       # Joint state publisher node
│   ├── joint_trajectory_controller.cpp   # FollowJointTrajectory action node
│   └── gripper_controller.cpp            # Gripper control node
├── launch/
│   ├── wmx_r2_general_nodes.launch.py
│   ├── wmx_r2_cr3a_manipulator.launch.py
│   └── wmx_r2_cr5a_manipulator.launch.py
├── config/
│   ├── cr3a_manipulator_config.yaml
│   ├── cr3a_wmx_parameters.xml           # WMX3 axis params for CR3A
│   ├── cr5a_manipulator_config.yaml
│   ├── cr5a_wmx_parameters.xml           # WMX3 axis params for CR5A
│   └── diffbot_wmx_parameters.xml        # WMX3 axis params for a diff-drive base
└── test/

Dependencies#

Package Dependencies (package.xml)#

Dependency	Type	Purpose
`ament_cmake`	buildtool	CMake build system
`rclcpp`	depend	ROS2 C++ client library
`rclcpp_action`	depend	Action server support (FollowJointTrajectory)
`std_srvs`	depend	Standard service types (`SetBool`, `Trigger`)
`std_msgs`	depend	Standard message types (`Bool`, `Float64MultiArray`)
`sensor_msgs`	depend	`JointState` messages
`control_msgs`	depend	`FollowJointTrajectory` action type
`trajectory_msgs`	depend	`JointTrajectory` messages
`wmx_r2_message`	depend	Custom message and service definitions
`ros2launch`	exec	Launch system
`joint_state_publisher`	exec	Joint state publishing utilities
`robot_state_publisher`	exec	Robot TF broadcasting
`rviz2`	exec	Visualization
`xacro`	exec	URDF preprocessing

CMake Dependencies (find_package)#

ament_cmake, rclcpp, rclcpp_action, std_msgs, std_srvs, sensor_msgs, control_msgs, trajectory_msgs, and wmx_r2_message.

WMX Libraries (External)#

Executables link against the WMX shared libraries at /opt/wmx3/lib/. Each node links only the libraries it needs:

Library	Executable(s)	Purpose
`libwmx3api.so` / `libimdll.so`	All nodes	Core WMX device/engine management (and internal dependency)
`libcoremotionapi.so`	`wmx_core_motion_node`, `joint_state_broadcaster`, `joint_trajectory_controller`, `gripper_controller`	Position, velocity, and axis control
`libadvancedmotionapi.so`	`joint_trajectory_controller`	Cubic spline trajectory execution
`libioapi.so`	`wmx_io_node`, `joint_state_broadcaster`, `gripper_controller`	Digital I/O (gripper control)
`libecapi.so`	`wmx_engine_node`, `wmx_ethercat_node`	EtherCAT network scan and diagnostics

Node Coordination#

Nodes start up in a fixed order, coordinated by two ready heartbeat topics so that dependent nodes only activate once the engine and motion layers are live:

        sequenceDiagram
    participant E as wmx_engine_node
    participant C as wmx_core_motion_node
    participant I as wmx_io_node / wmx_ethercat_node
    participant M as manipulator controllers

    E->>E: CreateDevice + StartCommunication
    E-->>C: /wmx/engine/ready (Bool)
    E-->>I: /wmx/engine/ready (Bool)
    E-->>M: /wmx/engine/ready (Bool)
    C-->>M: /wmx/core_motion/ready (Bool)
    Note over M: joint_state_broadcaster waits on<br/>/wmx/core_motion/ready before publishing

Node startup coordination via ready signals#

wmx_engine_node creates the WMX device, starts EtherCAT communication, and publishes /wmx/engine/ready.
wmx_core_motion_node, wmx_io_node, wmx_ethercat_node, gripper_controller, and joint_trajectory_controller wait for /wmx/engine/ready before activating.
wmx_core_motion_node publishes /wmx/core_motion/ready; joint_state_broadcaster waits for it before loading parameters and publishing joint feedback.

General Nodes#

wmx_engine_node#

Manages the WMX device lifecycle: creates the device, starts/stops EtherCAT communication, and publishes a ready signal to coordinate dependent nodes. On startup it automatically calls CreateDevice and StartCommunication, and also exposes manual-override services.

Source: src/wmx_engine_node.cpp — Node name: wmx_engine_node

Services#
Service	Type	Description
`/wmx/engine/set_device`	`wmx_r2_message/srv/SetEngine`	Create or close the WMX device handle
`/wmx/engine/set_comm`	`std_srvs/srv/SetBool`	Start or stop EtherCAT communication
`/wmx/engine/get_status`	`std_srvs/srv/Trigger`	Query engine state (Idle/Running/Communicating/Shutdown)
`/wmx/engine/scan_network`	`std_srvs/srv/Trigger`	Trigger EtherCAT network scan to discover slaves

Publishes /wmx/engine/ready (std_msgs/msg/Bool) — true when communication is active, false on shutdown.

wmx_core_motion_node#

Provides service-based axis control, XML parameter load/get, topic-based motion commands, and per-axis state publishing. Waits for /wmx/engine/ready before activating.

Source: src/wmx_core_motion_node.cpp — Node name: wmx_core_motion_node

Services#
Service	Type	Description
`/wmx/axis/set_on`	`wmx_r2_message/srv/SetAxis`	Enable/disable servo drives
`/wmx/axis/clear_alarm`	`wmx_r2_message/srv/SetAxis`	Clear amplifier faults
`/wmx/axis/set_mode`	`wmx_r2_message/srv/SetAxis`	Set position (0) or velocity (1) mode
`/wmx/axis/set_polarity`	`wmx_r2_message/srv/SetAxis`	Set rotation direction (1 or -1)
`/wmx/axis/set_gear_ratio`	`wmx_r2_message/srv/SetAxisGearRatio`	Configure encoder gear ratio
`/wmx/axis/homing`	`wmx_r2_message/srv/SetAxis`	Set current position as home (zero)
`/wmx/params/load`	`wmx_r2_message/srv/LoadWmxParams`	Load axis parameters from a WMX3 XML file
`/wmx/params/get`	`wmx_r2_message/srv/GetWmxParams`	Retrieve active axis parameters as text

Published topic: /wmx/axis/state (wmx_r2_message/msg/AxisState, 100 Hz) — full per-axis status.

Subscribed topics: /wmx/axis/velocity (AxisVelocity → CoreMotion::StartVel()), /wmx/axis/position (AxisPose → CoreMotion::StartPos()), /wmx/axis/position/relative (AxisPose → CoreMotion::StartMov()). Also publishes /wmx/core_motion/ready.

wmx_io_node#

Service-based access to EtherCAT digital I/O. Waits for /wmx/engine/ready.

Source: src/wmx_io_node.cpp — Node name: wmx_io_node

Services#
Service	Type	Description
`/wmx/io/get_input_bit`	`wmx_r2_message/srv/GetIoBit`	Read a single digital input bit
`/wmx/io/get_output_bit`	`wmx_r2_message/srv/GetIoBit`	Read back a digital output bit
`/wmx/io/get_input_bytes`	`wmx_r2_message/srv/GetIoBytes`	Read a block of digital input bytes
`/wmx/io/get_output_bytes`	`wmx_r2_message/srv/GetIoBytes`	Read a block of digital output bytes
`/wmx/io/set_output_bit`	`wmx_r2_message/srv/SetIoBit`	Write a single digital output bit
`/wmx/io/set_output_bytes`	`wmx_r2_message/srv/SetIoBytes`	Write a block of digital output bytes

wmx_ethercat_node#

EtherCAT diagnostic services for network monitoring and debugging. Waits for /wmx/engine/ready.

Source: src/wmx_ethercat_node.cpp — Node name: wmx_ethercat_node

Services#
Service	Type	Description
`/wmx/ecat/get_network_state`	`wmx_r2_message/srv/EcatGetNetworkState`	Full network state: master + all slaves
`/wmx/ecat/register_read`	`wmx_r2_message/srv/EcatRegisterRead`	Read raw EtherCAT register from a slave
`/wmx/ecat/reset_statistics`	`wmx_r2_message/srv/EcatResetStatistics`	Reset packet loss / timing counters
`/wmx/ecat/start_hotconnect`	`wmx_r2_message/srv/EcatStartHotconnect`	Initiate hot-connect for dynamic slave addition

Manipulator Controllers#

joint_state_broadcaster#

Loads the robot’s WMX axis parameters and publishes encoder feedback as JointState (plus simulator mirrors). Waits for /wmx/core_motion/ready before publishing.

Source: src/joint_state_broadcaster.cpp — Node name: joint_state_broadcaster

Parameters#
Parameter	Type	Description
`joint_axes`	`int[]`	WMX axis indices for the robot joints (e.g. `[0,1,2,3,4,5]`)
`joint_feedback_rate`	`int`	Encoder publish rate in Hz
`gripper_open_value` / `gripper_close_value`	`double`	Joint position reported when the gripper is open / closed
`joint_name`	`string[]`	Joint names for the JointState message
`gripper_joint_name`	`string[]`	Gripper finger joint names (e.g. `picker_1_joint`, `picker_2_joint`)
`gripper_address`	`int[]`	I/O `[byte, bit]` address read for gripper state
`encoder_joint_topic`	`string`	Primary joint state topic (typically `/joint_states`)
`isaacsim_joint_topic`	`string`	Isaac Sim joint command topic
`gazebo_joint_topic`	`string`	Gazebo position controller topic
`wmx_param_file_path`	`string`	Absolute path to the WMX axis parameter XML (resolved at launch)

Published Topics#
Topic (param)	Message Type	Description
`encoder_joint_topic`	`sensor_msgs/msg/JointState`	Joint positions + gripper state
`isaacsim_joint_topic`	`sensor_msgs/msg/JointState`	Mirror for Isaac Sim
`gazebo_joint_topic`	`std_msgs/msg/Float64MultiArray`	Joint positions for Gazebo

joint_trajectory_controller#

Action server that executes MoveIt2-planned trajectories on the robot using WMX cubic spline interpolation. Waits for /wmx/engine/ready.

Source: src/joint_trajectory_controller.cpp — Node name: joint_trajectory_controller

Parameters#
Parameter	Type	Description
`joint_axes`	`int[]`	WMX axis indices (sets the spline `dimensionCount`)
`joint_trajectory_action`	`string`	Action server name for `FollowJointTrajectory`

Hosts the FollowJointTrajectory action (control_msgs/action/FollowJointTrajectory). See ROS2 Actions for the full execution details.

gripper_controller#

Controls the pneumatic gripper via EtherCAT digital I/O. Waits for /wmx/engine/ready.

Source: src/gripper_controller.cpp — Node name: gripper_controller

Parameters#
Parameter	Type	Description
`wmx_gripper_topic`	`string`	Service name for gripper open/close (typically `/wmx/set_gripper`)
`gripper_address`	`int[]`	I/O `[byte, bit]` address written to actuate the gripper

The gripper service is a std_srvs/srv/SetBool (true = close, false = open) backed by Io::SetOutBit.

Launch Files#

wmx_r2_general_nodes.launch.py#

Starts the four general nodes for standalone axis/IO/EtherCAT control without manipulator controllers.

Nodes launched: wmx_engine_node, wmx_core_motion_node, wmx_io_node, wmx_ethercat_node.

Arguments: use_sim_time (default false). Config: none.

ros2 launch wmx_r2_package wmx_r2_general_nodes.launch.py

wmx_r2_cr3a_manipulator.launch.py#

Full Dobot CR3A manipulator launch. Includes wmx_r2_general_nodes.launch.py and then starts the manipulator controllers.

Nodes launched: the four general nodes (via include), plus joint_state_broadcaster, joint_trajectory_controller, and gripper_controller.

Arguments: use_sim_time (default false). Config: config/cr3a_manipulator_config.yaml and config/cr3a_wmx_parameters.xml (the WMX parameter path is resolved at launch time).

ros2 launch wmx_r2_package wmx_r2_cr3a_manipulator.launch.py \
  use_sim_time:=false

wmx_r2_cr5a_manipulator.launch.py#

Full Dobot CR5A manipulator launch. Includes the general nodes and starts joint_state_broadcaster and joint_trajectory_controller.

Arguments: use_sim_time (default false). Config: config/cr5a_manipulator_config.yaml and config/cr5a_wmx_parameters.xml.

ros2 launch wmx_r2_package wmx_r2_cr5a_manipulator.launch.py \
  use_sim_time:=false

Note

The launch commands above assume the workspace is already sourced. On real hardware the nodes require sudo with the ROS2 environment preserved — see Install WMX R2 Package for the full sudo --preserve-env invocation.

Configuration Files#

cr3a_manipulator_config.yaml#

Parameters for the Dobot CR3A manipulator, shared by the three manipulator controllers:

joint_state_broadcaster:
  ros__parameters:
    joint_feedback_rate: 100
    gripper_open_value: 0.00
    gripper_close_value: 0.045
    joint_axes: [0, 1, 2, 3, 4, 5]
    joint_name: ["joint1", "joint2", "joint3", "joint4", "joint5", "joint6"]
    gripper_joint_name: ["picker_1_joint", "picker_2_joint"]
    gripper_address: [0, 0]
    encoder_joint_topic: /joint_states
    isaacsim_joint_topic: /isaacsim/joint_command
    gazebo_joint_topic: /gazebo_position_controller/commands
    wmx_param_file_path: ""   # resolved at launch via get_package_share_directory

joint_trajectory_controller:
  ros__parameters:
    joint_axes: [0, 1, 2, 3, 4, 5]
    joint_trajectory_action: /movensys_manipulator_arm_controller/follow_joint_trajectory

gripper_controller:
  ros__parameters:
    wmx_gripper_topic: /wmx/set_gripper
    gripper_address: [0, 0]

cr5a_manipulator_config.yaml#

The CR5A equivalent of the CR3A config, used by the CR5A launch file. It configures joint_state_broadcaster and joint_trajectory_controller for the CR5A robot.

WMX Parameter XML Files#

Robot-specific WMX parameter files define per-axis motor configuration (gear ratios, polarities, limits, home positions):

cr3a_wmx_parameters.xml – Dobot CR3A manipulator (6 joints)
cr5a_wmx_parameters.xml – Dobot CR5A manipulator (6 joints)
diffbot_wmx_parameters.xml – differential-drive base axes

These files are loaded at runtime via CoreMotion::config->ImportAndSetAll(path), by the controller that owns the axes — joint_trajectory_controller or differential_drive_controller, using the wmx_param_file_path parameter. The four general nodes load no parameter file.

Warning

These are the parameters that decide how far and in which direction each joint moves. A shipped file describes the robot MOVENSYS commissioned, not your unit. For what every field means, where its value comes from, and how to verify it against the running engine, see Robot Parameter Configuration and Validation.

Building the Package#

This package depends on wmx_r2_message and must be built after it:

cd ~/workspaces/movensys_ws

# Stage 1: Build message package
colcon build --packages-select wmx_r2_message
source install/setup.bash

# Stage 2: Build application package
colcon build --packages-select wmx_r2_package
source install/setup.bash

Verify executables are available:

ros2 pkg executables wmx_r2_package

Expected:

wmx_r2_package differential_drive_controller
wmx_r2_package gripper_controller
wmx_r2_package joint_position_controller
wmx_r2_package joint_state_broadcaster
wmx_r2_package joint_trajectory_controller
wmx_r2_package wmx_core_motion_node
wmx_r2_package wmx_engine_node
wmx_r2_package wmx_ethercat_node
wmx_r2_package wmx_io_node
wmx_r2_package wmx_io_node