MicrOBU/obu-firmware/main/serial_link.h

#ifndef SERIAL_LINK_H
#define SERIAL_LINK_H
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

// Binary framing for the phone <-> ESP32-C5 link (Phase 03). This runs over the ESP32-C5's
// native USB Serial/JTAG peripheral (driver/usb_serial_jtag.h) - the same physical USB-C port
// used for JTAG, exposed to the host as a fixed-VID/PID (0x303A/0x1001) USB CDC-ACM device.
// Deliberately NOT the same wire as the ESP-IDF console/ESP_LOG output, which stays on the
// OTHER USB-C port (the UART-bridge one, UART0, see sdkconfig CONFIG_ESP_CONSOLE_UART_NUM=0) -
// mixing binary frames with human-readable log text on one wire would corrupt both, and this
// way they're physically separate ports so there's no risk of that regardless.
//
// On the Android side, connect the phone (via USB-OTG) to the board's NATIVE USB-C port, not
// the UART-bridge/flashing port. The usb-serial-for-android library's default prober doesn't
// know Espressif's 0x303A/0x1001 VID/PID, so UsbSerialTransport.kt registers it manually via a
// custom ProbeTable pointed at CdcAcmSerialDriver - see that file's KDoc.
//
// Frame format (both directions, symmetric):
//   [0xAA][0x55][type:1][length:2 LE][payload: length bytes][crc16:2 LE]
// CRC16 is CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF, no reflect, no xorout), computed over
// type + length + payload only (not the two sync bytes). Same algorithm must be used on the
// Kotlin side (see app SerialFrame.kt) - frames that don't checksum are silently dropped.
//
// Direction / types:
//   SERIAL_MSG_CAM_TX (0x01), phone -> ESP32: payload is a raw CAM UPER byte string, already
//     built by the phone (position/speed/heading/yaw rate baked in). On receipt the ESP32
//     immediately GeoNetworking-wraps and transmits it - this IS the transmit clock now, there
//     is no independent on-chip timer. See main.c's rx-driven tx path.
//   SERIAL_MSG_CAM_RX (0x02), ESP32 -> phone: SUPERSEDED by SERIAL_MSG_V2X_RX, no longer sent.
//     The constant is kept so the numbering is not silently reused by a future message type.
//   SERIAL_MSG_V2X_RX (0x04), ESP32 -> phone: any ITS message received over the air, already
//     stripped of its 802.11/LLC-SNAP/GeoNetworking/BTP-B framing by gn_unwrap.c - the phone
//     never sees raw 802.11 frames. Payload is a fixed 14-byte prefix followed by the UPER bytes:
//
//       [0..1]   btp_dest_port  uint16 LE   2001 = CAM, 2002 = DENM (ETSI TS 103 248)
//       [2]      rssi           int8        dBm, from the promiscuous RX metadata
//       [3]      flags          uint8       bit0: geo area fields below are valid
//       [4..7]   geo_area_lat   int32 LE    1/10 microdegree, GeoBroadcast destination area
//       [8..11]  geo_area_lon   int32 LE    1/10 microdegree
//       [12..13] geo_area_dist  uint16 LE   Distance A, metres (relevance radius for a circle)
//       [14..]   UPER message bytes
//
//     All prefix fields are LITTLE-endian, matching this framing's own length field - note the
//     GeoNetworking wire format they came from is big-endian, so gn_unwrap.c converts.
//     Generic on purpose: adding MAPEM/SPATEM later needs a decoder on the phone and one port in
//     gn_unwrap.c, but no change to this protocol. No station id is carried separately - each
//     message's own ItsPduHeader.stationID is the meaningful identifier.
//   SERIAL_MSG_STATUS (0x03), ESP32 -> phone: heartbeat + counters, sent at 1 Hz so the phone can
//     distinguish "link idle" from "link dead" independent of CAM traffic (the app's watchdog in
//     UsbSerialTransport.kt declares the link dead after 3 missed beats). Payload is 7 bytes:
//       [status:1][oversize_drops:2 LE][tx_failures:2 LE][rx_crc_errors:2 LE]
//     status 0 = ok. The counters are free-running totals since boot, saturating at 0xFFFF.
//     They exist because the alternative - ESP_LOGW on the flashing port - is invisible to the
//     phone, which is the only thing watching during a bench session. Mirrored by EspLinkStatus
//     in the app's SerialFrame.kt.
#define SERIAL_MSG_CAM_TX   0x01
#define SERIAL_MSG_CAM_RX   0x02
#define SERIAL_MSG_STATUS   0x03
#define SERIAL_MSG_V2X_RX   0x04

