Quickstart Guide

Step-by-step setup guides for both supported communication pathways: ROS 2 with CycloneDDS RMW, and standalone Native CycloneDDS. Follow the path that matches your development environment.

Quickstart: ROS 2

This guide provides the necessary steps to configure a ROS 2 development environment, compile the required message structures, and establish an initial communication with the Svan M2 robot.

1. System Prerequisites

To ensure consistent behavior within the ROS 2 ecosystem, the following development environment is recommended:

2. Installation & Workspace Setup

The Svan M2 utilizes custom message types to structure its remote commands and telemetry. Ensure these message types are compiled in a ROS 2 workspace before you interface with the robot.

2.1 Install Dependencies

Ensure the ROS 2 CycloneDDS implementation is installed on the host machine. The command below uses your active ROS 2 distribution environment variable:

sudo apt update
sudo apt install ros-$ROS_DISTRO-rmw-cyclonedds-cpp

2.2 Build the Workspace

Clone the SDK, create a new colcon workspace, and build the custom message interfaces and validation nodes:

# 1. Clone the Svan M2 SDK repository (e.g., into your home directory)
cd ~
git clone https://github.com/xterra-robotics/m2_sdk.git

# 2. Create an isolated colcon workspace
mkdir -p ~/m2_ws
cd ~/m2_ws

# 3. Source the base ROS 2 installation (change 'humble' to 'foxy' if using ros2 foxy)
source /opt/ros/humble/setup.bash

# 4. Build the SDK using the base-paths argument to point to the cloned repo
colcon build \
  --base-paths ~/m2_sdk \
  --cmake-args -DBUILD_ROS2=ON -DBUILD_EXAMPLES=ON

2.3 Source the Environment

After a successful build, source the overlay setup script to expose the newly compiledxterra_msgs to the environment.

source ~/m2_ws/install/setup.bash

3. Network Configuration

The host machine should be connected to the same subnet as the Svan M2 robot. Additionally, the RMW implementation must be explicitly set to CycloneDDS to ensure packet compatibility with the robot.

The SDK repository includes a cyclonedds.xml configuration file. User have to edit this file to specify your host machine's active network interface.

1. Identify your network interface connected to the robot (e.g., wlp0s20f3) by executing the ifconfig or ip a command in your terminal.
2. Open the cyclonedds.xml file located in the cloned SDK repository.
3. Replace the value inside the <NetworkInterfaceAddress> tags with your identified interface name.

Once the file is updated, execute the following network configurations in the active terminal:

# Enforce CycloneDDS as the active ROS 2 middleware
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

# Point the middleware to the configured XML file
export CYCLONEDDS_URI=file:///absolute/path/to/m2_sdk/cyclonedds.xml

4. Hello World: Reading Telemetry

Before transmitting commands to robot, it is recommended to verify setup by subscribing to the robot's hardware telemetry stream.

The following ROS 2 command utilizes the CLI to echo the onboard sensor data. If the network configuration and message compilation were successful, this command will continuously stream the robot's state.

Option A: Using ROS 2 CLI

# Verify the topic exists on the network
ros2 topic list | grep /m2_metal/hw/sensor_data

# Echo the real-time battery voltage and system diagnostics
ros2 topic echo /m2_metal/hw/sensor_data

Option B: Using the SDK Validation Node

# Run the custom formatted C++ node
ros2 run xterra_msgs svan_sensor_echo_ros2

Expected Output:

The terminal should output the structured SensorData array. To verify a live and accurate connection, physically move one of the robot's joints and observe the q (joint position) array values changing dynamically in the terminal output.

Quickstart: Native CycloneDDS

This guide provides the steps to configure a standalone C++ development environment utilizing Eclipse CycloneDDS. This pathway bypasses the ROS 2 middleware (RMW) abstraction and type conversion overhead entirely, providing ultra-low latency access to the Svan M2 robot.

1. System Prerequisites

To ensure consistent builds and reliable network communication, the following development environment is recommended:

2. Installation & Workspace Setup

The DDS C++ method requires the Eclipse CycloneDDS core libraries to function. To streamline the installation process the SDK provides an automated setup script.

This script dynamically downloads, and compiles the necessary DDS dependencies directly into a local third_party folder within the m2_sdk folder. Once the environment is prepared, CMake commands are used to build the SDK's C++ message headers and validation executables.

Follow these steps to clone the repository, setup the environment, and compile the SDK:

# 1. Clone the Svan M2 SDK repository
cd ~
git clone https://github.com/xterra-robotics/m2_sdk.git
cd m2_sdk

# 2. Run the dynamic environment setup script
sudo chmod +x setup_dds_env.sh
./setup_dds_env.sh

# 3. Create a CMake build directory
mkdir build && cd build

# 4. Configure CMake to build the DDS pathway (ignoring ROS 2)
cmake .. -DBUILD_DDS=ON -DBUILD_EXAMPLES=ON

# 5. Compile the C++ headers and validation executables
make -j$(nproc)

3. Network Configuration

The host machine should be connected to the same subnet as the Svan M2 robot. CycloneDDS relies on an XML configuration string to bind to the correct physical network interface.

The SDK repository includes a cyclonedds.xml configuration file. User have to edit this file to specify your host machine's active network interface.

1. Identify the network interface connected to the robot (e.g., eth0 for Ethernet or wlan0 for Wi-Fi) by executing the ifconfig or ip a command in your terminal.
2. Open the cyclonedds.xml file located in the cloned SDK repository.
3. Replace the value inside the <NetworkInterfaceAddress> tags with your identified interface name.

Once the file is updated, execute the following network configuration in the active terminal:

# Point the middleware to the configured XML file
export CYCLONEDDS_URI=file:///absolute/path/to/m2_sdk/cyclonedds.xml

4. Hello World: Reading Telemetry

Before transmitting commands to robot, it is recommended to verify setup by subscribing to the robot's hardware telemetry stream.

The SDK compilation generates a standalone binary specifically designed to validate DDS packet reception. Execute this binary to echo the onboard sensor data on the same active terminal.

# Navigate to the compiled binaries directory
cd ~/m2_sdk/build/bin

# Execute the standalone sensor echo node
./svan_sensor_echo_dds

Expected Output:

The executable will output (stdout) logs of the parsed DDS packets. To verify a live and accurate connection, physically move one of the robot's joints and observe theJoint Pos values changing dynamically in the terminal output.

[DDS Sub] Successfully connected to Domain 0.
[DDS Sub] Listening on topic: rt/m2_metal/hw/sensor_data...
---
Voltage: 49.2 V | Temp: 0.0 C
Quat: [0.012, -0.005, 0.000, 0.999]
Joint[0] Pos: 0.01 rad
...