From navigation intent to motor registers.

Audit date: 21 September 2026. This document separates the supplied source code from the proposed navigation interface. Source-level review and generated frame checks are not physical robot validation.

The integration decision

Use the Jetson as the high-level navigation computer and retain the ESP32 as the single owner of the motor RS485 bus. LiDAR and optional IMU data enter the Jetson; localization, planning and obstacle handling produce a bounded velocity request. A Jetson bridge converts the request to four logical wheel velocities and sends it to the ESP32. The ESP32 validates commands and freshness, performs local stopping/interlocks, applies wheel polarity, and writes both motor drivers.

The supplied files do not contain the matching external-command ESP32 firmware. The student team can design, simulate and validate the message contract now; physical operation requires the actual bridge firmware from Adaptive AgroTech or a separately reviewed implementation. The browser workbench simulates movement and obstacle-triggered route replanning while generating and displaying messages. It does not connect to the robot or publish a command endpoint.

Do not connect two Modbus masters to the existing RS485 bus. Direct Jetson-to-driver Modbus is an alternative architecture only if the ESP32 relinquishes bus ownership and its local command checking and stop responsibilities are replaced explicitly. The ESP32 in the supplied demo is a Modbus master, not a documented Modbus slave; the Jetson cannot send the driver register frames to the ESP32 USB port and expect forwarding.

What each supplied source actually provides

Source anchors: demo lines 35–50, 137–307, 581–632 and 635–709; serial-test sketch lines 1–32; Lua lines 256–269, 537–709 and 1045–1070. Line numbers identify the company-provided source snapshots reviewed when this guide was prepared. Raw firmware and source archives are outside this student edition; obtain the approved hardware files from the company during integration.

Two different wire interfaces

1. Jetson → ESP32, proposed bridge contract: USB serial, newline-delimited ASCII, 115200 baud, logical wheel angular velocities in rad/s. This reproduces the host-side format in the Lua example. A compatible ESP32 receiver is missing.
2. ESP32 → motor drivers, present in demo: binary Modbus RTU over RS485, 115200 baud, 8 data bits, no parity, 1 stop bit. Driver addresses 1 and 2. UART1 RX GPIO 18, TX GPIO 17.

USB serial and RS485 are not interchangeable electrically or syntactically. The UART GPIOs require the robot's proper RS485 transceiver/interface, not a direct connection to A/B. No DE/RE direction pin is controlled in the sketch; establish whether the installed board handles direction automatically. Cable, shielding, bus bias, termination, common reference/isolation and driver hardware version must be documented from the physical robot and appropriate manufacturer documentation. Do not guess power wiring from the code.

Commands accepted by the standalone demo

Use USB Serial at 115200 baud and end each line with LF (\n, one newline byte). CRLF and lowercase work because this parser trims input and converts it to uppercase; blank lines are ignored. These commands apply to the Sep 10 RobotDemo profile, not to the browser or the missing streaming receiver.

During the eight-second startup countdown, only PAUSE, STOP and ESTOP are handled; other input is consumed and ignored. FW, BW, LEFT, RIGHT, SPEED and TIME are not commands in this sketch.

What to verify: record the flashed firmware build and its power-on/reset behaviour before opening a terminal. Confirm the selected control profile and stop procedure with the company; a filename, a heartbeat or a successful USB connection does not identify a working wheel-command receiver.

Logical coordinates and kinematics

Use +X forward, +Y left, +Z up and positive yaw counterclockwise when viewed from above (left turn). Positive logical wheel speed means robot-forward, independent of motor mounting polarity. Lua names BL/BR mean the same rear wheels as RL/RR.

Steering sign is not yaw sign: the Lua joystick uses positive steering for a right turn; the navigation yaw rate w below is positive for a left turn. Convert the convention at the interface instead of copying a joystick axis directly into a yaw-rate request.

Let v be body forward velocity in m/s, w body yaw rate in rad/s, b measured effective track width in m, and r measured loaded wheel radius in m:

left_m_s  = v - w*b/2
right_m_s = v + w*b/2
FL = RL = left_m_s/r       # logical wheel rad/s
FR = RR = right_m_s/r
rpm = wheel_rad_s * 60/(2*pi)

