Send large BLE host frames across multiple notifies.

Prefer ATT MTU 517 and chunk oversized responses so CLIENT_INFO/BATTERY work with many pods; reset the goTool parser after timeouts so partial frames do not poison the next exchange.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/ARCHITECTURE.md

@@ -109,7 +109,7 @@ sequenceDiagram
 └─────────────────────────────────────────────────────────────┘
 ```
 
-**Host UART vs BLE:** Nur einer aktiv (DIP8). Gleiches Framing (`0xAA`…`0xCC`) und dieselbe `cmd_queue`. BLE: NUS-ähnliche GATT-Char, Write=RX, Notify=TX. `gotool serve` verbindet UART oder BLE über Dashboard/REST/WS (`managedHost`); **OTA** über UART oder BLE (ATT MTU ≥ ~219). Bei BLE-Host und aktivem Accel-Stream pusht `ble_stream` periodisch `BLE_STREAM_TICK` (10–16 ms, Default 10; pausiert während OTA) mit `esp_timestamp_us` (Live-Pfad bevorzugt Tick statt CACHE_STATUS-Poll).
+**Host UART vs BLE:** Nur einer aktiv (DIP8). Gleiches Framing (`0xAA`…`0xCC`) und dieselbe `cmd_queue`. BLE: NUS-ähnliche GATT-Char, Write=RX, Notify=TX; Frames größer als ATT MTU-3 werden in aufeinanderfolgende Notifies gestückelt (Host-Parser reassembliert). `gotool serve` verbindet UART oder BLE über Dashboard/REST/WS (`managedHost`); **OTA** über UART oder BLE (ATT MTU ≥ ~219, preferred 517). Bei BLE-Host und aktivem Accel-Stream pusht `ble_stream` periodisch `BLE_STREAM_TICK` (10–16 ms, Default 10; pausiert während OTA) mit `esp_timestamp_us` (Live-Pfad bevorzugt Tick statt CACHE_STATUS-Poll).
 
 
 ---
@@ -225,12 +225,12 @@ Unabhängig von Protobuf — reines Bytestream-Framing:
 | Feld | Wert |
 |------|------|
 | Start | `0xAA` |
-| Länge | 1 Byte (1–252) |
+| Länge | 2 Bytes little-endian (1–1024) |
 | Payload | `length` Bytes |
 | Prüfsumme | XOR aller Payload-Bytes |
 | Stopp | `0xCC` |
 
-**Parameter:** `main/uart.h` — `UART_NUM_1`, `921600` Baud, TX GPIO **2**, RX GPIO **3**, `MAX_PAYLOAD_SIZE` 248.
+**Parameter:** `main/uart.h` — `UART_NUM_1`, `921600` Baud, TX GPIO **2**, RX GPIO **3**, `MAX_PAYLOAD_SIZE` 1024.
 
 ### 5.2 Nutzlast (Anwendung)
 

docs/DOCUMENTATION.md

@@ -124,10 +124,10 @@ idf.py -p /dev/ttyUSB0 flash monitor
 | Byte | Inhalt |
 |------|--------|
 | 0 | `0xAA` Start |
-| 1 | Länge N (1–252) |
-| 2…N+1 | Payload |
-| N+2 | XOR-Checksum über Payload |
-| N+3 | `0xCC` Stopp |
+| 1–2 | Länge N little-endian (1–1024) |
+| 3…N+2 | Payload |
+| N+3 | XOR-Checksum über Payload |
+| N+4 | `0xCC` Stopp |
 
 Implementierung: `uart.c` — `parse_uart_byte()`, `uart_send_framed()`.
 
@@ -370,7 +370,7 @@ Implementierung: `ota_uart.c`, Steuerung `cmd/cmd_ota.c`. Gleiches Protokoll üb
 
 - Inaktive Partition: `esp_ota_get_next_update_partition()`.
 - LED-Ring zeigt Fortschritt (blau Schreiben, grün Verteilung).
-- BLE: ATT MTU ≥ ~219 (preferred 247); `BLE_STREAM_TICK` pausiert während `ota_session_busy()`.
+- BLE: ATT MTU ≥ ~219 (preferred 517); große Antworten werden über mehrere Notifies gestückelt; `BLE_STREAM_TICK` pausiert während `ota_session_busy()`.
 - **App-Rollback** (`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE`): neues Image bootet als `PENDING_VERIFY`. `ota_confirm` markiert nach ~8 s stabilem Lauf `mark_app_valid`; Crash/Reset davor → Bootloader rollt auf die vorherige App zurück. Während `PENDING_VERIFY` ist ein neues `OTA_START` blockiert.
 
 ### 8.2 ESP-NOW-OTA (Master → Slaves)

docs/adding-a-feature.md

@@ -287,7 +287,7 @@ Entspricht `main/README.md`:
 
 | Byte | Inhalt |
 |------|--------|
-| Frame | `0xAA`, Länge, Payload, XOR-Checksum, `0xCC` |
+| Frame | `0xAA`, Länge (uint16 LE), Payload, XOR-Checksum, `0xCC` |
 | Payload[0] | `MessageType` (z.B. `22` = FIND_ME) |
 | Payload[1…] | Nanopb-`UartMessage` |
 

goTool/ble_link.go

@@ -22,6 +22,7 @@ type bleLink struct {
 	device   bluetooth.Device
 	char     bluetooth.DeviceCharacteristic
 	mu       sync.Mutex
+	parserMu sync.Mutex
 	parser   *uartframe.Parser
 	respCh   chan []byte
 	streamCh chan []byte
@@ -162,6 +163,8 @@ func connectBLEDevice(addr bluetooth.Address, settle time.Duration) (*bleLink, e
 }
 
 func (b *bleLink) onNotify(buf []byte) {
+	b.parserMu.Lock()
+	defer b.parserMu.Unlock()
 	for _, by := range buf {
 		payload, ok, err := b.parser.Feed(by)
 		if err != nil || !ok {
@@ -195,6 +198,12 @@ func (b *bleLink) onNotify(buf []byte) {
 	}
 }
 
+func (b *bleLink) resetParser() {
+	b.parserMu.Lock()
+	b.parser = uartframe.NewParser()
+	b.parserMu.Unlock()
+}
+
 func (b *bleLink) Close() error {
 	return b.device.Disconnect()
 }
@@ -243,6 +252,9 @@ sent:
 	for {
 		remain := time.Until(deadline)
 		if remain <= 0 {
+			// Drop a half-parsed frame (e.g. aborted multi-notify) so the next
+			// exchange does not treat a new 0xAA as payload data.
+			b.resetParser()
 			return nil, fmt.Errorf("BLE read timeout for %s (check DIP8=BLE / -ble)", cmdName)
 		}
 		timer := time.NewTimer(remain)
@@ -264,6 +276,7 @@ sent:
 			}
 			return resp, nil
 		case <-timer.C:
+			b.resetParser()
 			return nil, fmt.Errorf("BLE read timeout for %s (check DIP8=BLE / -ble)", cmdName)
 		}
 	}

goTool/uart/frame.go

@@ -10,8 +10,10 @@ import (
 const (
 	StartMarker = 0xAA
 	StopMarker  = 0xCC
-	// Must match main/uart.h MAX_PAYLOAD_SIZE (MAX_BUF_SIZE - 4).
-	MaxPayload = 248
+	// Must match main/uart.h MAX_PAYLOAD_SIZE.
+	MaxPayload = 1024
+	// AA | len_lo | len_hi | payload | xor | CC
+	FrameOverhead = 5
 )
 
 var (
@@ -19,14 +21,15 @@ var (
 	ErrTimeout      = errors.New("read timeout")
 )
 
-// EncodeFrame builds a framed packet: 0xAA len payload xor(payload) 0xCC.
+// EncodeFrame builds a framed packet: 0xAA len_lo len_hi payload xor(payload) 0xCC.
 func EncodeFrame(payload []byte) ([]byte, error) {
 	if len(payload) == 0 || len(payload) > MaxPayload {
 		return nil, fmt.Errorf("payload length %d out of range 1..%d", len(payload), MaxPayload)
 	}
 
-	frame := make([]byte, 0, 4+len(payload))
-	frame = append(frame, StartMarker, byte(len(payload)))
+	n := len(payload)
+	frame := make([]byte, 0, FrameOverhead+n)
+	frame = append(frame, StartMarker, byte(n&0xff), byte((n>>8)&0xff))
 	var checksum byte
 	for _, b := range payload {
 		frame = append(frame, b)
@@ -39,6 +42,7 @@ func EncodeFrame(payload []byte) ([]byte, error) {
 type Parser struct {
 	state    int
 	len      int
+	lenLo    byte
 	payload  []byte
 	index    int
 	checksum byte
@@ -46,7 +50,8 @@ type Parser struct {
 
 const (
 	stateStart = iota
-	stateLen
+	stateLenLo
+	stateLenHi
 	stateData
 	stateChecksum
 	stateStop
@@ -63,14 +68,19 @@ func (p *Parser) Feed(b byte) (payload []byte, ok bool, err error) {
 		if b == StartMarker {
 			p.index = 0
 			p.checksum = 0
-			p.state = stateLen
+			p.state = stateLenLo
 		}
-	case stateLen:
-		if b == 0 || b > MaxPayload {
+	case stateLenLo:
+		p.lenLo = b
+		p.state = stateLenHi
+	case stateLenHi:
+		n := int(p.lenLo) | (int(b) << 8)
+		if n == 0 || n > MaxPayload {
 			p.state = stateStart
 		} else {
-			p.len = int(b)
+			p.len = n
 			p.payload = make([]byte, p.len)
+			p.index = 0
 			p.state = stateData
 		}
 	case stateData:
@@ -102,7 +112,7 @@ func (p *Parser) Feed(b byte) (payload []byte, ok bool, err error) {
 // maxWait bounds total wait time; zero means no limit (serial read timeouts retry forever).
 func ReadFrame(r io.Reader, buf []byte, maxWait time.Duration) ([]byte, error) {
 	if buf == nil {
-		buf = make([]byte, 256)
+		buf = make([]byte, 1024)
 	}
 	parser := NewParser()
 

main/README.md

@@ -166,7 +166,7 @@ Hardware: **UART1**, **921600** baud, **TX = GPIO3**, **RX = GPIO2** (adapter TX
 | Field | Value |
 |-------|--------|
 | Start | `0xAA` |
-| Length | 1 byte, payload size 1–252 |
+| Length | 2 bytes little-endian, payload size 1–1024 |
 | Payload | `length` bytes |
 | Checksum | XOR of all payload bytes |
 | Stop | `0xCC` |
@@ -178,7 +178,7 @@ Hardware: **UART1**, **921600** baud, **TX = GPIO3**, **RX = GPIO2** (adapter TX
 | 0 | Command ID (`MessageType` / `msg_id`) |
 | 1… | Arguments (handler receives bytes after ID only) |
 
-Example VERSION request: single-byte payload `03` → frame `AA 01 03 03 CC`.
+Example VERSION request: single-byte payload `03` → frame `AA 01 00 03 03 CC`.
 
 Logging:
 

main/ble_host.c

@@ -4,6 +4,7 @@
 #include "host_transport.h"
 #include "nvs_flash.h"
 #include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
 #include "freertos/task.h"
 
 #include "nimble/nimble_port.h"
@@ -22,6 +23,12 @@ static const char *DEVICE_NAME = "Powerpod";
 #define BLE_CONN_ITVL_MIN_UNITS 6 /* 7.5 ms */
 #define BLE_CONN_ITVL_MAX_UNITS 6
 #define BLE_CONN_TUNE_MAX_TRIES 6
+/** Prefer large ATT MTU so CLIENT_INFO / BATTERY fit in fewer notify chunks. */
+#define BLE_PREFERRED_ATT_MTU 517
+#define BLE_NOTIFY_CHUNK_RETRIES 24
+#define BLE_NOTIFY_CHUNK_RETRY_MS 5
+/** Pace multi-chunk notifies so the central parser sees contiguous frame bytes. */
+#define BLE_NOTIFY_CHUNK_GAP_MS 8
 
 /*
  * Nordic UART style:
@@ -43,6 +50,7 @@ static bool notify_enabled;
 static uint16_t att_mtu = 23;
 static esp_timer_handle_t conn_tune_timer;
 static uint8_t conn_tune_tries;
+static SemaphoreHandle_t s_tx_mu;
 
 static int ble_gap_event(struct ble_gap_event *event, void *arg);
 static void ble_request_fast_conn_params(uint16_t handle);
@@ -61,28 +69,83 @@ uint16_t ble_host_max_payload(void) {
   return (uint16_t)(att_mtu - 3);
 }
 
-static esp_err_t ble_host_tx(const uint8_t *frame, size_t frame_len) {
-  struct os_mbuf *om;
-  int rc;
+/**
+ * One ATT notification (≤ MTU-3). Retries on transient NimBLE buffer pressure.
+ */
+static esp_err_t ble_notify_chunk(const uint8_t *data, uint16_t len) {
+  for (int attempt = 0; attempt < BLE_NOTIFY_CHUNK_RETRIES; attempt++) {
+    struct os_mbuf *om = ble_hs_mbuf_from_flat(data, len);
+    if (om == NULL) {
+      vTaskDelay(pdMS_TO_TICKS(BLE_NOTIFY_CHUNK_RETRY_MS));
+      continue;
+    }
 
+    int rc = ble_gatts_notify_custom(conn_handle, ble_chr_val_handle, om);
+    if (rc == 0) {
+      return ESP_OK;
+    }
+    /* Ownership stays with us on failure. */
+    os_mbuf_free_chain(om);
+    if (!ble_host_ready()) {
+      return ESP_ERR_INVALID_STATE;
+    }
+    ESP_LOGD(TAG, "notify chunk rc=%d attempt=%d len=%u", rc, attempt,
+             (unsigned)len);
+    vTaskDelay(pdMS_TO_TICKS(BLE_NOTIFY_CHUNK_RETRY_MS));
+  }
+  ESP_LOGW(TAG, "notify chunk gave up after retries len=%u", (unsigned)len);
+  return ESP_ERR_NO_MEM;
+}
+
+/**
+ * Send a full host frame. If larger than ATT MTU-3, split across consecutive
+ * notifies; goTool feeds every notify into the same byte parser, so the frame
+ * reassembles without a protocol change. Mutex keeps stream ticks from
+ * interleaving mid-frame.
+ */
+static esp_err_t ble_host_tx(const uint8_t *frame, size_t frame_len) {
   if (!ble_host_ready()) {
     return ESP_ERR_INVALID_STATE;
   }
-  if (frame_len == 0 || frame_len > ble_host_max_payload()) {
+  if (frame == NULL || frame_len == 0) {
+    return ESP_ERR_INVALID_ARG;
+  }
+
+  uint16_t max_chunk = ble_host_max_payload();
+  if (max_chunk == 0) {
     return ESP_ERR_INVALID_SIZE;
   }
 
-  om = ble_hs_mbuf_from_flat(frame, (uint16_t)frame_len);
-  if (om == NULL) {
-    return ESP_ERR_NO_MEM;
+  if (s_tx_mu == NULL ||
+      xSemaphoreTake(s_tx_mu, pdMS_TO_TICKS(2000)) != pdTRUE) {
+    return ESP_ERR_TIMEOUT;
   }
 
-  rc = ble_gatts_notify_custom(conn_handle, ble_chr_val_handle, om);
-  if (rc != 0) {
-    os_mbuf_free_chain(om);
-    return ESP_FAIL;
+  esp_err_t result = ESP_OK;
+  size_t off = 0;
+  while (off < frame_len) {
+    if (!ble_host_ready()) {
+      result = ESP_ERR_INVALID_STATE;
+      break;
+    }
+    size_t remain = frame_len - off;
+    uint16_t n =
+        (uint16_t)(remain > max_chunk ? max_chunk : remain);
+    result = ble_notify_chunk(&frame[off], n);
+    if (result != ESP_OK) {
+      ESP_LOGW(TAG, "TX abort at %u/%u (chunk %u, mtu_pay %u)",
+               (unsigned)off, (unsigned)frame_len, (unsigned)n,
+               (unsigned)max_chunk);
+      break;
+    }
+    off += n;
+    if (off < frame_len) {
+      vTaskDelay(pdMS_TO_TICKS(BLE_NOTIFY_CHUNK_GAP_MS));
+    }
   }
-  return ESP_OK;
+
+  xSemaphoreGive(s_tx_mu);
+  return result;
 }
 
 static void ble_conn_tune_timer_cb(void *arg) {
@@ -365,6 +428,12 @@ esp_err_t init_ble_host(QueueHandle_t cmd_queue) {
   host_transport_set_cmd_queue(cmd_queue);
   host_transport_set_tx(ble_host_tx);
 
+  s_tx_mu = xSemaphoreCreateMutex();
+  if (s_tx_mu == NULL) {
+    ESP_LOGE(TAG, "failed to create TX mutex");
+    return ESP_ERR_NO_MEM;
+  }
+
   /* NVS may already be init via pod_settings; ignore ALREADY_INIT. */
   ret = nvs_flash_init();
   if (ret == ESP_ERR_NVS_NO_FREE_PAGES ||
@@ -404,9 +473,11 @@ esp_err_t init_ble_host(QueueHandle_t cmd_queue) {
     return ESP_FAIL;
   }
 
-  rc = ble_att_set_preferred_mtu(247);
+  rc = ble_att_set_preferred_mtu(BLE_PREFERRED_ATT_MTU);
   if (rc != 0) {
     ESP_LOGW(TAG, "preferred MTU set failed: %d", rc);
+  } else {
+    ESP_LOGI(TAG, "preferred ATT MTU %u", (unsigned)BLE_PREFERRED_ATT_MTU);
   }
 
   nimble_port_freertos_init(ble_host_task);

main/ble_host.h

@@ -16,7 +16,7 @@ bool ble_host_ready(void);
 /** Negotiated ATT MTU (default 23 until exchange). */
 uint16_t ble_host_att_mtu(void);
 
-/** Max notify/write payload bytes (ATT MTU - 3). */
+/** Max bytes per ATT notify/write (ATT MTU - 3). Frames may span multiple notifies. */
 uint16_t ble_host_max_payload(void);
 
 #endif

main/ble_stream.c

@@ -7,10 +7,9 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "ota_session.h"
-#include "pb_encode.h"
-#include "uart.h"
 #include "uart_cmd.h"
 #include "uart_messages.pb.h"
+#include "uart_proto.h"
 #include <string.h>
 
 static const char *TAG = "[BLE_STREAM]";
@@ -102,34 +101,22 @@ static bool any_accel_stream(void) {
 }
 
 static esp_err_t send_tick_truncated(alox_UartMessage *msg) {
-  uint8_t pb_buf[MAX_PAYLOAD_SIZE];
-  pb_ostream_t stream = pb_ostream_from_buffer(pb_buf, sizeof(pb_buf));
-
+  /*
+   * ble_host_tx splits frames larger than ATT MTU-3 across notifies. Only
+   * shrink the tick if it cannot encode into MAX_PAYLOAD_SIZE.
+   */
   while (true) {
-    stream = pb_ostream_from_buffer(pb_buf, sizeof(pb_buf));
-    if (!pb_encode(&stream, alox_UartMessage_fields, msg)) {
-      return ESP_FAIL;
+    esp_err_t err = uart_send_uart_message(msg);
+    if (err == ESP_OK) {
+      return ESP_OK;
     }
-
-    size_t payload_len = stream.bytes_written + 1;
-    uint16_t max_pay = ble_host_max_payload();
-    /* Framed size = payload + 4; notify must fit ATT MTU-3. */
-    size_t frame_len = payload_len + 4;
-    if (payload_len <= MAX_PAYLOAD_SIZE && frame_len <= max_pay) {
-      uint8_t payload[MAX_PAYLOAD_SIZE];
-      payload[0] = (uint8_t)msg->type;
-      memcpy(&payload[1], pb_buf, stream.bytes_written);
-      return uart_send_framed(payload, payload_len);
-    }
-
     if (msg->payload.ble_stream_tick.clients_count == 0) {
-      ESP_LOGW(TAG, "tick too large even with 0 clients (need %u max %u)",
-               (unsigned)frame_len, (unsigned)max_pay);
-      return ESP_ERR_NO_MEM;
+      ESP_LOGW(TAG, "tick too large even with 0 clients: %s",
+               esp_err_to_name(err));
+      return err;
     }
-
     msg->payload.ble_stream_tick.clients_count--;
-    ESP_LOGW(TAG, "truncating tick clients to %u for MTU",
+    ESP_LOGW(TAG, "truncating tick clients to %u for encode buffer",
              (unsigned)msg->payload.ble_stream_tick.clients_count);
   }
 }
@@ -197,7 +184,7 @@ void ble_stream_update(void) {
 
   if (want && !s_running) {
     s_running = true;
-    if (xTaskCreate(ble_stream_task, "ble_stream", 4096, NULL, 5, &s_task) !=
+    if (xTaskCreate(ble_stream_task, "ble_stream", 8192, NULL, 5, &s_task) !=
         pdPASS) {
       s_running = false;
       s_task = NULL;

main/host_transport.c

@@ -22,14 +22,14 @@ void host_transport_set_cmd_queue(QueueHandle_t cmd_queue) {
 
 QueueHandle_t host_transport_cmd_queue(void) { return s_cmd_queue; }
 
-bool host_enqueue_packet(const uint8_t *payload, uint8_t len) {
+bool host_enqueue_packet(const uint8_t *payload, size_t len) {
   if (s_cmd_queue == NULL || payload == NULL || len == 0) {
     return false;
   }
 
   generic_msg_t msg = {
       .msg_id = payload[0],
-      .len = len > 1 ? (size_t)(len - 1) : 0,
+      .len = len > 1 ? (len - 1) : 0,
       .payload = NULL,
   };
 
@@ -63,10 +63,11 @@ esp_err_t host_send_framed(const uint8_t *payload, size_t len) {
     checksum ^= payload[i];
   }
 
-  uint8_t frame[4 + MAX_PAYLOAD_SIZE];
+  uint8_t frame[UART_FRAME_OVERHEAD + MAX_PAYLOAD_SIZE];
   size_t pos = 0;
   frame[pos++] = START_MARKER;
-  frame[pos++] = (uint8_t)len;
+  frame[pos++] = (uint8_t)(len & 0xff);
+  frame[pos++] = (uint8_t)((len >> 8) & 0xff);
   memcpy(&frame[pos], payload, len);
   pos += len;
   frame[pos++] = checksum;

main/host_transport.h

@@ -19,7 +19,7 @@ void host_transport_set_cmd_queue(QueueHandle_t cmd_queue);
 QueueHandle_t host_transport_cmd_queue(void);
 
 /**
- * Build AA|len|payload|xor|CC and send via the registered TX backend.
+ * Build AA|len_lo|len_hi|payload|xor|CC and send via the registered TX backend.
  * Same semantics as uart_send_framed.
  */
 esp_err_t host_send_framed(const uint8_t *payload, size_t len);
@@ -31,6 +31,6 @@ esp_err_t host_send_framed(const uint8_t *payload, size_t len);
 void host_rx_bytes(const uint8_t *data, size_t len);
 
 /** Enqueue a completed uart_packet_t (payload[0]=msg type). */
-bool host_enqueue_packet(const uint8_t *payload, uint8_t len);
+bool host_enqueue_packet(const uint8_t *payload, size_t len);
 
 #endif

main/uart.c

@@ -81,18 +81,27 @@ bool parse_uart_byte(uint8_t byte, uart_packet_t *p) {
     if (byte == START_MARKER) {
       p->index = 0;
       p->checksum = 0;
-      p->state = STATE_LEN;
+      p->len = 0;
+      p->state = STATE_LEN_LO;
     }
     break;
 
-  case STATE_LEN:
-    if (byte > MAX_PAYLOAD_SIZE || byte == 0) {
+  case STATE_LEN_LO:
+    p->len = byte;
+    p->state = STATE_LEN_HI;
+    break;
+
+  case STATE_LEN_HI: {
+    uint16_t len = (uint16_t)(p->len | ((uint16_t)byte << 8));
+    if (len == 0 || len > MAX_PAYLOAD_SIZE) {
       p->state = STATE_START;
     } else {
-      p->len = byte;
+      p->len = len;
+      p->index = 0;
       p->state = STATE_DATA;
     }
     break;
+  }
 
   case STATE_DATA:
     p->payload[p->index++] = byte;

main/uart.h

@@ -22,13 +22,18 @@
 #define UART_DRIVER_TX_BUF_SIZE 4096
 #define START_MARKER 0xAA
 #define STOP_MARKER 0xCC
-#define MAX_BUF_SIZE 252
-#define MAX_PAYLOAD_SIZE                                                       \
-  MAX_BUF_SIZE - 4 // Buffer overhead, Start, Len, CRC, End
+/** Frame: AA | len_lo | len_hi | payload[len] | xor | CC */
+#define UART_FRAME_OVERHEAD 5
+/**
+ * Max application payload (type byte + protobuf). Sized for CLIENT_REGISTRY_MAX
+ * aggregations (CLIENT_INFO / BATTERY_STATUS with 16+ samples).
+ */
+#define MAX_PAYLOAD_SIZE 1024
 
 typedef enum {
   STATE_START,
-  STATE_LEN,
+  STATE_LEN_LO,
+  STATE_LEN_HI,
   STATE_DATA,
   STATE_CHECKSUM,
   STATE_STOP
@@ -36,8 +41,8 @@ typedef enum {
 
 typedef struct {
   uint8_t payload[MAX_PAYLOAD_SIZE];
-  uint8_t len;
-  uint8_t index;
+  uint16_t len;
+  uint16_t index;
   uint8_t checksum;
   parser_state_t state;
 } uart_packet_t;

main/uart_cmd.c

@@ -42,7 +42,8 @@ void uart_cmd_init_response(alox_UartMessage *msg, alox_MessageType type,
 esp_err_t uart_cmd_send(const alox_UartMessage *msg, const char *log_tag) {
   esp_err_t err = uart_send_uart_message(msg);
   if (err != ESP_OK && log_tag != NULL) {
-    ESP_LOGE(log_tag, "failed to send UART response");
+    ESP_LOGE(log_tag, "failed to send UART response: %s",
+             esp_err_to_name(err));
   }
   return err;
 }

main/uart_proto.c

@@ -1,18 +1,26 @@
 #include "uart_proto.h"
+#include "esp_log.h"
 #include "pb_encode.h"
 #include "uart.h"
 #include <string.h>
 
+static const char *TAG = "[UART_PROTO]";
+
 esp_err_t uart_send_uart_message(const alox_UartMessage *msg) {
   uint8_t pb_buf[MAX_PAYLOAD_SIZE];
   pb_ostream_t stream = pb_ostream_from_buffer(pb_buf, sizeof(pb_buf));
 
   if (!pb_encode(&stream, alox_UartMessage_fields, msg)) {
+    ESP_LOGE(TAG, "pb_encode failed type=%u (%s)", (unsigned)msg->type,
+             PB_GET_ERROR(&stream));
     return ESP_FAIL;
   }
 
   uint8_t payload[MAX_PAYLOAD_SIZE];
   if (stream.bytes_written + 1 > sizeof(payload)) {
+    ESP_LOGE(TAG, "payload too large type=%u need=%u max=%u",
+             (unsigned)msg->type, (unsigned)(stream.bytes_written + 1),
+             (unsigned)sizeof(payload));
     return ESP_ERR_NO_MEM;
   }