car_stm32f103vet6/docs/upper_computer_ai_guide.md

Logistics Car Upper Computer AI Guide

1. Purpose

This document is written for an AI agent that will implement the upper computer application. Goal: build a stable TCP client for the logistics car, with both auto mode and manual mecanum mode, based on the embedded protocol implemented in this repository.

Target users:

• AI coding agents (Copilot-like, AutoGen-like, etc.)
• Human developers who review AI-generated upper computer code

Out of scope:

• Modifying embedded firmware behavior
• Replacing transport protocol

---

2. Must-Follow Protocol Contract

2.1 Frame format

All commands and telemetry use ASCII text:

LOGI::#

Fields:

• LOGI: fixed header
• : command or telemetry body
• : 2-digit uppercase hex checksum
• #: fixed frame tail

2.2 Checksum algorithm

Checksum is the low 8 bits of ASCII sum of all bytes from L in LOGI to the byte before the final colon before CS.

Pseudo:

1. base = "LOGI:" + payload
2. cs = sum(base bytes as ASCII) & 0xFF
3. frame = base + ":" + toHex2Upper(cs) + "#"

Python reference:

def build_frame(payload: str) -> str:
    base = f"LOGI:{payload}"
    cs = sum(base.encode("ascii")) & 0xFF
    return f"{base}:{cs:02X}#"

C# reference:

static string BuildFrame(string payload)
{
    string baseStr = $"LOGI:{payload}";
    int sum = 0;
    foreach (byte b in System.Text.Encoding.ASCII.GetBytes(baseStr))
        sum = (sum + b) & 0xFF;
    return $"{baseStr}:{sum:X2}#";
}

Important:

• Must use uppercase hex (for consistency)
• Do not append CRLF unless your socket tool requires it
• One frame can be sent as raw ASCII bytes directly

---

3. Command Set (PC -> Car)

3.1 Common control

• SP:xxx set speed 000..100
• ST:RUN start auto run
• ST:STOP stop run
• GS:xxx set target station (current firmware supports 001, 002)

3.2 Mode switch (new)

• MD:MAN switch to manual mecanum mode
• MD:AUTO switch to auto tracking mode

3.3 Manual movement (new, only valid in MAN mode)

• MV:FWD forward
• MV:BWD backward
• MV:LEFT strafe left
• MV:RIGHT strafe right
• MV:LF forward-left diagonal
• MV:RF forward-right diagonal
• MV:LB backward-left diagonal
• MV:RB backward-right diagonal
• MV:CW rotate clockwise
• MV:CCW rotate counterclockwise
• MV:STOP stop motion

If current mode is AUTO and you send MV:*:

• car returns FB:MV:0 (rejected)
• upper computer must first send MD:MAN

---

4. Telemetry and Feedback (Car -> PC)

4.1 Periodic status (every ~500ms)

Payload format:

STAT:SP:xxx,STA:xxx,RUN:x,MODE:mode,MAN:dir,DIS:d,TRK:b4b3b2b1,DEV:n,OBS:x,RPM:m1:m2:m3:m4

Fields:

• SP: speed percent
• STA: target station
• RUN: 1 running, 0 stopped
• MODE: AUTO or MAN
• MAN: STOP/FWD/BWD/LEFT/RIGHT/LF/RF/LB/RB/CW/CCW
• DIS: ultrasonic distance in cm
• TRK: 4-channel line mask, order H4 H3 H2 H1
• DEV: track deviation (auto mode meaningful)
• OBS: obstacle lock (1 blocked, 0 clear)
• RPM: 4 motor RPM, order M1:M2:M3:M4 (LR:LF:RF:RR)

4.2 Command feedback (immediate)

Payload format:

FB::<0|1>

Examples:

• FB:SP:1 speed accepted
• FB:GS:0 station invalid or parse fail
• FB:MV:0 movement rejected (for example mode mismatch)

Upper computer rule:

• Every button operation should wait for feedback timeout window
• If no feedback in timeout, mark command uncertain and retry policy applies

---

5. Upper Computer Architecture Requirements

AI must implement the upper computer with these modules.

5.1 Network module

Responsibilities:

• Maintain TCP connection lifecycle
• Auto reconnect with backoff
• Byte stream receive and frame extraction

Required behavior:

• Reconnect delay: 1s, 2s, 3s, then fixed 3s
• On reconnect success, UI state set to Connected
• On disconnect, all movement buttons should be disabled

5.2 Protocol module

Responsibilities:

• Build frames from payload
• Parse incoming frames
• Verify checksum before dispatch

Required behavior:

• Drop frame if checksum invalid
• Log invalid frame raw text for diagnostics
• Expose strongly typed events: StatusEvent, FeedbackEvent

5.3 Command dispatcher

Responsibilities:

• Serialize outbound commands (single queue)
• Attach request id locally (not in protocol) for UI correlation
• Wait feedback with timeout

Recommended defaults:

• Feedback timeout: 800 ms
• Max retries for idempotent commands (SP, MD, MV:STOP): 2
• No auto-retry for ST:RUN and GS:xxx unless user confirms

5.4 UI module

Required controls:

