This is a read-only mirror of the HSC engineering wiki, restored from a 2017 archive. Some links are broken and some content is out of date. About this mirror.
Pheromone Bus Wire Format
From ANTFARM Wiki
This is an old revision of this page, as archived. The mirror serves the archived text for every revision id.
| ⌛ | This page has not been updated since 2012-02-11 and may describe behaviour that no longer exists. |
| Pheromone Bus Wire Format | |
|---|---|
| Service | phero |
| Framing | 4-byte length prefix |
| Payload | IACP JSON line |
| Status | stale |
| Archive ref | QUANTARA-SWARMGLASS-R45-A4F955 |
Contents[hide] |
The byte layout of a phero bus frame. Unchanged since 1.0; the 2.0 binary framing (Deprecated Agent API) would have replaced it and did not.
[edit] Frame
offset size field 0 4 length (big-endian uint32) of payload 4 n payload: one IACP message, UTF-8 JSON, trailing "\n" included in n
That is the entire format.
[edit] Connection handshake
client → broker SUB <trail-prefix> <last-seq>\n
broker → client OK <current-seq>\n
(replay frames if last-seq < current-seq - 1)
client → broker PUB <trail>\n followed by a frame
SUB and PUB lines are plain text before the first frame; after that, everything is frames. A client that sends SUB after frames get ERR proto\n and is disconnected.
[edit] Sequence numbers
Per trail, 64-bit, start at 1, never wrap. Delivered in the frame's IACP id? No — that is a separate namespace. The sequence number is prepended to replayed frames as SEQ <n>\n and omitted on live frames, which every client handles by ignoring lines starting with SEQ unless it is resyncing. This is documented nowhere but here and in the client source.
[edit] Example session
SUB queen.assign.forager-07 118\n
OK 121\n
SEQ 119\n
[4-byte len]{"v":"1.1",...}\n
SEQ 120\n
[4-byte len]{"v":"1.1",...}\n
SEQ 121\n
[4-byte len]{"v":"1.1",...}\n
[4-byte len]{"v":"1.1",...}\n <- live
