Install WMX R2 Package#

With the Computer Setup complete (real-time kernel, ROS 2, and the WMX runtime in place), build the WMX R2 packages.

Configure the environment#

Add the following to your ~/.bashrc:

export ROS_DOMAIN_ID=70                         #use any number
export ROS_DISTRO=jazzy                         #support {jazzy, humble}
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

source /opt/ros/$ROS_DISTRO/setup.bash
source ~/workspaces/movensys_ws/install/setup.bash

Apply the changes:

source ~/.bashrc

Install Required ROS2 Dependencies#

sudo apt update
sudo apt install -y ros-${ROS_DISTRO}-graph-msgs \
                 ros-${ROS_DISTRO}-moveit-ros \
                 ros-${ROS_DISTRO}-moveit-planners \
                 ros-${ROS_DISTRO}-moveit-plugins \
                 ros-${ROS_DISTRO}-moveit-setup-assistant \
                 ros-${ROS_DISTRO}-moveit-configs-utils \
                 ros-${ROS_DISTRO}-moveit-task-constructor-core \
                 ros-${ROS_DISTRO}-ros2-control \
                 ros-${ROS_DISTRO}-ros2-controllers \
                 ros-${ROS_DISTRO}-rmw-cyclonedds-cpp
sudo apt install -y python3-colcon-common-extensions python3-rosdep

Create Workspace and Build#

Create workspace

mkdir -p ~/workspaces/movensys_ws/src
cd ~/workspaces/movensys_ws/src && \
git clone https://github.com/movensys/wmx-r2.git

Rosdep update

sudo rosdep init   # only needed once per system
rosdep update
cd ~/workspaces/movensys_ws
rosdep install --from-paths src --ignore-src -y

Build (wmx_r2_package depends on wmx_r2_message, so build the message package first):

cd ~/workspaces/movensys_ws

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

# Stage 2: build all remaining packages
colcon build
source install/setup.bash

Verify Installation#

ros2 pkg list | grep wmx && ros2 pkg executables wmx_r2_package

Expected:

wmx_r2_control
wmx_r2_message
wmx_r2_package
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

Testing WMX R2#

Once WMX R2 is installed and built, you can validate it in two ways: in simulation (no physical hardware required) or against real EtherCAT hardware. Start with simulation to verify basic behavior, then move to real hardware.

The WMX R2 nodes communicate directly with the WMX engine over EtherCAT — there is no built-in mock hardware mode. The mode is selected in /opt/wmx3/Module.ini by enabling either the simulation or the EtherCAT platform. Select your mode below, then continue with the common test steps that follow.

Use the simulation platform to test without any physical hardware connected.

Setup WMX in simulation mode

Modify /opt/wmx3/Module.ini to disable the EtherCAT platform and enable the simulation platform:

[Platform 0]
Location = ./platform/ethercat
DllName = ec_platform.so
NumOfMaster = 1
disable = 1

[Platform 1]
Location = ./platform/simu
DllName = simu_platform.so
NumOfMaster = 1
disable = 0

This covers testing against any EtherCAT hardware (a robot, a standalone servo drive, an I/O module, etc.). The examples below use the Dobot CR3A manipulator, but the same procedure applies to any EtherCAT device.

Prerequisites

  • The WMX R2 workspace is built and sourced

  • The WMX Runtime is installed at /opt/wmx3/

  • EtherCAT cable is connected between compute platform and first EtherCAT device

  • The hardware and all servo drives are powered on

  • You have sudo privileges

EtherCAT Wiring

┌──────────────┐    Ethernet     ┌──────────┐    ┌──────────┐         ┌──────────┐
│  Compute PC  │────(EtherCAT)──►│ Servo J1 │───►│ Servo J2 │── ... ──│ Servo J6 │
│  (dedicated  │                 └──────────┘    └──────────┘         └──────────┘
│   NIC port)  │
└──────────────┘

  • Use a dedicated Ethernet port for EtherCAT

  • Servo drives are daisy-chained (each drive has IN and OUT ports)

  • The I/O module for gripper control is part of the same chain

