Initial commit

tcp-command-frame/readme.md

@@ -0,0 +1,60 @@
+# TCP Command Frame
+
+## Authorship
+
+This document was generated using ChatGPT (OpenAI), version 5.2.
+It has not been independently reviewed or validated yet.
+
+# Planned design
+
+## Transport
+
+* TCP (lwIP raw API).
+* Single synchronous request/response per connection.
+* TCP flow control is the only queue.
+
+## Future goals
+
+* HMAC with preshared key
+
+## Framing
+
+
+```
+cmd (1 byte)
+len (2 bytes, uint16)
+payload (len bytes)
+```
+
+## Limits
+
+* `MAX_PAYLOAD` compile-time constant.
+* Fixed local frame buffer: `uint8_t frame[MAX_PAYLOAD]`.
+* No dynamic allocation based on `len`.
+
+## Parser
+
+* Stateful stream parser (READ_CMD → READ_LEN → READ_PAYLOAD).
+* Accumulate until full frame received.
+* When `len > MAX_PAYLOAD` → `tcp_abort()` immediately.
+* On complete frame → execute command → send response → reset parser.
+
+## Memory safety
+
+* Only copy up to `MAX_PAYLOAD`.
+* Call `tcp_recved()` only for consumed bytes.
+* `pbuf_free()` after processing.
+* No resynchronization logic.
+* Protocol violation ⇒ connection closed.
+
+## Commands (initial)
+
+* `SETUP_I2C`
+* `I2C_XFER` (write + read with bounded `wlen`/`rlen`)
+
+## Result
+
+* Deterministic RAM usage.
+* Clear failure behavior.
+* Minimal parser complexity.
+* No reliance on TCP message boundaries.