Units at each boundary: navigation produces v in m/s and w in rad/s; the ASCII CMD fields are wheel rad/s; the driver registers hold signed integer RPM. A value of 90 in a CMD field would mean 90 rad/s, not 90 RPM.

The Lua geometry (r = 0.0535 m, b = 0.250 m) is a simulation profile. Its body and mass differ from the brochure. Measure the delivered robot before physical use; do not silently treat either source as the final hardware dimensions. Four-wheel skid steering slips on turns, so this ideal differential-drive model needs effective-track calibration and feedback. A 3 s timed pivot is not proof of a 360° rotation.

The Lua caps each physical command to ±150 RPM (±15.707963 rad/s). The demo drives at 90 RPM and turns at 90 RPM. A demo comment mentions 250 RPM as a provisional upper range, and the Lua simulation has 450/550 RPM motor limits; those are not validated navigation operating limits. Begin supervised commissioning at a separately agreed low speed. Preserve curvature by uniformly scaling all wheel requests when applying a common wheel-speed cap. The current Lua clamps each wheel independently; describe this difference if using uniform scaling in the new browser example.

The proposed bridge should define its conversion explicitly: validate finite numbers, cap in rad/s, convert to RPM, round to nearest integer with a defined tie rule, then apply the hardware polarity exactly once. The demo's sendRobotWheelSpeeds accepts integer RPM, so it does not define a float-to-RPM rounding rule. This browser uses JavaScript Math.round after formatting wheel rad/s to three decimals; exact half-integer RPM ties round toward positive infinity. A future receiver must deliberately adopt a documented matching policy. For example, 9.425 rad/s rounds to 90 RPM.

Hardware channel mapping recorded in the demo

Packet wheel order is always FL, FR, RL, RR. Driver channel names LEFT/RIGHT are labels on a dual-channel driver; they do not always match the robot side.

Therefore driver 1 receives (FL, -FR) and driver 2 receives (-RR, RL), all in signed RPM. 0x2089 is the second consecutive register in the source's two-register write. Confirm wheel identity and polarity with the robot supported and one wheel commanded at a time before navigation commissioning.

Lua-compatible serial message preview

Each line ends with LF (\n); CRLF is tolerated by the Lua receive parser because it strips CR. The Lua emits three decimals.

ESP32 → Jetson: ESP32_READY\n             expected receiver behavior; not supplied
Jetson → ESP32: HELLO\n
ESP32 → Jetson: ACK,HELLO\n               expected receiver behavior; not supplied
Jetson → ESP32: CMD,9.425,9.425,9.425,9.425\n
ESP32 → Jetson: ACK,CMD,...\n             exact suffix/schema not specified by Lua

For pivot left at 90 RPM: CMD,-9.425,9.425,-9.425,9.425\n. For stop: CMD,0.000,0.000,0.000,0.000\n. Lua cleanup and ACK-timeout logic also send STOP\n; the demo supports STOP, but that does not make it compatible with streaming CMD requests.

The Lua accepts ESP32_READY or ARDUINO_READY. It sends HELLO on READY and also starts probing after 0.5 s even when no READY was received, retrying at 1 s intervals. Thus the header comment saying it always waits for READY is not the full implemented behavior. After ACK,HELLO, it attempts to stream wheel commands every 0.05 s of simulation time. Commands are limited to ±150 RPM. Reconnection is attempted every 2 s of simulation time; an ACK gap greater than 2 s causes a zero/STOP attempt and closes the serial link. All ACK, lines refresh this timeout; it is not proof of the latest command being applied. The comment says ACK summaries arrive every ten commands, but that firmware behavior is unavailable here. A physical controller needs its own monotonic hardware-clock watchdog because simulation time can pause or run at a different rate from wall time. The Lua reconnects automatically while retaining operator demand; a compatible receiver could receive that demand after a new handshake. Define a stopped reconnect state and deliberate re-enable in the new bridge.

Binary Modbus RTU write

The demo writes both channels of one driver using function 0x10 (write multiple holding registers). Register addresses below are the literal PDU addresses used by the code; do not add an undocumented 40001 offset.

