Damiao Omnidirectional AGV Base — DBUS Protocol & Teleop Guide

1. Overview

The Damiao AGV (达妙 AGV) is a four-wheel omnidirectional mobile base with independent steering and drive on all four wheels (4WS4WD configuration). Its omnidirectional kinematics — using Mecanum or omni wheels — allow the base to move laterally, diagonally, and rotate in place without any turning radius constraint. This makes it well-suited for manipulation tasks in cluttered environments, mobile manipulation data collection, and whole-body teleoperation setups where precise base positioning is required.

The AGV's open-source firmware communicates via its main controller's UART5 interface (pin PD2, RX), accepting RC receiver-style DBUS/SBUS control frames at 100000 baud with 8 data bits, even parity, and 2 stop bits (8E2). The dami_agent.py bridge script connects a PC via USB-to-TTL adapter to this UART, translates high-level platform commands (move, stop, goal) into properly encoded 18-byte DBUS frames, and forwards them at a configurable control rate — all without modifying the AGV firmware.

The agent simultaneously maintains a WebSocket connection to the Fearless Platform, enabling real-time teleoperation from the browser UI, telemetry reporting, command timeout safety stops, and episode recording for mobile manipulation datasets.

2. Full Specifications

3. Quick Start

1. Install dependencies.

   pip install pyserial websockets

2. Connect the USB-to-TTL adapter. Wire the adapter's TX pin to the AGV main controller's UART5_RX (PD2). Connect GND. Do NOT connect the adapter's RX or 5V to the AGV. Confirm the port appears:

   ls /dev/ttyUSB*   # Linux

3. Create a teleop session on the platform. Open platform.roboticscenter.ai, navigate to the Teleop section, and create a new session. Copy the session ID (format: RC-XXXX-XXXX).
4. Launch the AGV agent.

   python3 dami_agent.py \
     --session RC-XXXX-XXXX \
     --serial-port /dev/ttyUSB0 \
     --backend ws://localhost:8000

   The agent connects to the platform, registers the AGV node, and begins the control loop at 30 Hz.
5. Drive from the browser. Open the session URL in your browser. Use the directional controls to send move commands. The AGV responds within one control-loop tick (33 ms at default 30 Hz).

4. DBUS Protocol

The Damiao AGV firmware expects standard DBUS/SBUS RC receiver frames on its UART5 input. The agent encodes velocity commands as RC joystick values in this format without any firmware modification required.

18-byte frame layout

The 11-bit channels are packed consecutively starting from bit 0 of byte 0:

# bit-packing of ch0..ch3 into bytes 0..5
b[0] =  ch0 & 0xFF
b[1] = (ch0 >> 8 & 0x07) | ((ch1 & 0x1F) << 3)
b[2] = (ch1 >> 5 & 0x3F) | ((ch2 & 0x03) << 6)
b[3] =  ch2 >> 2 & 0xFF
b[4] = (ch2 >> 10 & 0x01) | ((ch3 & 0x7F) << 1)
b[5] =  ch3 >> 7 & 0x0F    # upper nibble: switch bits

# ch4 in bytes 16..17
b[16] = ch4 & 0xFF
b[17] = ch4 >> 8 & 0x07

Channel-to-velocity mapping

The AGV firmware's Control_Task decodes channels as follows. The agent must invert this mapping when encoding velocity commands:

Channel values are clamped to [0, 2047]. At center (1024 on all channels), the AGV holds position. The amp parameter (default 660) sets the magnitude of deflection from center — higher values produce faster motion. The agent accepts vx, vy, and vw as discrete sign values (−1, 0, +1) from the platform command messages.

5. SDK / Python Usage

The dami_agent.py script is the primary interface between the Fearless Platform and the AGV hardware. It runs two async loops — a control loop and a telemetry loop — inside a single WebSocket session.

Agent CLI reference

Sending commands programmatically

The agent receives platform commands as JSON messages over its WebSocket. You can send commands from any platform client or script using the session WebSocket. Supported command types:

# Move forward along X axis
{"type": "move", "axis": "x", "dir": 1}

# Move laterally right (Y axis)
{"type": "move", "axis": "y", "dir": 1}

# Rotate counter-clockwise (Z axis)
{"type": "move", "axis": "z", "dir": -1}

# Stop all motion immediately
{"type": "stop"}

# Goal-based delta movement (x, y, yaw)
{"type": "goal", "delta": {"x": 0.5, "y": 0.0, "yaw": 0.0}}

The goal command degrades the continuous delta to a discrete direction sign, matching the agent's discrete velocity model. For smooth continuous control, send repeated move commands at the desired rate and stop when the target is reached.

Shutdown safety

On agent exit (Ctrl+C or WebSocket close), the agent sends three center-position DBUS frames (all channels at 1024) separated by 30 ms delays before closing the serial port. This ensures the AGV firmware receives the stop signal even if the final command was a movement.

6. Platform Integration

The agent connects to /api/teleop/ws on the Fearless Platform backend and registers the AGV as a robot node. The WebSocket handshake:

{
  "role": "robot",
  "session_id": "RC-XXXX-XXXX",
  "member_id": "dami-agv-node",
  "node_id": "dami-agv-node",
  "node_role": "robot",
  "device_type": "mobile_base",
  "capabilities": ["mobile_base", "agv", "telemetry"],
  "source_host": "hostname"
}

Telemetry format

The agent sends telemetry at the configured --telemetry-hz rate. The joints field reuses the generic telemetry structure to carry the discrete velocity command state:

{
  "type": "telemetry",
  "member_id": "dami-agv-node",
  "joints": {
    "vx_cmd": 1.0,    // current commanded X velocity sign
    "vy_cmd": 0.0,
    "vw_cmd": 0.0
  },
  "feedback": {
    "connected": true,
    "robot_model": "dami_agv_4ws4wd",
    "transport": "serial_dbus",
    "serial_port": "/dev/ttyUSB0",
    "amp": 660,
    "cmd_timeout_ms": 300
  },
  "ts": 1743680400123
}

Latency ping/pong

The platform sends periodic ping_latency messages. The agent responds with pong_latency immediately, preserving the original ts and id fields. The platform uses these round trips to display round-trip latency in the teleop session header.

Episode recording

When a recording session is active on the platform, all telemetry frames from the AGV node are archived alongside other session nodes (arm, cameras, tactile sensors). The resulting JSONL archive captures the complete mobile manipulation trajectory, including base velocity commands and timing, enabling full replay and training data extraction.

7. Troubleshooting

8. Related Hardware

The Damiao AGV is commonly deployed as a mobile base in combination with manipulation hardware:

• Wuji Dexterous Hand — Can be mounted on a robot arm attached to the AGV for whole-body mobile manipulation. Both register as separate nodes in the same teleop session.
• LinkerBot O6 — Dexterous end effector for picking tasks on mobile platforms. The O6 agent and AGV agent can share a single platform session for synchronized recording.
• Paxini PX-6AX GEN3 — Tactile sensors on a mobile manipulator's end effector; recorded synchronously with the AGV base motion for contact-rich mobile manipulation datasets.
• VLAI L1 — Full humanoid platform; see this page for whole-body locomotion integration patterns as a reference for integrating the AGV base with upper-body hardware.