#include "serial_link.h" #include #include #include "freertos/FreeRTOS.h" #include "freertos/task.h" #include "freertos/semphr.h" #include "driver/usb_serial_jtag.h" #include "esp_log.h" static const char *TAG = "serial_link"; #define SYNC0 0xAA #define SYNC1 0x55 static serial_link_cam_tx_cb_t s_on_cam_tx; // ---- Counters reported to the phone in every heartbeat (see SERIAL_MSG_STATUS in the header). // Saturating rather than wrapping: "65535 drops" reads as "lots and still going", whereas a wrap // back to a small number during a long bench run reads as "the problem went away". static uint16_t s_oversize_drops; static uint16_t s_tx_failures; static uint16_t s_rx_crc_errors; // Serializes send_frame(): it writes a frame as four separate usb_serial_jtag_write_bytes() calls // and shares one static CRC scratch buffer, and it's now called from three tasks (rx_forward for // CAM_RX, the heartbeat task for STATUS, and potentially others). Without this, two frames could // interleave on the wire and both would be discarded by the phone's framer. static SemaphoreHandle_t s_tx_mutex; static inline void bump(uint16_t *counter) { if (*counter < 0xFFFF) (*counter)++; } void serial_link_note_tx_failure(void) { bump(&s_tx_failures); } // ---- CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF, no reflect, no xorout) ---- // Bytewise (no table) - frames here are at most SERIAL_LINK_MAX_PAYLOAD + 3 bytes, so table // lookup isn't worth the flash/RAM tradeoff. MUST match the Kotlin-side implementation exactly // (see app SerialFrame.kt) or every frame will be silently rejected as corrupt. static uint16_t crc16_ccitt_false(const uint8_t *data, size_t len) { uint16_t crc = 0xFFFF; for (size_t i = 0; i < len; i++) { crc ^= (uint16_t)data[i] << 8; for (int b = 0; b < 8; b++) { crc = (crc & 0x8000) ? (uint16_t)((crc << 1) ^ 0x1021) : (uint16_t)(crc << 1); } } return crc; } static bool send_frame(uint8_t type, const uint8_t *payload, int len) { if (len < 0 || len > SERIAL_LINK_MAX_PAYLOAD) { ESP_LOGW(TAG, "send_frame: payload too large (%d)", len); return false; } // type(1) + length(2) + payload(len) is what the CRC covers. uint8_t head[3]; head[0] = type; head[1] = (uint8_t)(len & 0xFF); head[2] = (uint8_t)((len >> 8) & 0xFF); // Concatenate head+payload to CRC them in one pass. static, not stack: at // SERIAL_LINK_MAX_PAYLOAD = 512 this buffer is 515 bytes, which is a meaningful bite out of a // 4 KB task stack, and send_frame() is called from several tasks. Guarded by s_tx_mutex below // so the shared buffer (and the four-part write) can't interleave between callers. static uint8_t s_crc_buf[3 + SERIAL_LINK_MAX_PAYLOAD]; // No host on the other end: the TX buffer never drains, so every write below would block its // full timeout and this frame is going nowhere regardless. Bail before taking the mutex - // otherwise a burst of promiscuously-captured CAMs holds the lock for hundreds of ms each and // starves the heartbeat, which is exactly what "tx mutex timeout, dropping frame" was. if (!usb_serial_jtag_is_connected()) { return false; } // Timeout must exceed the worst-case hold below (4 writes x SERIAL_LINK_WRITE_TIMEOUT_MS), // or a legitimately slow-but-working host makes contending senders drop frames instead of // waiting their turn. if (s_tx_mutex && xSemaphoreTake(s_tx_mutex, pdMS_TO_TICKS(SERIAL_LINK_TX_LOCK_TIMEOUT_MS)) != pdTRUE) { ESP_LOGW(TAG, "send_frame: tx mutex timeout, dropping frame"); return false; } memcpy(s_crc_buf, head, 3); if (len > 0) memcpy(s_crc_buf + 3, payload, (size_t)len); uint16_t crc = crc16_ccitt_false(s_crc_buf, (size_t)(3 + len)); uint8_t sync[2] = {SYNC0, SYNC1}; uint8_t crc_bytes[2] = {(uint8_t)(crc & 0xFF), (uint8_t)((crc >> 8) & 0xFF)}; // Four separate writes rather than one assembled buffer - simplest given payload is // already wherever the caller has it (avoids a second copy of up to 160 bytes). // usb_serial_jtag_write_bytes() blocks up to the given tick timeout if the host isn't // reading fast enough; generous for a single frame at USB full-speed, and keeps a wedged // host from hanging the radio TX/RX tasks indefinitely. const TickType_t write_timeout = pdMS_TO_TICKS(SERIAL_LINK_WRITE_TIMEOUT_MS); int wrote = 0; wrote += usb_serial_jtag_write_bytes(sync, sizeof(sync), write_timeout); wrote += usb_serial_jtag_write_bytes(head, sizeof(head), write_timeout); if (len > 0) wrote += usb_serial_jtag_write_bytes(payload, (size_t)len, write_timeout); wrote += usb_serial_jtag_write_bytes(crc_bytes, sizeof(crc_bytes), write_timeout); if (s_tx_mutex) xSemaphoreGive(s_tx_mutex); return wrote == (int)(sizeof(sync) + sizeof(head) + len + sizeof(crc_bytes)); } 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) { if (uper_len < 0 || uper_len > SERIAL_LINK_MAX_PAYLOAD - SERIAL_V2X_RX_PREFIX_LEN) { // Counted, not just logged: this log line goes to the flashing port, which nobody is // watching during a phone bench session - so the symptom would be "that station just // never shows up in the app" with no visible cause. bump(&s_oversize_drops); ESP_LOGW(TAG, "send_v2x_rx: port %u payload too large (%d), total oversize drops %u", btp_dest_port, uper_len, s_oversize_drops); return false; } // static, not stack (526 bytes at MAX_PAYLOAD 512); only rx_forward_task calls this, and // send_frame's mutex covers the handoff onto the wire. static uint8_t s_v2x_payload[SERIAL_LINK_MAX_PAYLOAD]; // Little-endian prefix, layout documented in serial_link.h - keep in lockstep with the app's // SerialFrame.kt. s_v2x_payload[0] = (uint8_t)(btp_dest_port & 0xFF); s_v2x_payload[1] = (uint8_t)((btp_dest_port >> 8) & 0xFF); s_v2x_payload[2] = (uint8_t)rssi; s_v2x_payload[3] = has_geo_area ? 0x01 : 0x00; uint32_t lat = (uint32_t)geo_area_lat_tenmicrodeg; uint32_t lon = (uint32_t)geo_area_lon_tenmicrodeg; s_v2x_payload[4] = (uint8_t)(lat & 0xFF); s_v2x_payload[5] = (uint8_t)((lat >> 8) & 0xFF); s_v2x_payload[6] = (uint8_t)((lat >> 16) & 0xFF); s_v2x_payload[7] = (uint8_t)((lat >> 24) & 0xFF); s_v2x_payload[8] = (uint8_t)(lon & 0xFF); s_v2x_payload[9] = (uint8_t)((lon >> 8) & 0xFF); s_v2x_payload[10] = (uint8_t)((lon >> 16) & 0xFF); s_v2x_payload[11] = (uint8_t)((lon >> 24) & 0xFF); s_v2x_payload[12] = (uint8_t)(geo_area_distance_a_m & 0xFF); s_v2x_payload[13] = (uint8_t)((geo_area_distance_a_m >> 8) & 0xFF); if (uper_len > 0) memcpy(s_v2x_payload + SERIAL_V2X_RX_PREFIX_LEN, uper, (size_t)uper_len); return send_frame(SERIAL_MSG_V2X_RX, s_v2x_payload, SERIAL_V2X_RX_PREFIX_LEN + uper_len); } bool serial_link_send_status(uint8_t status) { // [status:1][oversize_drops:2 LE][tx_failures:2 LE][rx_crc_errors:2 LE] - keep in lockstep // with EspLinkStatus.parse() in the app's SerialFrame.kt. uint8_t payload[7]; payload[0] = status; payload[1] = (uint8_t)(s_oversize_drops & 0xFF); payload[2] = (uint8_t)((s_oversize_drops >> 8) & 0xFF); payload[3] = (uint8_t)(s_tx_failures & 0xFF); payload[4] = (uint8_t)((s_tx_failures >> 8) & 0xFF); payload[5] = (uint8_t)(s_rx_crc_errors & 0xFF); payload[6] = (uint8_t)((s_rx_crc_errors >> 8) & 0xFF); return send_frame(SERIAL_MSG_STATUS, payload, sizeof(payload)); } // 1 Hz heartbeat. This is what lets the phone tell "link alive, radio quiet" from "link dead" - // the app's watchdog (UsbSerialTransport.kt) marks the link ERROR after 3 missed beats. Keep the // period in step with LINK_TIMEOUT_MS over there. static void status_task(void *arg) { (void)arg; while (1) { serial_link_send_status(0); vTaskDelay(pdMS_TO_TICKS(1000)); } } // ---- RX framing state machine ---- // Runs in its own task, byte-at-a-time off the USB Serial/JTAG driver's RX ring buffer (via // usb_serial_jtag_read_bytes with a short timeout, not raw ISR access - simplest correct option // for a link this slow/small; revisit if CAM traffic volume ever makes this a bottleneck). typedef enum { WAIT_SYNC0, WAIT_SYNC1, WAIT_TYPE, WAIT_LEN_LO, WAIT_LEN_HI, WAIT_PAYLOAD, WAIT_CRC_LO, WAIT_CRC_HI, } rx_state_t; static void rx_task(void *arg) { (void)arg; rx_state_t state = WAIT_SYNC0; uint8_t type = 0; uint16_t len = 0; uint16_t payload_idx = 0; uint16_t crc_recv = 0; // static, not stack: at SERIAL_LINK_MAX_PAYLOAD = 512 these two are >1 KB together, a quarter // of this task's 4 KB stack. Safe as statics because rx_task is a singleton - one instance, // created once in serial_link_init(). static uint8_t payload[SERIAL_LINK_MAX_PAYLOAD]; static uint8_t crc_buf[3 + SERIAL_LINK_MAX_PAYLOAD]; uint8_t byte; while (1) { int n = usb_serial_jtag_read_bytes(&byte, 1, pdMS_TO_TICKS(50)); if (n <= 0) continue; switch (state) { case WAIT_SYNC0: state = (byte == SYNC0) ? WAIT_SYNC1 : WAIT_SYNC0; break; case WAIT_SYNC1: state = (byte == SYNC1) ? WAIT_TYPE : (byte == SYNC0 ? WAIT_SYNC1 : WAIT_SYNC0); break; case WAIT_TYPE: type = byte; state = WAIT_LEN_LO; break; case WAIT_LEN_LO: len = byte; state = WAIT_LEN_HI; break; case WAIT_LEN_HI: len |= (uint16_t)byte << 8; if (len > SERIAL_LINK_MAX_PAYLOAD) { ESP_LOGW(TAG, "rx: length %u exceeds max, resyncing", len); state = WAIT_SYNC0; // can't trust this frame boundary at all - drop to resync } else if (len == 0) { payload_idx = 0; state = WAIT_CRC_LO; } else { payload_idx = 0; state = WAIT_PAYLOAD; } break; case WAIT_PAYLOAD: payload[payload_idx++] = byte; if (payload_idx >= len) state = WAIT_CRC_LO; break; case WAIT_CRC_LO: crc_recv = byte; state = WAIT_CRC_HI; break; case WAIT_CRC_HI: { crc_recv |= (uint16_t)byte << 8; crc_buf[0] = type; crc_buf[1] = (uint8_t)(len & 0xFF); crc_buf[2] = (uint8_t)((len >> 8) & 0xFF); if (len > 0) memcpy(crc_buf + 3, payload, len); uint16_t crc_calc = crc16_ccitt_false(crc_buf, (size_t)(3 + len)); if (crc_calc == crc_recv) { if (type == SERIAL_MSG_CAM_TX && s_on_cam_tx) { s_on_cam_tx(payload, len); } else if (type != SERIAL_MSG_CAM_TX) { ESP_LOGW(TAG, "rx: unexpected frame type 0x%02x from phone, ignoring", type); } } else { bump(&s_rx_crc_errors); ESP_LOGW(TAG, "rx: CRC mismatch (got %04x want %04x), dropping frame (total %u)", crc_recv, crc_calc, s_rx_crc_errors); } state = WAIT_SYNC0; break; } } } } void serial_link_init(serial_link_cam_tx_cb_t on_cam_tx) { s_on_cam_tx = on_cam_tx; s_tx_mutex = xSemaphoreCreateMutex(); if (!s_tx_mutex) { // Fail loudly rather than silently running unserialized: interleaved frames would look // like random CRC errors on the phone, which is a miserable thing to debug. ESP_LOGE(TAG, "failed to create tx mutex"); abort(); } usb_serial_jtag_driver_config_t cfg = { .tx_buffer_size = SERIAL_LINK_USB_BUF_SIZE, .rx_buffer_size = SERIAL_LINK_USB_BUF_SIZE, }; ESP_ERROR_CHECK(usb_serial_jtag_driver_install(&cfg)); xTaskCreate(rx_task, "serial_link_rx", 4096, NULL, 6, NULL); xTaskCreate(status_task, "serial_link_status", 2560, NULL, 4, NULL); ESP_LOGI(TAG, "serial_link up on native USB Serial/JTAG (VID 0x303A / PID 0x1001), " "max payload %d, 1 Hz heartbeat", SERIAL_LINK_MAX_PAYLOAD); }