Roadmap

Fri, 29 May 2026 00:00:00 -0500

This roadmap groups the project’s open work into themes. It’s distilled from the public issue tracker — issue numbers link to the canonical discussion, which is always the source of truth.

Concepts & Vocabulary

Fri, 29 May 2026 00:00:00 -0500

The Hive AI design borrows its structure from social insects: a colony with a ruler, members that take on specialized roles, and a kind of shared awareness across the group. Every metaphor maps cleanly onto an engineering construct. This page defines both sides so the rest of the documentation can use the shorthand.

The metaphor → the machinery

Biology In the hive Engineering reality

Hive / colony One MagNET deployment on a LAN A set of nodes sharing a hive_id and a pre-shared secret

Ruler / queen The coordinator A device running the ruler firmware: advertises itself, accepts joins, holds the peer table and shared-memory store

Biologic A hive member A node running updatable Forth code over ESP-IDF

Spawn A newborn with no job A freshly joined node holding the default spawn role until promoted

Role A member’s specialization A named behavior (worker, scribe, spy, …), delivered as a signed Forth role bundle

DNA

What proves family

A per-lineage secret key baked into firmware, used by the

HIVE AI

Architecture & Topology

Fri, 29 May 2026 00:00:00 -0500

A MagNET hive is a star at the protocol level: one ruler, many nodes, each node talking to one ruler at a time. The richness comes from what flows over those links — authenticated joins, role grants, and shared-memory queries.

Topology at the current checkpoint

graph TD
    R["M5Dial (ESP32-S3)<br/>role = ruler<br/>mDNS advert · peer table · KV store"]
    R -- "mDNS _magnet-ruler._tcp<br/>+ HMAC-SHA256 over TCP" --- E["Atom Echo (ESP32)<br/>role = spawn<br/>hex LEDs + chirps"]
    R --- C["ESP32-CAM / Unit CamS3<br/>role = spy<br/>/stream MJPEG"]
    R --- P["M5Capsule (ESP32-S3)<br/>role = scribe<br/>KV in NVS (+ Redis sidecar)"]
    R --- B["ReSpeaker (XIAO S3)<br/>role = boombox<br/>audio notifications"]
    R --- F["scripts/fake_ruler.py<br/>(laptop dev harness)"]

A node discovers the ruler via mDNS, opens a TCP connection, and authenticates with a shared-secret HMAC. The ruler keeps a small table of live peers and serves a hive-wide key-value store. The same fake_ruler.py laptop script can stand in for either side, which makes the text-based wire format easy to debug with nc, Wireshark, or Python. See the full

HIVE AI

The 12 Roles

Fri, 29 May 2026 00:00:00 -0500

A role is the runtime function a node performs. Roles model the division of labor in a colony — most are general behaviors that any capable node can take on, a few are tied to specific hardware. A node starts as a spawn and can be promoted to another role at runtime via a

HIVE AI

Hive Protocol v1
Ruler discovery, length-prefixed JSON transport, HMAC-SHA256 authentication, the message types, and the node state machine." data-bs-toggle="tooltip" href="https://projectmagnet-github-docs.pages.dev/docs/hive-ai/hive-protocol/#role_grant-ruler--node">ROLE_GRANT, which delivers the role’s behavior as a

HIVE AI

Hive Protocol v1

Fri, 29 May 2026 00:00:00 -0500

The hive protocol is the wire language nodes and rulers speak. It is deliberately text-based and inspectable — you can play either side with nc, a Python script, or Wireshark. This page is the implementer-facing reference; both sides live in the craw_hive component.

Goals and non-goals

Goals

A node that already has WiFi can find a ruler on the same LAN with zero configuration.
A join is authenticated by a pre-shared secret — a stolen MAC alone cannot impersonate a node.
The wire format is readable, so any tool can participate for debugging.

Non-goals (v1)

Generations & the Lineage Gate

Fri, 29 May 2026 00:00:00 -0500

How does a hive decide whether a newcomer is one of us? The answer combines a versioning scheme (which firmware family a node belongs to) with a cryptographic membership test (proving it descends from that family). This page covers both — Layer 1 (observational versioning) and Layer 2 (the lineage puzzle gate).

Why three version axes

A biologic carries three orthogonal version concepts. Keeping them separate avoids grief whenever any one moves:

Signed Role Bundles

Fri, 29 May 2026 00:00:00 -0500

A role bundle is a signed JSON envelope carrying ESPIDFORTH source that a receiving node executes via forth_eval_n(). Bundles are how a hive teaches its nodes new behavior at runtime — without reflashing. Implementation lives in the craw_role_bundle component.

