dexcontrol-rosbridge

A Python bridge for republishing sensor data between Zenoh and ROS2 networks when using Dexmate Robots.

Installation

Prerequisites

• Ubuntu 22.04 or 24.04
• Python 3.10+
• ROS2 (Humble or Jazzy)
• dexcontrol library installed and configured

Deployment Flexibility:

This package can run on either:

• Local development machine (recommended for development and testing)
• Jetson onboard computer

As long as dexcontrol can connect to the robot and Zenoh network, you can run this ROS bridge and other ROS applications on your local dev machine instead of the robot's Jetson.

Note: We recommend using robostack and micromamba for the ROS2 and Python environments instead of the system-level ROS2 (at /opt/ros). Please follow the instructions here to create a micromamba environment with ROS2 inside.

If you have ROS2 installed on your system (i.e., at /opt/ros/{ROS_DISTRO}), please DO NOT source it before activating the micromamba environment to avoid environment conflicts. The keys to successful communication between your system ROS2 and the mamba ROS2 are:

1. Make sure to use the same ROS2 distribution. (e.g., communication between Jazzy and Humble is problematic)
2. Make sure to use the same RMW_IMPLEMENTATION (by default it's the same)

Install from source

# Activate your micromamba environment with ROS2 installed first
# micromamba activate ros_env
pip install dexcontrol_rosbridge

# Or install from source code below
# git clone https://github.com/dexmate-ai/dexcontrol-rosbridge.git
# pip install -e ./dexcontrol-rosbridge/

Usage

Re-publish sensor streams from Zenoh topics

First, make sure you set the correct robot name. This is the prefix for Zenoh topics. You can access the robot name on your robot's onboard computer by running echo $ROBOT_NAME. Also ensure that the corresponding sensors (e.g., head_camera or lidar) have been started using dexsensor launch --sensor.

export ROBOT_NAME=[...]

The repository provides a unified script that handles sensor types through command-line arguments:

# Publish head cameras and IMU
python scripts/republish_sensors.py --sensors head

# Publish LIDAR only
python scripts/republish_sensors.py --sensors lidar

# Publish LIDAR and chassis IMU together
python scripts/republish_sensors.py --sensors lidar chassis_imu

Available sensor groups (defaults from configs/sensor_mapping.yaml):

• head_left - Head left camera (RGB)
• head_right - Head right camera (RGB)
• head_depth - Head depth camera
• head_imu - Head IMU sensor
• lidar - Base LIDAR sensor (PointCloud2)
• chassis_imu - Chassis IMU sensor
• wrist - Wrist cameras (left/right RGB), publishes both streams together
• all - Enable every configured group

Wheel odometry

Run:

python scripts/publish_wheel_odometry.py

This will publish the wheel odometry using the differential vehicle model on Vega. The published topics are:

/odom # the wheel odometry
/left_wheel_velocity
/right_wheel_velocity

Configuration

Sensor groups are defined in src/dexcontrol_rosbridge/configs/sensor_mapping.yaml. Each top-level key matches a CLI group:

head_left:
  description: "Head left camera (RGB)"
  type: camera
  sensors:
    - name: head_left_rgb
      zenoh_topic: "camera/head/left_rgb"
      ros2_topic: "/head_camera/left/image"
      frame_id: "head_camera_left_link"
      compressed: true
      compression_format: "jpeg"
      queue_size: 2

Add additional groups or streams by extending this file and passing --config <path> if you want to use a custom mapping outside the packaged defaults.

Architecture

Multi-Process Design

Each sensor stream runs in a dedicated process:

Main Process
├── Camera Process 1 (+ Zenoh Session + ROS2 Node)
├── Camera Process 2 (+ Zenoh Session + ROS2 Node)
├── IMU Process (+ Zenoh Session + ROS2 Node)
└── LIDAR Process (+ Zenoh Session + ROS2 Node)

This is primarily for GIL isolation.

Data Flow

Zenoh Network → Zenoh Handler → Bounded Queue → Consumer Thread → Converter → ROS2 Publisher

1. Zenoh Handler: Fast callback that enqueues samples (<0.1ms) without blocking
2. Bounded Queue: Small FIFO queue (size: 1-3) for maintaining temporal ordering
3. Consumer Thread: Single thread that processes samples sequentially (preserves order)
4. Converter: Decodes and converts data to ROS2 message format
5. ROS2 Publisher: Publishes to ROS2 topics with proper timestamps and frame IDs

Congestion Handling:

• When processing can't keep up with incoming rate, oldest frames are dropped
• Drop statistics are logged

License

GNU Affero General Public License v3.0 (AGPL-3.0)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.