// Size of the V2X_RX prefix documented above. Must match the app's SerialFrame.kt.
#define SERIAL_V2X_RX_PREFIX_LEN  14

// USB Serial/JTAG has no baud rate or GPIO pins to configure - it's a fixed on-chip USB device
// controller wired directly to the native USB-C port's D+/D- lines in silicon. RX/TX buffer
// sizes for usb_serial_jtag_driver_install() (see serial_link.c) are sized generously relative
// to SERIAL_LINK_MAX_PAYLOAD below.
#define SERIAL_LINK_USB_BUF_SIZE  1024

// Per-write block ceiling, and the mutex acquire timeout that must comfortably exceed the
// worst case of one frame (4 writes: sync, head, payload, crc). Keep that relationship if you
// change either number - a lock timeout below the max hold turns normal contention into
// dropped frames, which is how the heartbeat was being starved by forwarded CAM_RX traffic.
#define SERIAL_LINK_WRITE_TIMEOUT_MS   100
#define SERIAL_LINK_TX_LOCK_TIMEOUT_MS 600

// Max CAM payload this link will carry. MUST match SERIAL_LINK_MAX_PAYLOAD in the app's
// SerialFrame.kt - a mismatch means every frame above the smaller of the two is rejected by that
// side's "length exceeds max, resync" branch, silently.
//
// Raised from 160 to 512: 160 was reasoned from cam.c's 96-byte encode buffer, which only ever
// described OUR OWN minimal CAM. A third-party CAM off the air carrying a path-history or
// special-vehicle container comfortably exceeds it, and those stations would then never reach the
// phone at all. 512 clears any realistic CAM; the real upstream ceiling on the RX path is
// rx_item_t.data (400 bytes) in main.c, so nothing larger can get here anyway.
#define SERIAL_LINK_MAX_PAYLOAD  512

// Initializes the USB Serial/JTAG driver and its background RX-framing and 1 Hz heartbeat tasks.
// Call once from app_main, after nvs/event loop init. `on_cam_tx` is invoked (from the RX task's
// context - keep it fast, it blocks the next frame's parsing) whenever a complete, checksummed
// SERIAL_MSG_CAM_TX frame arrives from the phone.
typedef void (*serial_link_cam_tx_cb_t)(const uint8_t *cam_uper, int cam_len);
void serial_link_init(serial_link_cam_tx_cb_t on_cam_tx);

// Sends a SERIAL_MSG_V2X_RX frame: the metadata prefix plus the UPER bytes gn_unwrap.c extracted
// from an over-the-air frame. Pass has_geo_area=false and zeroes for the area fields when the
// source frame carried no destination area (i.e. it was single-hop broadcast, not GeoBroadcast).
// Returns true if the frame was written to the USB endpoint - not an end-to-end ack, the phone
// may still drop it.
bool serial_link_send_v2x_rx(uint16_t btp_dest_port, int8_t rssi,
                              bool has_geo_area,
                              int32_t geo_area_lat_tenmicrodeg,
                              int32_t geo_area_lon_tenmicrodeg,
                              uint16_t geo_area_distance_a_m,
                              const uint8_t *uper, int uper_len);

// Sends one SERIAL_MSG_STATUS heartbeat frame immediately (status byte + the current counters).
// Normally unnecessary to call by hand - serial_link_init() starts a task that does this at 1 Hz.
bool serial_link_send_status(uint8_t status);

// Records a failed esp_wifi_80211_tx() so it shows up in the next heartbeat's tx_failures
// counter. Called from main.c's tx_radio_task - a CAM that reached the radio but didn't go out is
// otherwise indistinguishable, from the phone's side, from one that transmitted fine.
void serial_link_note_tx_failure(void);

#endif