Setup WMX in real hardware mode

Modify /opt/wmx3/Module.ini to enable the EtherCAT platform and disable the simulation platform:

[Platform 0]
Location = ./platform/ethercat
DllName = ec_platform.so
NumOfMaster = 1
disable = 0

[Platform 1]
Location = ./platform/simu
DllName = simu_platform.so
NumOfMaster = 1
disable = 1

Warning

Real Hardware mode moves a physical machine.

Start with the Simulation platform. Before switching to EtherCAT and enabling servos on a robot, complete Commissioning — parameter validation, the low-speed single-axis procedure, and the separate safety measures described in Safety Functions and Responsibility.

Test the WMX R2 General Nodes (Standalone)#

sudo --preserve-env=PATH \
  --preserve-env=AMENT_PREFIX_PATH \
  --preserve-env=COLCON_PREFIX_PATH \
  --preserve-env=PYTHONPATH \
  --preserve-env=LD_LIBRARY_PATH \
  --preserve-env=ROS_DISTRO \
  --preserve-env=ROS_VERSION \
  --preserve-env=ROS_PYTHON_VERSION \
  --preserve-env=ROS_DOMAIN_ID \
  --preserve-env=RMW_IMPLEMENTATION \
  bash -c "source /opt/ros/${ROS_DISTRO}/setup.bash && source $HOME/workspaces/movensys_ws/install/setup.bash && \
  ros2 launch wmx_r2_package wmx_r2_general_nodes.launch.py"

Startup Sequence#

wmx_r2_general_nodes.launch.py starts four robot-agnostic nodes — wmx_engine_node, wmx_core_motion_node, wmx_io_node, and wmx_ethercat_node:

  1. Device creation – wmx_engine_node creates the WMX device handle, retrying up to five times if another application holds the lock (error 297). The remaining nodes then attach to that device.

  2. Communication start – StartCommunication brings up the real-time EtherCAT cycle, which discovers the drives on the bus.

  3. Ready – each node publishes on its ready topic and begins serving its services and topics.

Warning

The general nodes load no robot parameters and enable no servos.

These four nodes are robot-agnostic by design. They do not apply a <robot>_wmx_parameters.xml file, so the gear ratios, polarities, command modes, and limits in the engine are whatever was left there by a previous session — not your robot’s values. They also do not enable the servos; that is an explicit /wmx/axis/set_on call.

Robot parameters are applied by the per-robot launches (wmx_r2_<robot>_manipulator.launch.py and wmx_r2_diffbot_navigation.launch.py), which pass wmx_param_file_path to their controllers, or by the ros2_control hardware plugin. If you command motion from the general nodes alone, load the parameters first:

ros2 service call /wmx/params/load wmx_r2_message/srv/LoadWmxParams \
     "{file_path: '/abs/path/to/<robot>_wmx_parameters.xml'}"
ros2 service call /wmx/params/get wmx_r2_message/srv/GetWmxParams \
     "{index: [0,1,2,3,4,5]}"

See Robot Parameter Configuration and Validation.

Testing WMX R2 Services and Topics#

The general nodes expose the WMX engine, axis, I/O, and EtherCAT control interfaces as ROS2 services and topics. List what is available and confirm the engine is communicating:

ros2 service list | grep /wmx                                  # Available WMX services
ros2 topic list | grep /wmx                                    # Available WMX topics
ros2 service call /wmx/engine/get_status std_srvs/srv/Trigger  # Expect: "Communicating"
ros2 service call /wmx/ecat/get_network_state \
     wmx_r2_message/srv/EcatGetNetworkState                  # EtherCAT master/slave status

For the complete list of services, topics, and message types exposed by the general nodes — engine control, axis motion, I/O, and EtherCAT — see the WMX R2 General Nodes reference.

Shutdown#

Press Ctrl+C in the launch terminal. The nodes will automatically disable servos, stop EtherCAT communication, and close the WMX device.