AgileX UGV SDK — Universal CAN Platform SDK

1. Overview

The ugv_sdk is AgileX Robotics' open-source C++ library that provides a unified software interface to all AgileX mobile platforms over the CAN bus. Rather than platform-specific drivers, ugv_sdk abstracts the underlying CAN protocol into a consistent API — the same code that commands a SCOUT 2.0 also works unmodified on a BUNKER, TRACER, or RANGER.

The library supports two protocol versions: Protocol V1 (legacy) and Protocol V2 (current). All platforms produced from 2021 onward use Protocol V2. Protocol V1 support is retained for backward compatibility with older Scout, Scout Mini, Hunter 1.0, and Bunker units.

For Python users, the pyagxrobots package provides Python bindings for ugv_sdk via pip, allowing rapid prototyping and integration with navigation stacks written in Python without compiling the C++ library directly.

2. Supported Platforms

The table below shows protocol version support, available interfaces, and current support status for each AgileX platform.

3. Installation

C++ Library

Build and install ugv_sdk from source. The library requires CMake 3.10+, a C++14-compatible compiler, and the SocketCAN development headers (libsocketcan-dev on Ubuntu).

# Install dependencies (Ubuntu 20.04 / 22.04)
sudo apt install build-essential cmake libsocketcan-dev

# Clone the repository
git clone https://github.com/agilexrobotics/ugv_sdk.git
cd ugv_sdk && mkdir build && cd build

# Build and install
cmake .. && make -j4
sudo make install

After installation, the headers are available at /usr/local/include/ugv_sdk/ and the library at /usr/local/lib/libugv_sdk.so. Link with -lugv_sdk in your CMakeLists.txt.

Python Binding (pyagxrobots)

For Python-first workflows, install the official Python binding via pip. No C++ compilation required.

pip install pyagxrobots

4. CAN Bus Setup

All AgileX platforms use CAN 2.0B at 500 kbps. You will need a GS_USB-compatible USB-to-CAN adapter (e.g., CANable, Waveshare USB-CAN-A). Connect it to the robot's CAN port before running any of the commands below.

Bring up the CAN interface

# Load the GS_USB kernel module
sudo modprobe gs_usb

# Bring up can0 at 500 kbps
sudo ip link set can0 up type can bitrate 500000

# Verify the interface is up and running
ip link show can0

# Optional: dump raw CAN frames for diagnostics
candump can0

Persistent setup across reboots

Each platform's ROS2 package ships two shell scripts that handle persistence automatically:

# Run once after first hardware connection to configure the adapter
bash setup_can2usb.bash

# Run on each subsequent boot before launching any ROS2 node
bash bringup_can2usb.bash

Both scripts are located in the scripts/ directory of the platform-specific ROS2 package (e.g., scout_ros2/scripts/).

5. Protocol Details

6. ROS2 Usage

All AgileX platforms follow an identical ROS2 launch pattern. Replace <robot> with the platform name: scout, ranger, bunker, tracer, hunter, or limo.

Install the platform's ROS2 package

# Example for SCOUT — replace 'scout' with your platform
cd ~/ros2_ws/src
git clone https://github.com/agilexrobotics/scout_ros2.git
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash

Launch the base driver

# Bring up the CAN interface first (if not already up)
bash ~/ros2_ws/src/scout_ros2/scripts/bringup_can2usb.bash

# Launch the robot base driver
ros2 launch scout_base scout_base.launch.py port_name:=can0

# In a second terminal — keyboard teleoperation
ros2 run teleop_twist_keyboard teleop_twist_keyboard

Velocity command topic

All platforms subscribe to /cmd_vel (type: geometry_msgs/msg/Twist) and publish odometry on /odom and robot status on /robot_state. The topic names and message types are consistent across all platforms.

# Check available topics after launching the driver
ros2 topic list

# Send a manual velocity command (0.3 m/s forward, 0 angular)
ros2 topic pub /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.3, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}"

7. Gazebo Simulation

AgileX provides a unified Gazebo simulation package for all UGV platforms at ugv_gazebo_sim. The simulation uses the same ROS2 topic interface as the real hardware, so code developed in simulation transfers to the physical robot without modification.

# Clone the Gazebo sim package
cd ~/ros2_ws/src
git clone https://github.com/agilexrobotics/ugv_gazebo_sim.git
cd ~/ros2_ws && colcon build --symlink-install
source install/setup.bash

# Launch SCOUT 2.0 in Gazebo (replace 'scout' with your platform)
ros2 launch scout_description scout_gazebo.launch.py

8. Key Links