Hex ↔ Main protocol

Transport and ownership

The prototype direction is a compact binary protocol over a shared I²C bus. The Base Board initiates transactions; each Smart Hex is an addressed endpoint. Separate CHAIN input/output GPIOs determine the order in which hexes become eligible for addressing.

The wire protocol has not been implemented or finalized. This page contains proposals. The local OLED is on a separate bus and does not participate in the main protocol.

Enumeration

The fixed chain is MAIN → H0 → H1 → H2 → H3 → H4 → H5 → H6. I²C addresses alone do not encode physical order.

The sequence expresses intended behavior, not the mechanism for the initial address exchange. An unenumerated hex must not collide with another unenumerated hex. Boot address, chain eligibility gating, activation polarity, timing, acknowledgments, reset behavior, and end-of-chain detection all remain TBD.

Illustrative runtime addresses are H0 = 0x20, H1 = 0x21, H2 = 0x22, H3 = 0x23, H4 = 0x24, H5 = 0x25, H6 = 0x26. These are example 7-bit addresses, not a reserved allocation or a definition of shifted address bytes. Check the final bus device inventory before allocation.

Candidate commands

Command	Intended meaning	Response or open detail
PING	Check device responsiveness	Health/error response TBD
GET_STATUS	Read local state and device information	Snapshot schema TBD
GET_SENSORS	Read sensor observations	Empty/unknown/identity encoding TBD
SET_NUMBER	Set semantic number token	Valid values and acknowledgment TBD
SET_DISPLAY_MODE	Select local display behavior	Mode precedence and duration TBD
GET_FIRMWARE_VERSION	Query installed hex software	Version format TBD
ENTER_BOOTLOADER	Enter future firmware-update flow	Recovery mechanism not defined

For example, SET_NUMBER 8 describes meaning only; it is not a textual command to transmit. The hex renders pixels locally.

Conceptual framing and data contracts

[COMMAND] [LENGTH] [PAYLOAD] [CRC]

This is a framing idea, not a packet specification. Field widths, byte order, maximum length, CRC algorithm and coverage, request/response distinction, I²C transaction boundaries, and error codes are unassigned.

The local HexStatus example describes useful data. Firmware version, protocol compatibility, index, sensor identity, and diagnostics need explicit encoding before implementation. Board-global IDs belong in the Base Board mapping layer, not in local sensor reports.

Timing and recovery

The implementation will need bounded request lengths, validation before state changes, timeouts, and defined retry behavior. Repeating SET_NUMBER can be designed to be idempotent; a bootloader command requires its own retry semantics. Do not infer those guarantees from the current command names.

Polling versus change notification, snapshot consistency, missed-update recovery, busy responses, chain restarts, and a device holding the bus low are unresolved. A failed read must preserve an unavailable/stale indication rather than invent empty sensors.

Future versions

When a wire version is defined, add a versioned page here covering transport assumptions, fields, message examples, compatibility negotiation, limits, errors, checksums, retries, and migration behavior. Link the version from this page. There is no protocol v1, assigned opcode table, or deprecated message set yet.

Related: Smart Hex wiring, Base Board software, and firmware updates.