Damiao AGV Community & FAQ

What are the exact serial port settings for the Damiao AGV?

The AGV firmware listens on UART5 (pin PD2, RX) at 100000 baud with 8 data bits, even parity, and 2 stop bits (8E2). In pyserial, open the port with:

serial.Serial(
    port='/dev/ttyUSB0',
    baudrate=100000,
    bytesize=serial.EIGHTBITS,
    parity=serial.PARITY_EVEN,
    stopbits=serial.STOPBITS_TWO
)

A very common mistake is using 8N1 (no parity, 1 stop bit). The AGV will appear to connect but will silently ignore or misparse all frames. Always use PARITY_EVEN and STOPBITS_TWO.

How does the 18-byte DBUS frame encode velocity?

The DBUS frame packs four 11-bit channel values (ch0–ch3) into bytes 0–5 using little-endian bit-packing. Each channel ranges 0–2047 with 1024 as centre (neutral/stop). The velocity mapping is: ch3 = 1024 + vx × amp (forward), ch2 = 1024 + vy × amp (lateral), ch0 = 1024 + (−vw) × amp (rotation). Bytes 6–15 are zeroed mouse/keyboard fields. Bytes 16–17 hold ch4, fixed at 1024. See Specs for the complete channel map table.

The AGV moves briefly then stops — what is happening?

This is the command timeout safety feature triggering. If no move or stop command is received within --cmd-timeout-ms (default 300 ms), the agent automatically zeros all velocity channels and the AGV stops. This usually means the platform is not sending commands fast enough, or there is network latency causing gaps. Solutions: (1) increase --cmd-timeout-ms 500 for high-latency connections, (2) ensure the browser teleop panel is actively sending repeated move commands at ~10 Hz while a direction button is held, (3) check your network RTT to the platform.

The AGV moves in the wrong direction — how do I fix it?

Use the axis inversion flags on the agent — no firmware changes needed:

# Flip forward/backward
python3 dami_agent.py --session RC-XXXX --serial-port /dev/ttyUSB0 --invert-x

# Flip lateral (left/right)
python3 dami_agent.py ... --invert-y

# Flip rotation direction
python3 dami_agent.py ... --invert-z

Test each axis individually (e.g., send only an X command, observe motion) to determine which flags are needed for your physical installation orientation.

Can I test without the physical AGV?

Yes. Pass --mock when launching dami_agent.py. In mock mode, the serial port is never opened. The control loop still encodes DBUS frames (stored in memory), telemetry is forwarded to the platform WebSocket, and all command parsing works identically. This lets you verify the full WebSocket pipeline, test the platform UI, and integrate in CI without hardware:

python3 dami_agent.py --session RC-XXXX-XXXX --mock

I get pyserial.SerialException when launching — what do I check?

First: ls /dev/ttyUSB* to confirm the adapter appears. If it does not, the USB-to-TTL adapter driver may not be loaded (try a different USB port). If the port appears but you get a permission error, add your user to the dialout group:

sudo usermod -aG dialout $USER
# Log out and back in, then retry

If the port appears in device listing but the agent still cannot open it, another process may have it open (e.g., a previous agent instance or a serial monitor). Close all other processes using the port.

Agent connects but the platform shows no telemetry — what is wrong?

Confirm the session ID passed to --session is still active in the platform UI. Sessions can expire if inactive. Check the agent's terminal output for the registration handshake response — if it prints "handshake failed" or does not print "ready", the session may have expired. Create a new session in the platform and pass the new ID to the agent. Also verify that --backend points to the correct platform WebSocket URL.

How do I tune the speed of the AGV?

Adjust the --amp parameter. This sets the channel offset from centre (1024) that represents the motion command. The default is 660, giving roughly 64% of maximum speed. For slower, more controlled operation during arm-mounted manipulation tasks, use --amp 400. For maximum speed on an open floor, use up to --amp 900. Note that mecanum wheels lose some lateral efficiency at very high speeds — keep --amp below 800 for lateral manoeuvres.