How signal profiles work

Dynamic signal profiles let an organization change what its Status Displays render — colors, pulses, stale behavior — without a firmware rebuild. The architecture keeps that convenience inside the same safety boundary the display system already had: Print Hive is the only writer of display state, and every change lands as durable, verifiable evidence before any light changes.

One writer of display state

A Status Display shows the status of explicitly assigned Printers. Only Print Hive can write that state. Hive Link continues to supply Printer observations — it never acquires a display-writing role, so a compromised or misconfigured host can report state but cannot draw on the strip. The display credential is broker-scoped in the other direction too: it can subscribe only to its own display's topics and publish only on its own credential-bound paths. It holds no Print Hive API access and cannot reach a sibling display.

The UI follows the same rule. Editing a draft never streams frames or moves a slider value to hardware. Every change goes through the same path: draft, immutable revision, explicit assignment, retained delivery, device receipt.

Controllers render locally, without API credentials

The controller receives one complete compiled profile and renders it locally at its own 50 ms cadence. It never calls the Print Hive API, holds no API keys, and executes no downloaded code — a profile is a bounded data structure of channel values and durations, validated byte for byte before it can activate. WLED keeps ownership of the physical outputs: color order, relay configuration, and power limits. If trustworthy state disappears, the device's existing safety behavior overrides every configured pattern.

Why one complete retained profile

Version 1 sends the whole profile — at most 750 decoded bytes — in a single retained profile/config message. A complete image gives atomic validation: the bytes either decode and pass every check or none of them apply, so a display can never run half a palette. Retained delivery gives free recovery: a controller that reconnects receives the current desired profile from the broker without a cloud round trip. The alternatives were rejected deliberately — per-pattern objects need missing-object requests and cache eviction, and patches need an exact base plus a full-image recovery path. The cost is that a reconnect can redeliver unchanged bytes; the SHA-256 lets the device recognize them and skip the flash write.

PostgreSQL owns the truth

Drafts, immutable revisions, desired activations, and receipts live in organization-scoped PostgreSQL tables. The broker is transport, not authority: a server restart rebuilds the retained desired configuration from the database, never from whatever the broker happens to hold. This is also why publishing a library revision does not silently retarget displays — the desired state is a per-display record that only an explicit assignment changes, in one transaction that validates capabilities, allocates the generation, and enqueues the immutable delivery.

Revisions are immutable because displays run them. If a published revision could change under a fleet, two displays could legitimately disagree about what the same bytes mean. A rollback is therefore a new activation pointing at older bytes, not an edit.

Generations and the admission fence

Every activation carries a generation that only increases within a Display Binding. Because the ordering is per display and not per profile, switching between two different libraries still has one ordering — there is no way to replay last week's profile over today's. A newer generation can skip predecessors because its payload is complete.

On the device, the admission fence is the durable floor. The controller writes the candidate bytes, verifies them, persists the fence — generation, revision ID, and hash — and only then promotes the candidate. A failed fence write cannot activate anything. The fence recovers independently of the profile blob: restoring an older backup must not lower the admitted generation, because that would reopen the door to replayed activations. If no trustworthy fence survives corruption, the device fails closed — fixed safe output and no profile activation — until a new Display Binding is established through re-pairing. Rebind allocates a new epoch, so cached bytes from the old binding lose all authority.

Receipts are not broker acknowledgements

A QoS 1 acknowledgment proves the broker accepted the message. It says nothing about the device. The profile status receipt is different: the controller publishes it only after the profile is durably installed and swapped in at a render boundary, and it carries three separate identities — what the device actually runs (active), what this result attempted (attempted), and the durable fence floor (highest_admitted). The API marks an activation device_applied only when the receipt's active identity exactly equals the desired generation, revision, and hash — and only from the current credential and session with an increasing sequence. That is why a lost receipt causes bounded republication of the same desired activation rather than a false success, and why device_applied still does not claim physical light output — it proves durable installation, not photons.

Negotiated, not assumed

The extension is advertised, not silently added to strict v1 schemas. A controller reports its format version, decoder size bound, phase limit, and white/CCT support; the API refuses assignments the hardware cannot honor before any bytes are published. Firmware without the capability keeps its built-in patterns and can never be claimed to run a dynamic profile.

What is deliberately excluded

• No animation frames and no per-pattern delta transfer — one complete bounded message per activation.
• No Printer IDs, pixel assignments, network addresses, or credentials inside a profile — printer rebalancing never invalidates it.
• No combined mapping-and-profile activation — the two operations stay independent so neither can pretend to be atomic.
• No extension of the completion window or the four-flash limit — a profile cannot buy more attention than the existing completion policy grants.
• No silent recovery of a corrupted admission fence — fail closed and rebind instead.

For the wire format and route surface, see the signal profile reference. For the operator path, start with set up your first status display.