Design goals

Self-contained — everything a node needs to install and run a role (source, version, signature).
Verifiable — the signature catches tampering and lets a node refuse an unauthorized publisher.
Portable — any chip running ESPIDFORTH and the matching FFI words can install any bundle whose caps_req it satisfies.
Compact — typical bundles are < 2 KB, fitting in a single hive KV_DATA frame (3 KB cap).

Wire format

  {
  "name":      "spy",
  "version":   "1.0.3",
  "min_proto": 1,
  "author":    "iotone-dev",
  "caps_req":  ["camera", "jpeg"],
  "deps":      [],
  "crc32":     "a1b2c3d4",
  "sig_alg":   "hmac-sha256",
  "sig":       "f17b...",
  "src_b64":   "OiBzcHktbG9vcCAuLi4="
}

Field	Purpose
`name`	Role name (≤ 32 chars)
`version`	SemVer; a node refuses a bundle older than the installed one (monotonic upgrade)
`min_proto`	Minimum hive-protocol version; future-proto bundles are refused
`author`	Selects which trusted key the signature must validate against
`caps_req`	Capabilities the role needs; refused if the node’s caps don’t cover them
`deps`	Bundles expected first (not enforced in v1)
`crc32`	CRC-32 of the decoded source; defends against base64 corruption
`sig_alg`	`hmac-sha256` in v1; `ed25519` planned for v2
`sig`	Signature over the canonical signing input
`src_b64`	Base64 Forth source; decoded ≤ 4096 bytes for v1

Canonical signing input

  "<name>|<version>|<min_proto>|<author>|<crc32>|<src_b64>"

Pipe-delimited, that exact order, no whitespace. For hmac-sha256:

The Cast: Devices & Boards

Fri, 29 May 2026 00:00:00 -0500

Each node type is a separate PlatformIO project assembled from the

HIVE AI

Architecture & Topology
How a ruler and its nodes fit together, the shared component stack, and the load-bearing bring-up order." data-bs-toggle="tooltip" href="https://projectmagnet-github-docs.pages.dev/docs/hive-ai/architecture/#the-shared-component-stack">shared component stack. All join the hive through the same protocol; they differ in hardware and the role-specific work they do.

The ruler — M5Stack Dial


Project	`M5StackDial-m5gfx-demo-ESPIDFORTH`
MCU	ESP32-S3 (no PSRAM)
Distinguishing hardware	1.28" round touch LCD, rotary encoder, LEDC buzzer
Role	Ruler (Role 1)

The Dial runs the ruler firmware: it advertises _magnet-ruler._tcp over mDNS, maintains up to 8 peer sessions (one FreeRTOS task per client), and shows BLE / WiFi / hive status plus a live peer count as colored dots on the round display. A serial REPL exposes ruler-status, grant-role, lineage-auth, and the KV words. It began life as the Pharkie m5gfx playground, reimplemented atop ESP-IDF + ESPIDFORTH.

Controlling the Hive from Forth

Fri, 29 May 2026 00:00:00 -0500

Every MagNET node runs an ESPIDFORTH interpreter with a serial REPL. Hardware features and hive operations are exposed as Forth words — so you can drive a node live over USB serial, and bundle authors get the same vocabulary to compose new roles. Stack effects use the standard ( before -- after ) notation.

warning

ESPIDFORTH (the E4TH dialect) is lowercase and case-sensitive — use do/loop/if, not their uppercase forms, or words silently fail to parse. Also call forth_init() before NimBLE/WiFi/httpd, or the dictionary heap starves.

Display & app words (Dial)

Word	Effect	Notes
`theme`	`( n -- )`	Switch display theme (6 available)
`brightness`	`( n -- )`	Set backlight
`ping`	`( -- )`	Ripple animation
`starburst`	`( -- )`	Starburst animation
`invert`	`( -- )`	Invert display colors
`mute`	`( -- )`	Toggle the buzzer
`appbeep`	`( -- )`	Beep via the LEDC buzzer
`appsleep`	`( -- )`	Sleep display until touch/encoder
`appshowmem`	`( -- )`	Dump memory state to the display
`appdevinfo`	`( -- )`	Dump CPU / device info to the display

Provisioning words (every node)

Word	Effect
`prov-status`	Print BLE + WiFi + IP + hostname + hive state
`prov-reset`	Clear stored WiFi credentials and reboot into BLE provisioning

  boombox> prov-status
ble:    MagNET-biologic-XXXX
wifi:   connected
ip:     192.168.1.42
time:   synced
host:   magnet-boombox-XXXX.local
hive:   joined

Ruler words (Dial)

Word Effect