• Connection: IP, port, connect/disconnect
• Mode: AUTO / MAN toggle
• Speed: slider 0..100 with send button
• Auto controls: station selector (001/002), RUN, STOP
• Manual controls: directional keypad + rotation + STOP
• Status panel: parsed telemetry fields
• Logs panel: TX/RX raw frames + parsed result

5.5 Safety guard module

Required safety logic:

• If UI in MAN mode and mouse/touch release on direction button, auto send MV:STOP
• If no fresh status for >2s, show stale warning
• Emergency stop hotkey sends MV:STOP first; if in AUTO also send ST:STOP

---

6. Exact Button-to-Command Mapping

All below are complete frames with checksum, directly sendable.

6.1 Mode

• Switch to manual: LOGI:MD:MAN:0C#
• Switch to auto: LOGI:MD:AUTO:69#

6.2 Speed presets

• 30%: LOGI:SP:030:D5#
• 50%: LOGI:SP:050:D7#
• 80%: LOGI:SP:080:DA#

6.3 Auto mode

• Station 001: LOGI:GS:001:CA#
• Station 002: LOGI:GS:002:CB#
• Auto run: LOGI:ST:RUN:3B#
• Auto stop: LOGI:ST:STOP:8C#

6.4 Manual movement

• Forward: LOGI:MV:FWD:23#
• Backward: LOGI:MV:BWD:1F#
• Left strafe: LOGI:MV:LEFT:6D#
• Right strafe: LOGI:MV:RIGHT:C0#
• Forward-left: LOGI:MV:LF:D4#
• Forward-right: LOGI:MV:RF:DA#
• Backward-left: LOGI:MV:LB:D0#
• Backward-right: LOGI:MV:RB:D6#
• Rotate CW: LOGI:MV:CW:DC#
• Rotate CCW: LOGI:MV:CCW:1F#
• Stop: LOGI:MV:STOP:88#

---

7. Recommended Operation Sequences

7.1 Manual driving flow

1. Connect TCP
2. Send SP:xxx
3. Send MD:MAN
4. Hold direction button -> send MV:* repeatedly or once per state change
5. Release button -> send MV:STOP

Recommended send style for manual:

• Edge-triggered (on press send once, on release send stop) is preferred
• If network jitter is high, add keepalive send of same MV every 300 ms

7.2 Auto transport flow

1. Connect TCP
2. Send SP:xxx
3. Send MD:AUTO
4. Send GS:001 or GS:002
5. Send ST:RUN
6. Observe RUN and feedback/status until arrival

Arrival behavior in firmware:

• Car auto-stops on target RFID
• RUN becomes 0
• Next run requires sending GS again, then ST:RUN

---

8. Frame Parsing Strategy (Stream-safe)

TCP is stream-based, not message-based. AI must implement frame extraction correctly.

Required parser behavior:

• Keep a receive buffer string/byte array
• Search for header "LOGI:"
• Search for tail '#'
• Extract candidate frame from first valid header to first following '#'
• Validate checksum
• Dispatch valid frame; remove consumed bytes
• If garbage before header, discard garbage

Do not assume one recv equals one frame.

---

9. Error Handling and Recovery

9.1 Feedback timeout

If command has no FB within timeout:

• Mark as timeout in UI
• For safe idempotent commands, retry once or twice
• For movement commands, prefer fail-safe by sending STOP

9.2 Checksum mismatch in received data

• Drop frame
• Log as warning with raw text
• Keep connection alive (do not disconnect directly)

9.3 Mode conflict

If receiving FB:MV:0 after sending MV command:

• UI should hint: "Not in manual mode, switching to MAN"
• Auto-send MD:MAN then retry once

9.4 Connection loss during motion

On disconnect event:

• UI enters safe state
• disable movement controls
• after reconnect, require operator to re-confirm mode and speed

---

10. AI Implementation Checklist (Definition of Done)

Functional:

• Can connect/disconnect TCP manually
• Can parse status and feedback reliably
• All buttons send correct command frames
• Manual control works in all listed directions
• Auto mode flow works (GS + RUN + STOP)

Robustness:

• Stream parser handles sticky packets and split packets
• Reconnect works automatically
• Command timeout/retry policy implemented
• Logs include TX/RX and parse errors

Usability:

• Telemetry fields visible and updating
• Mode and direction state clearly shown
• Emergency stop is always accessible

Testing:

• Unit test for checksum build/verify
• Unit test for parser with mixed/fragmented frames
• Integration test with mock TCP server replaying status/feedback

---

11. Suggested Prompt for Coding AI

Use this prompt when asking another coding AI to generate the upper computer:

"Implement a production-ready TCP upper computer client for an STM32 logistics car protocol. Use ASCII frame format LOGI::# with checksum as sum(base bytes) & 0xFF where base is LOGI:. Support commands SP, ST, GS, MD, MV. Parse status payload STAT with fields SP, STA, RUN, MODE, MAN, DIS, TRK, DEV, OBS, RPM. Parse feedback payload FB::<0|1>. Build a stream-safe parser for sticky/fragmented TCP packets. Include reconnect, timeout/retry, and a UI with manual mecanum directional controls and auto mode controls."

---

12. Notes for Future Extension

If firmware adds fields later:

• Keep parser tolerant: unknown key-value pairs should not crash parser
• Preserve raw payload in logs for forward compatibility
• Version your app-side parser module (for example v1_2)