UGV / Rover Control Interface (JSON Commands & Firmware Flow)

This page documents how the UGV (Ground Rover) receives movement commands and executes them.
Commands are received over UDP in JSON format, interpreted by the onboard microcontroller (ESP32),
and then forwarded to motor drivers controlling the wheels.

---

Communication Overview

Data Flow

Drone (VOXL) ── VIO / "Come to me" Commands ──▶ Laptop
Laptop ── JSON Motor Commands ──▶ UGV
UGV (ESP32) ── Motor PWM ──▶ Wheels

---

JSON Command Structure (UGV)

Field	Meaning	Range
T	Throttle / forward movement	-1.0 to 1.0
L	Left wheel command	-1.0 to 1.0
R	Right wheel command	-1.0 to 1.0

Example command

{"T": 0.4, "L": 0.3, "R": 0.5}

Behavior Rules

Value	Action
T = +1	Full forward
T = -1	Full reverse
L > R	Turns right
L < R	Turns left
0,0,0	Stop

---

Rover Firmware Logic (ESP32)

UDP Listener Pseudocode

listen_udp:
    receive JSON
    parse T, L, R
    convert to motor PWM
    write to motor driver

Error Handling

Issue	ESP32 Action
No packets for 1s	Stop motors (failsafe)
Corrupt JSON	Ignore message
Values > 1	Clamp to [-1,1]

---

Laptop → Rover Command Sender (Behavior Summary)

The PC script:

Task	Description
Position tracking	Reads drone VIO data
Control law	Computes T, L, R based on target offset
Reset logic	Handles drone origin resets smoothly
Network	Sends motor JSON to rover

---

Control Equation Recap

T = Kt * forward_error
Angular = Kr * lateral_error

Left = T - Angular
Right = T + Angular

Where:

Constant	Meaning
Kt	Forward acceleration gain
Kr	Turning gain
STOP_DIST	When rover is considered "under drone"

---

Safety / Failsafe Rules

Trigger	Rover Behavior
Drone reset	Continue to last known position, then reset to (0,0)
Bad VIO quality	Ignore drone movement (hold last good position)
User cancel / stop	Freeze motors immediately

---

Summary

This module ensures:

• Real‑time rover motion based on drone pose
• Smooth handling when VIO resets
• Safety and communication reliability
• Compatibility with Waveshare UGV JSON protocol

---