Negative RPM uses 16-bit two's complement: +90 → 00 5A; −90 → FF A6. CRC starts at 0xFFFF, uses the reflected polynomial 0xA001, and covers all preceding request bytes. Register/data values are high-byte first; CRC bytes are low-byte first.

Known vectors below were calculated independently in Python and checked by obtaining a zero CRC residual on each full frame. These are expected request/response bytes, not captured hardware traffic.

Expected successful function-0x10 responses:

Driver 1: 01 10 20 88 00 02 CA 22
Driver 2: 02 10 20 88 00 02 CA 11

The response acknowledges the register start and quantity, not the four data bytes. It confirms protocol acceptance, not wheel rotation, actual RPM or safe vehicle stopping. The sketch validates response length, CRC, driver ID, function, register start and quantity. Failed CRC, timeout, wrong fields or Modbus exception frames are treated as failure; exception codes are not decoded into specific diagnoses.

Initialization present in the demo

For each driver (1 then 2), the source performs these steps:

There is an 80 ms delay after each successful setting write. A function-06 reply must exactly echo its eight-byte request. Once both drivers configure successfully, zero RPM is written to both. The firmware then counts down eight seconds and automatically starts its repeating demonstration. There is no separate physical power-on versus USB-reset behavior in this sketch. Never use this autostart program as the students' assumed autonomous-command receiver.

A revised bridge should initialize to a disabled/stopped state, clear stale targets before enabling, require explicit enable, and roll back both drivers on partial initialization failure. The supplied initialization enables each driver before the final common zero command; a failure configuring the second driver does not explicitly disable the first. These are source-review findings, not evidence that the physical unit has unexpectedly moved.

Timing and stop limits

Two 250 ms timeouts already consume about 500 ms for a paired send, so three failures do not imply a 300 ms physical-stop guarantee. The next zero write can also fail on the same broken bus. Serial line reads and other blocking calls can delay servicing; independent local stop design and measured end-to-end timing are required. Software ESTOP is not a safety-rated power-removal circuit. The code has no shown motor-power contactor/STO circuit and does not establish compliance.

The demo’s communication-failure path pauses and attempts zero targets, but does not disable the drivers or clear driversReady; RESUME can therefore still be accepted. The Lua reversal dwell uses commanded side speeds and the average longitudinal sign, not measured standstill or an interlock on every individual wheel reversal. Verify these cases in the replacement bridge.

Future web JSON interface: design boundary

The current deliverable may export a JSON preview/log but must not label it an operational robot-control endpoint. The attached ESP32 firmware has no network client or JSON parser. For a later implementation, let the onboard Jetson retain navigation and obstacle-stop authority; treat web requests as bounded operator intent or mission goals. If an ESP32 must fetch a network command, its local command-expiry watchdog must still govern motion when the web service, Wi-Fi or DNS fails.

A future schema should explicitly include version, robot/session ID, monotonically increasing sequence number, command kind, units, requested wheel values or body twist, creation/expiry metadata, maximum validity window, source/authority and simulation/live intent. Use authenticated transport and explicit enable; the last saved JSON value must never become a persistent velocity command. Reject duplicate/out-of-order commands. Distinguish wall-clock expiry (requires trustworthy clock behavior) from local receive freshness. No endpoint, authentication or network-polling implementation is included in this source audit.

The downloadable fieldscout.simulation.command.v1 specimen is marked simulation_only: true and must be rejected by a future live receiver. An old cached JSON value must not become a fresh movement command when fetched again. Define caching, clock skew, partitions and receive-time expiry before adding an endpoint.

Download the simulation specimen schema

Parameters still needing company confirmation

Delivered robot identity and geometry; exact motor/driver variants and supply voltage; wiring/schematics and protective devices; actual bridge firmware; encoder register map and scale; measured braking behavior; available LiDAR/Jetson variants; payload and terrain limits; communication-loss behavior inside each motor driver; authorized commissioning speed; physical E-stop architecture. The brochure, Lua scene and new project scope describe different levels of maturity and cannot replace these measurements.