All multi-byte numbers are little-endian unless specified. One COBS-encoded frame followed by 00 is the unit of transmission. Decoder storage is bounded; an oversize frame is discarded until the next delimiter.
Decoded header (18 bytes): magic u16 0x3255, version u8 1, kind u8, session u32, channel u8, reserved u8 0, sequence u32, payload length u16, reserved u16 0. Payload (0..4096 bytes) follows; final u32 is IEEE CRC32 over header and payload. CRC/malformed frames are silently discarded and counted.
Kinds: HELLO=1, HELLO_ACK=2, ACK=3, OPEN=4, OPENED=5, DATA=6, CLOSE=7, RPC=8, RPC_REPLY=9, ERROR=10, BUSY=11, ABORT=12. There are eight logical channels: 0 management, 1..4 one TCP connection each, 5 telemetry, 6 logs, and 7 OTA. Channels 0/5/6/7 carry RPC/RPC_REPLY and cannot allocate TCP sockets. TCP frames on these control channels, and RPC frames on TCP channels, are invalid. Values 8..255 are invalid channel IDs. DATA uses at most 1024 bytes. All reliable kinds 4..10 use a per-direction, per-channel sequence starting at 1 and incrementing without reset when a connection slot is reused. Sequence wrap closes the link.
Host generates a cryptographically random nonzero session ID. HELLO uses channel0/sequence0/empty payload; device resets its connection and security state on a NEW session, and echoes HELLO_ACK. Duplicate HELLO for the current session only repeats HELLO_ACK, without resetting anything. Frames from other sessions are discarded. Host performs one handshake per Link object; reconnect creates a new Link. Device reboot invalidates old TCP and security state.
Each channel has at most one outstanding reliable frame. Receiver ACKs the same channel/sequence only after accepting a frame into its bounded queue. Old duplicate sequence numbers are ACKed without re-execution; future numbers are discarded. When a queue is full the expected frame is not accepted/ACKed; receiver emits BUSY with the same sequence and empty payload, providing implicit receive credit. Sender retransmits identical bytes every 500ms, at most 10 unanswered retries. A matching BUSY resets the retry budget, allowing indefinite application backpressure while the peer remains responsive. Exhaustion closes the entire session to avoid ambiguous sequence/cryptographic state. Each of the eight channels has independent bounded transmit resources and reliable sequence state; firmware reserves separate receive queues for control channels. A single physical writer services ACK/HELLO/ABORT first and the eight channel queues round-robin. No application request is replayed on a new session.
OPEN payload is UTF-8 host:port (bracketed IPv6 accepted); firmware resolves DNS and opens the socket only after the secure session has authenticated. OPENED empty payload signals success; ERROR payload is UTF-8 diagnostic and terminates the connection. DATA is opaque stream bytes. CLOSE empty payload terminates both directions. CLOSE must be acknowledged and earlier incoming bytes delivered before EOF. Local cancellation releases the connection; transport failure invalidates all connections. OPEN/OPENED and CLOSE exchanges complete before a channel slot may be reused.
The first CLOSE in either direction requires one reciprocal reliable CLOSE (duplicates only receive ACK). Host closing a stream drains/discards remaining stream frames until that reciprocal CLOSE. The host allows up to three seconds to reconcile a cancelled in-flight frame before sending CLOSE; healthy streams and management continue during this cleanup. If delivery or the CLOSE barrier cannot be established, the entire ambiguous session fails rather than admitting old bytes into a reused slot.
ABORT is a host-to-device priority signal outside the reliable sequence space. It has empty payload, channel 1..4, and its sequence field MUST equal that connection's OPEN sequence. The device only cancels a matching session/channel/OPEN incarnation; stale ABORTs are discarded. ABORT interrupts pending TCP connect/send and allows queued stream DATA to be accepted/ACKed and discarded so a pending frame does not prevent the reliable CLOSE from advancing. ABORT itself needs no ACK; the host repeats it every 200ms during cancellation cleanup. ABORT does not release a channel or replace the reciprocal CLOSE reuse barrier.
RPC payload: u32 request ID, u8 endpoint-name byte length, endpoint UTF-8 bytes, raw Protocomm input. RPC_REPLY: matching u32 request ID, u8 status (0 success, 1 error), raw Protocomm output (or UTF-8 diagnostic). Replies MUST use the request's logical channel. Only one RPC round trip executes at once across all four control channels, preserving the single shared Security2 session's nonce order. sec-session exchanges the unencrypted ESP-IDF SessionData/Sec2Payload protobuf handshake exclusively on channel 0. rpc exchanges AES-GCM ciphertext of the JSON management contract on channel 0, 5, 6 or 7. Other names are rejected by the firmware. Security 2 patch 1 is required: SRP6a RFC5054 3072-bit group g=5 with SHA512; first 32 bytes of session key feed AES256-GCM; 12-byte device nonce increments its last 4 bytes as a big-endian counter after EVERY successful encryption/decryption. Authentication/decryption/uncertain RPC failure invalidates the client session; no security0/1 downgrade or nonce reuse is permitted.
Security protobuf encoding follows ESP-IDF components/protocomm/proto/session.proto and sec2.proto. Pairing uses unique per-device username/password and stored salt/verifier, never an embedded common password. GPIO mapping and UART settings are outside the binary protocol.
link.New(io.ReadWriteCloser, link.Options) starts the bounded frame reader/writer; call Handshake(context.Context) before DialContext(ctx, "tcp", "host:port") or RPC(ctx, endpoint, bytes). Stats, Done, Err, and Close expose lifecycle/telemetry. Options select retry interval and maximum unanswered retries. The transport has no socket dialer and therefore cannot fall back to the computer's network. net.Conn supports cancellation, dynamic read/write deadlines, bounded receive queues, and a four-slot limit.
link.WithRPCChannel(ctx, channel uint8) selects ChannelManagement, ChannelTelemetry, ChannelLogs or ChannelOTA for the subsequent secure RPC; the default is management. Apply this context before security.Client.Call, which forwards it unchanged. Security handshakes always use management even if a different lane is requested. Request IDs are global across control lanes; a response with the wrong lane or ID invalidates the link. The host keeps one bounded response queue because secure calls are globally serialized; distinct framing, sequence spaces and firmware queues do not imply parallel use of the cipher nonce.
security.New(username,password) returns a fresh client. Handshake(ctx, link.RPC) verifies the server's SRP proof. Call(ctx,"rpc",jsonBytes) encrypts, sends, and authenticates one request/response pair under a mutex; Ready exposes whether it remains usable. An uncertain secure RPC failure requires a fresh transport and client, because nonce counters cannot safely be resynchronized by guessing. The host should paginate large registry/status results and send OTA in small chunks so encrypted replies fit the 4096-byte payload ceiling.
The transport tests exercise four simultaneous byte streams, immediate capacity rejection, channel reuse barriers, CRC/COBS corruption, dropped ACK/retransmission, duplicate delivery suppression, stale sessions, disconnected peers, all four control lanes while four receive queues are saturated, lane validation and mismatched reply rejection, BUSY beyond the retry limit, and cancellation that preserves unrelated channels. Security tests compare SRP values with a fixed vector produced by ESP-IDF v6.0.1's official Python reference, exercise the protobuf handshake and concurrent AES-GCM exchanges, and reject altered proofs, unsafe public keys and corrupted ciphertext. These host tests are not a substitute for serial hardware, device firmware interoperability, or power-loss acceptance tests.