+
+
Binarization Protocol
+
+⚠️ EXPERIMENTAL: subject to change without warning
+
+
The HiveMind Binarization Protocol is designed to efficiently serialize and deserialize structured messages into compact binary formats for network transmission. This document provides a high-level description of the protocol, including its structure, encoding rules, and the rationale behind key design decisions. The binary format is protocol-versioned to support backward compatibility and future extensions.
+
Protocol Versions
+
The protocol uses an integer version number to indicate supported features and ensure compatibility between clients and servers. The current protocol version is 1. Any change in functionality or structure requires incrementing the version number.
+
Version-specific functionality:
+
+-
+
Version 0: Original protocol design. No binarization, no handshake, only pre-shared crypto_key supported
+
+-
+
Version 1: Introduces support for handshakes and binary payloads.
+
+
+
Message Types
+
Messages in the HiveMind protocol are categorized into various types, each serving a specific role. These types are encoded as 5-bit unsigned integers, enabling up to 32 distinct types. Examples include:
+
+
+
+| Value |
+Type |
+Description |
+
+
+
+
+| 0 |
+HANDSHAKE |
+Initial connection handshake. |
+
+
+| 1 |
+BUS |
+Standard message bus. |
+
+
+| 2 |
+SHARED_BUS |
+Shared bus for multiple nodes. |
+
+
+| 3 |
+BROADCAST |
+Global message broadcast. |
+
+
+| 4 |
+PROPAGATE |
+Directed message propagation. |
+
+
+| 12 |
+BINARY |
+Raw binary payload. |
+
+
+
+
Compression
+
Payloads can optionally be compressed using the zlib library. A single bit in the header indicates whether compression is applied. Compressed payloads reduce transmission size but may add slight computational overhead during encoding and decoding.
+
+
HiveMeta is a reserved field for attaching arbitrary metadata to a message. The metadata is encoded as a byte array, prefixed by its size (in bytes). This allows for extensible features like routing hints or debug information.
+
Binary Message Structure
+
The serialized binary message consists of a header and a payload. All fields are packed to maximize efficiency. The structure is as follows:
+
+
The header contains information about the protocol version, message type, compression, and metadata length.
+
+
+
+| Field |
+Size (bits) |
+Description |
+
+
+
+
+| Start Marker |
+1 |
+Always 1. Helps align message boundaries. |
+
+
+| Versioned Flag |
+1 |
+Indicates if protocol version is specified. |
+
+
+| Protocol Version |
+8 |
+Protocol version (if Versioned Flag is 1). |
+
+
+| Message Type |
+5 |
+Encoded message type. |
+
+
+| Compressed Flag |
+1 |
+Indicates if payload is compressed. |
+
+
+| Metadata Length |
+8 |
+Length of metadata in bytes. |
+
+
+
+
+
Metadata is optional and encodes key-value pairs or other information. If present, it follows the header and is serialized as a byte array. The length of the metadata is specified in the header.
+
Payload
+
The payload represents the core message data. Its format depends on the message type:
+
+
Padding
+
To ensure byte alignment, padding bits (0) are inserted as needed. The total length of the message must be a multiple of 8 bits.
+
Encoding Process
+
+-
+
Start Marker: Add a single bit set to 1 to signify the start of the message.
+
+-
+
Header Fields:
+
+- Add a 1-bit flag to indicate whether the protocol version is included.
+- If the version is included, append the 8-bit protocol version number.
+- Add a 5-bit message type field.
+- Add a 1-bit flag to indicate compression status.
+- Add an 8-bit metadata length field.
+
+
+-
+
Metadata:
+
+- Serialize metadata as a JSON object (if any).
+- Compress the metadata if compression is enabled.
+- Append the serialized metadata.
+
+
+-
+
Payload:
+
+- Serialize the payload according to the message type.
+- Compress the payload if compression is enabled.
+- Append the serialized payload.
+
+
+-
+
Padding: Add 0 bits as needed to ensure the total length is a multiple of 8 bits.
+
+
+
Decoding Process
+
+-
+
Alignment: Read bits until encountering the start marker (1).
+
+-
+
Header Fields:
+
+- Read the
Versioned Flag and determine if the protocol version is specified.
+- If specified, read the 8-bit protocol version number.
+- Read the 5-bit message type field.
+- Read the
Compressed Flag.
+- Read the 8-bit metadata length field.
+
+
+-
+
Metadata:
+
+- Read the specified number of bytes for metadata.
+- Decompress if the
Compressed Flag is set.
+- Deserialize the metadata.
+
+
+-
+
Payload:
+
+- Read the remaining bits as the payload.
+- Decompress if the
Compressed Flag is set.
+- Deserialize the payload based on the message type.
+
+
+
+
Binary Payloads
+
The protocol provides support for binary payloads, enabling the transmission of non-textual data. Binary payloads are handled based on their designated types, which instruct the HiveMind how to process the binary content.
+
The binary payload type is indicated in the header as a 4 bit unsigned integer after the metadata and before the payload
+
+
+
+| Value |
+Type |
+Description |
+
+
+
+
+| 0 |
+UNDEFINED |
+No information provided about the binary contents. |
+
+
+| 1 |
+RAW_AUDIO |
+Binary content is raw audio. |
+
+
+| 2 |
+NUMPY_IMAGE |
+Binary content is an image represented as a numpy array (e.g., webcam picture). |
+
+
+| 3 |
+FILE |
+Binary is a file to be saved; additional metadata is provided elsewhere. |
+
+
+| 4 |
+STT_AUDIO_TRANSCRIBE |
+Full audio sentence to perform Speech-to-Text (STT) and return transcripts. |
+
+
+| 5 |
+STT_AUDIO_HANDLE |
+Full audio sentence to perform STT and handle transcription immediately. |
+
+
+| 6 |
+TTS_AUDIO |
+Synthesized Text-to-Speech (TTS) audio to be played. |
+
+
+
+
+💡 this how how the microphone satellite streams audio to hivemind-listener
+
+
Examples
+
Serialized Message
+
For a simple message with:
+
+
The binary representation might look like this (in bit groups):
+
1 | 1 | 00000001 | 00001 | 0 | 00000000 | <metadata> | <payload>
+
+
Where:
+
+-
+
1 (Start Marker)
+
+-
+
1 (Versioned Flag)
+
+-
+
00000001 (Protocol Version)
+
+-
+
00001 (Message Type: BUS)
+
+-
+
0 (Compressed Flag)
+
+-
+
00000000 (Metadata Length: 0 bytes)
+
+-
+
<metadata>: Serialized metadata bytes.
+
+-
+
<payload>: Serialized payload bytes.
+
+
+
Binary data
+
For a binary payload with:
+
+-
+
Protocol version: 1
+
+-
+
Message type: BINARY
+
+-
+
No compression
+
+-
+
Metadata: {}
+
+-
+
Binary Payload
+
+
+
The binary representation might look like this (in bit groups):
+
1 | 1 | 00000001 | 00001 | 0 | 00000000 | <metadata> | 0001 | <binary_payload>
+
+
Where:
+
+-
+
1 (Start Marker)
+
+-
+
1 (Versioned Flag)
+
+-
+
00000001 (Protocol Version)
+
+-
+
01100 (Message Type: BINARY)
+
+-
+
0 (Compressed Flag)
+
+-
+
00000000 (Metadata Length: 0 bytes)
+
+-
+
<metadata>: Serialized metadata bytes.
+
+-
+
0001 (Binary Type: Raw audio)
+
+-
+
<payload>: audio bytes.
+
+
+
More examples
+
<uint:1=start_marker> | <uint:1=versioned_bit> | <uint:8=protocol_version> | <uint:5=msg_type> | <uint:1=compression_bit> | <uint:8=metadata_len> | <metadata> | <payload>
+
+
A binarized uncompressed message
+
1 | 1 | XXXXXXXX | XXXXX | 0 | XXXXXXXX | <metadata> | <payload>
+
+
A unversioned and compressed binarized message
+
1 | 0 | XXXXX | 1 | XXXXXXXX | <metadata> | <payload>
+
+
A binary uncompressed payload message
+
1 | 1 | XXXXXXXX | 01100 | 0 | XXXXXXXX | <metadata> | XXXX | <payload>
+
+
A unversioned and compressed binary payload message
+
1 | 0 | 01100 | 1 | XXXXXXXX | <metadata> | XXXX | <payload>
+
+
+💡 the binarization scheme allows the protocol to be implemented by just flashing a light
+
+
Compression Metrics
+
Compression significantly reduces payload size for larger messages but is not always efficient for small messages. Benchmarks indicate a reduction of up to 50% for text-heavy payloads, while small payloads may see negligible benefits.
+
+
+NOTE: A Terminal is like a Slave, but it is NOT a Mind