ruler-status Print ruler id, hive id, gen, gate state, and the peer table

grant-role Send a ROLE_GRANT to a connected peer

lineage-auth

( n -- ) — 1 enables the

HIVE AI

Scribe & the Redis Sidecar

Fri, 29 May 2026 00:00:00 -0500

The Scribe (Role 4) is the hive’s memory keeper — “its only job is to save data to its internal memory and recall it from shared memory if asked.” It runs on the M5Capsule, whose 8 MB flash and oversized 64 KB NVS partition make it the natural store for hive shared memory and

HIVE AI

Signed Role Bundles
How the hive teaches nodes new behavior at runtime — the envelope format, signing, install pipeline, and authoring." data-bs-toggle="tooltip" href="https://projectmagnet-github-docs.pages.dev/docs/hive-ai/role-bundles/">role bundles.

Boombox: Audio Notifications

Fri, 29 May 2026 00:00:00 -0500

The Boombox (Role 12) is the hive’s voice — “any speaker or audio playback device; unlike the beeper, it can play full sounds, music, or recordings.” It runs on a XIAO ESP32-S3 socketed onto a Seeed ReSpeaker Lite Voice Kit, and synthesizes everything in software — no PCM files.

Audio architecture

16 kHz / 16-bit synth → 32-bit stereo I2S at slave-mode frame rate. The ESP32-S3 is the I2S slave; the on-carrier XMOS XU316 generates BCLK/WS and routes audio to the TLV320AIC3204 codec and speaker.
Software synth — a 256-entry sine LUT with linear interpolation and Q16.16 phase accumulation.
Render task drains a FreeRTOS queue of play requests; each request is up to 32 segments. Segment kinds: TONE, SWEEP, AM, SLEEP. Each can carry a gain envelope (gain → gain_end) for click-free attack/release.
No PCM on disk — patterns are static arrays in flash. Adding a notification is one new array; bundle authors get the same primitives with no C at all.

graph LR
    A["Forth REPL"] --> Q["request queue (16 deep)"]
    K["KV cmd poll"] --> Q
    Q --> RT["render task<br/>(sine LUT)"]
    RT --> I["I2S0 (slave)"]
    I --> X["XU316 router"]
    X --> C["codec → speaker"]

info

The pin map (BCLK = GPIO8, WS = GPIO7, DOUT = GPIO43, slave mode, 32-bit stereo slots with int16→int32 sign-extension) is confirmed against Seeed’s reference example. Getting any of role/pins/format wrong produces white noise — all three must match the carrier.

Primitives

These are the building blocks; the canned recipes and any bundle-authored sound compose from them.

Bench Bring-Up & Verification

Fri, 29 May 2026 00:00:00 -0500

This is a reader-facing adaptation of the project’s bench test plan for the 0.5.0-spore rev. Run it top to bottom; every step lists what to do, what to expect, and what a deviation means — so the first failure is itself the diagnostic.

Prerequisites

On the bench: a Dial (ruler), at least one peer (Echo / Matrix / C3U), a Capsule (Redis variant), optionally a Camera.
One 2.4 GHz SSID for everything, with mDNS unblocked. On macOS, System Settings → Privacy → Local Network must allow Terminal/Python.
Laptop tools: redis-cli (brew install redis), nc, Python 3.11+ for scripts/fake_ruler.py.
Two terminals: one pio device monitor on the device under inspection, one for laptop scripts.

1. Flash everything (ruler first)

Flash the ruler first so a newer ruler can recognize older nodes during a transition (see the

HIVE AI

Project MagNET

Roadmap

Concepts & Vocabulary

The metaphor → the machinery link

Architecture & Topology

Topology at the current checkpoint link

The 12 Roles

Hive Protocol v1

Goals and non-goals link

Generations & the Lineage Gate

Why three version axes link

Signed Role Bundles

Design goals link

Wire format link

Canonical signing input link

The Cast: Devices & Boards

The ruler — M5Stack Dial link

Controlling the Hive from Forth

Display & app words (Dial) link

Provisioning words (every node) link

Ruler words (Dial) link

Scribe & the Redis Sidecar

Boombox: Audio Notifications

Audio architecture link

Primitives link

Bench Bring-Up & Verification

Prerequisites link

1. Flash everything (ruler first) link

The metaphor → the machinery

Topology at the current checkpoint

Goals and non-goals

Why three version axes

Design goals

Wire format

Canonical signing input

The ruler — M5Stack Dial

Display & app words (Dial)

Provisioning words (every node)

Ruler words (Dial)

Audio architecture

Primitives

Prerequisites

1. Flash everything (ruler first)