title: Rendering vocabulary description: Generated tables of the RFC-048 rendering vocabulary: categories, ranks, value axes, units, action tags, archetypes, regions, renderer classes and widget patterns. register: IEEE generated: true
Rendering vocabulary#
These are the numbers behind RENDERING.md, the normative UI-rendering companion to the specification. Every vocabulary below is frozen at the v1.0 tag. None is wired onto a real catalog entry yet. See the specification's known limitations.
Categories#
category answers WHERE a catalog entry lives. Ids 1 to 15 are the frozen, complete spec set, in canonical menu order; 5 and 9 are retired and never emitted. An unrecognized id, including a retired or untaught vendor id, MUST render under other. It keeps the catalog-provided label. It is never dropped.
| Id | Category | Tier | Notes |
|---|---|---|---|
1 |
generator |
machine |
RFC-094 (was control): driving the machine now: the generators and patterns, move, streams |
2 |
motion |
machine |
live physical telemetry; since RFC-094 also the engine internals and calibration that were tuning (9), under subgroup Tuning |
3 |
safety |
machine |
faults, interlocks, e-stop state: the stop affordance itself is rank-pinned (ui_ranks), not a menu item here |
4 |
limits |
machine |
window + ceilings |
5 |
library |
retired | RETIRED pre-tag by RFC-094: folded into system (13) under subgroup Library. Never reissued. |
6 |
playback |
machine |
hub-local content transport: play/pause/seek/queue |
7 |
auxiliary |
machine |
secondary actuators: heat, lube, suction, inflation |
8 |
automation |
machine |
routines, schedules, scenes |
9 |
tuning |
retired | RETIRED pre-tag by RFC-094: folded into motion (2) under subgroup Tuning. Never reissued. |
10 |
hardware |
machine |
geometry, drive config, sensors, homing |
11 |
network |
link |
WiFi/BLE state, endpoints, provisioning |
12 |
session |
link |
clients, roles, ownership, pairing/trust |
13 |
system |
machine |
diagnostics and configuration: power, thermals, memory, firmware, logs; since RFC-094 also the stored content that was library (5) (presets, patterns, scripts, positions, profiles), under subgroup Library |
14 |
other |
machine |
the defined overflow: every unrecognized category id (including an untaught vendor id) renders here, per the graceful-extension rule |
15 |
setup |
machine |
RFC-079: the machine COMMISSIONING surface: network credentials (provisioning 0x000F), machine name, accessory pairing, and the machine's own geometry and ceilings. Pinout and board-level facts stay out. A config-mode client opens here with the wizard pattern (§13.4.1). |
0x40 to 0x7E is the vendor/device range. A hub that declares one MUST supply a label. 16 to 0x3F is reserved for future spec-registered categories. 0x7F and above is reserved.
Navigation tiers#
Above the categories sit three tiers. A renderer draws tiers in id order, then categories in registry order within a tier. The tier is not on the wire: it is the category's row above. Vendor and unrecognized ids are tier 1.
| Id | Tier | Notes |
|---|---|---|
1 |
machine |
things on the machine: every tier-1 category, every vendor id and every unrecognized id |
2 |
link |
things on or between the machine and its clients: network (11), session (12), and the renderer-provided views of the protocol itself (pairing, the session view, the 0x0008 log) |
3 |
client |
renderer-local settings (display, plugins, saved hubs, an embedded server). No category and no catalog entry ever lands here; the id is reserved so every renderer draws the same three, in the same order |
Ranks#
rank answers HOW MUCH a catalog entry or field matters by default. Unknown rank, or no rank annotation at all, renders as detail.
| Id | Rank | Notes |
|---|---|---|
0 |
hero |
the machine's face; surfaced by default on every renderer class |
1 |
control |
everyday driving controls; surfaced by default on handheld/full, one navigation step away on glance |
2 |
detail |
useful but not primary; reachable, not surfaced |
3 |
advanced |
the setting_flags.advanced bit's migration into this ladder; hidden behind an advanced affordance by default, NEVER removed from the surface |
4 |
diagnostic |
reachable on every class; a renderer MAY choose to omit it under its own display budget, but that is the renderer's choice, not this rank's |
5 |
hidden |
carried on the wire for compatibility, NEVER rendered: the honest home for an inert-but-released field |
Value axes#
Three small, orthogonal vocabularies tag what statistic a field is. The default, when none is given, is live / session / actual.
Aspect#
| Id | Aspect | Notes |
|---|---|---|
0 |
live |
the value now (default) |
1 |
peak |
highest observed |
2 |
min |
lowest observed |
3 |
mean |
average observed |
4 |
total |
cumulative (an odometer figure) |
5 |
rate |
a derivative/frequency quantity |
Scope#
| Id | Scope | Notes |
|---|---|---|
0 |
session |
since this client connected (default) |
1 |
lifetime |
since the device was manufactured/last factory-reset |
2 |
window |
a bounded rolling window, device-defined width |
Provenance#
| Id | Provenance | Notes |
|---|---|---|
0 |
demand |
the raw requested value |
1 |
planned |
the target the planner is currently aiming for |
2 |
actual |
the measured value (default). demand/planned/actual are one quantity at three stages; the axis archetype's commanded-vs-actual overlay is their companion composition. |
Units#
Units are a frozen numeric companion to the existing free-string unit field. Both exist side by side. This table is not yet wired onto real catalog fields; that is next-phase work. The list is deliberately larger than current needs, to cover future actuators. An unrecognized unit id renders the catalog's own label string verbatim.
| Id | Unit | Quantity |
|---|---|---|
0 |
mm |
length |
1 |
mm_s |
speed (mm/s) |
2 |
mm_s2 |
acceleration (mm/s²) |
3 |
mm_s3 |
jerk (mm/s³) |
4 |
normalized |
0-1 |
5 |
percent |
% |
6 |
hz |
Hz |
7 |
ms |
milliseconds |
8 |
s |
seconds |
9 |
v |
volts |
10 |
a |
amps |
11 |
w |
watts |
12 |
wh |
watt-hours |
13 |
deg_c |
°C |
14 |
count |
dimensionless count |
15 |
bytes |
data size |
16 |
db |
decibels |
17 |
n |
force, over-provisioned: force-feedback actuators |
18 |
kpa |
pressure, over-provisioned: suction/inflation |
19 |
ml |
volume, over-provisioned: lube dosing |
20 |
ml_min |
flow rate, over-provisioned: lube dosing |
21 |
rpm |
rotational speed, over-provisioned: rotary actuators |
22 |
bpm |
beats per minute, over-provisioned: bio-sync accessories |
23 |
deg |
RFC-086: angle in degrees. Radians are a math convenience, not a knob unit. |
24 |
us |
RFC-086: microseconds, the §7 hub-time resolution (only ms and s were registered) |
25 |
hub_s |
RFC-086: seconds in the hub's own §7.1 timebase, distinct from s so a client knows to apply its CLOCK offset; the unit of the RFC-083 datetime.* roles. Temperature stays deg_c only: K and F are display conversions. |
Action tags#
A conformant client MAY special-case the specific action.<name> suffixes below. This lets it upgrade a generic trigger archetype into a purpose-specific rendering. An unregistered suffix remains legal. An unrecognized one renders as a generic trigger.
| Tag | Meaning |
|---|---|
move |
the primary positional command: usually already the axis archetype's own binding, rarely a separate trigger |
safety |
a safety-adjacent action outside the law-bound stop archetype and the three safety pairs themselves (RFC-085: pause/resume, override/return, estop/release are bound by op identity, never by this tag) |
home |
a homing-cycle trigger |
calibrate |
a calibration-cycle trigger; commonly the entry point to a wizard widget pattern |
reset |
aspect-group reset linkage (value_aspects/RENDERING.md §5.4); co-located with the group it resets, confirm-gated |
save |
persist current state (settings, not a preset item) |
persist |
commit a value past a reboot: distinct from setting_flags.restart_required, which is about WHEN a change takes effect, not whether it survives one |
pair |
enters a pairing ceremony affordance |
identify |
blink-to-find: every device ecosystem needs one |
admin |
a generic administrative action not covered by a more specific tag |
reboot |
firmware reboot; SHOULD always confirm (cbor_keys.reboot_in_ms) |
accessory |
RFC-076: the accessory-admin op select on core channel 0x0012 (§8.10), options index-aligned with accessory_admin_ops. Op forget is destructive. |
provision |
RFC-069: the provisioning op select on core channel 0x000F (§13.9), options index-aligned with provisioning_ops |
trial |
RFC-099: the settings-trial op select on core channel 0x0016 (§9.3), options index-aligned with trial_ops. Neither op is destructive: commit stores values already live, revert restores stored ones. |
store |
RFC-067: the store CRUD op select (§8.7): options index-aligned with store_ops; no options beyond the registered ops. Op delete is destructive by registration (§8.8). |
Store ops#
The wire values of an action.store op select (SPEC §8.7). Index 0 is op-select filler.
| Value | Name | Notes |
|---|---|---|
1 |
save |
capture current live state into the slot; a supplied payload makes it an import (§8.7) |
2 |
load |
apply the slot; the resulting truth arrives on the ordinary STATE broadcasts |
3 |
delete_item |
the delete verb (named delete_item only because the generated C++ constant would otherwise be a keyword; prose and catalog labels say 'delete'): remove the slot's item. Destructive by registration (§8.8): a client confirm-gates it without a flag |
4 |
rename |
change the slot's item name (<= the store's name_max) |
Provisioning ops#
The wire values of the action.provision op select on core channel 0x000F (SPEC §13.9). Index 0 is op-select filler.
| Value | Name | Notes |
|---|---|---|
1 |
wifi_join |
join the WiFi network named by ssid with passphrase; answered after the join concludes (§13.9) |
Settings-trial ops#
The wire values of the action.trial op select on core channel 0x0016 (SPEC §9.3). Index 0 is op-select filler.
| Value | Name | Notes |
|---|---|---|
1 |
commit |
persist every value the sender trial-wrote, as it stands, and clear the sender's trial set. No effective value changes, so cfg_gen does not move. |
2 |
revert |
restore every pre-trial value of the sender's trial set and clear it. A restored value that differs bumps cfg_gen and republishes. Never refused: where a constraint no longer admits a pre-trial value, the nearest legal one. |
Archetypes#
An archetype is the control style and interaction contract a catalog field or channel renders with. A normative decision table derives it in the common case (RENDERING.md §8.2). An explicit archetype hint overrides that table. Fallback is the mandatory composition of frozen primitives every archetype declares. A primitive lists itself.
| Id | Archetype | Semantic | Fallback |
|---|---|---|---|
0 |
readout |
display of a value; bounds present -> bar/gauge projection | readout |
1 |
indicator |
status lamp; never the sole carrier of a safety fact | indicator |
2 |
slider |
bounded numeric intent; commit-on-release | slider |
3 |
stepper |
precision numeric, increments in step-sized ticks |
stepper |
4 |
toggle |
boolean | toggle |
5 |
select |
enum + options; wire value is the array index; index 0 is filler only on op selects (SPEC §8.9, RFC-064) | select |
6 |
trigger |
payload-less intent (button); destructive invocation (setting_flags.destructive, destructive_options, action.reboot/reset; SPEC §8.8) -> mandatory confirm on every class | trigger |
7 |
axis |
1-D positional hero control (role command.position) with commanded-vs-actual overlay; carries the override/return pair on its control row (RFC-085) | axis |
8 |
chart |
time-series; glance degrades to sparkline/value; missing samples render as gaps | chart |
9 |
list |
roster/store items + item actions; pending is a THIRD state distinct from success/failure | list |
10 |
text |
constrained string; glance projects a digit/char wheel: the pairing-PIN path | text |
11 |
stop |
the safety stop affordances (RFC-085: the estop/release and pause/resume controls, one control per pair): bound BY LAW to safety-op identity, never derived from annotation; reachable at every rank on every class, never role-gated, never hidden | stop |
12 |
pad2d |
two-axis control: the multi-axis runway; triggered by two command.position fields on one INTENT entry (RFC-083) | slider + slider |
13 |
color |
chromatic actuator setpoint (lighting/glow accessories); triggered by color.red/green/blue in one group (RFC-083) | slider + slider + slider |
14 |
datetime |
moment/interval input (automation schedules) in hub time; triggered by datetime.moment, or datetime.start + datetime.end in one group (RFC-083) | text |
Regions#
There are four abstract placement zones, plus one modal layer. Geometry, position, size and style within a region are the renderer author's craft. What lives in each region is normative.
| Id | Region | Contents |
|---|---|---|
0 |
primary |
hero-rank patterns (axis-hero and peers); the machine's face, exactly one per axis/capability instance |
1 |
persistent |
the safety-strip: latch state, ownership, the stop archetype. MUST remain visible in every navigation state of every class |
2 |
content |
the category tree's territory: cards/panes/menu screens in canonical category order; diagnostic-rank material last or collapsed by default |
3 |
utility |
connection/session status, identity, theme: chrome about the CLIENT, kept out of the machine's way |
4 |
overlay |
the modal layer: confirms, pairing knocks, alerts. Only ceremony/confirmation content may use it; nothing persistent lives here |
Renderer classes#
All classes render one category tree. They differ in projection and default surfacing, never in reachable content. A device between budgets adopts the nearer class.
| Id | Class | Notes |
|---|---|---|
0 |
glance |
OLED remote: home screen = hero-rank; categories = a menu stack; everything except diagnostic reachable by navigation; stop affordance reachable from every screen |
1 |
handheld |
phone: categories as sections/tabs; hero+control surfaced, detail one tap away |
2 |
full |
desktop: categories as panes, everything visible |
Widget patterns#
These are proven compositions extracted from the reference client. Required marks a pattern that a handheld or full client MUST provide when its capability is present. A glance-class device may reach it through the category tree instead.
| Id | Pattern | Composition | Required |
|---|---|---|---|
0 |
axis-hero |
rail + window band + command tape + live position/velocity numerals + nested plan-view; command-tape domain is the REPORTED window | yes |
1 |
plan-view |
in-flight plan lane; visibility gated by data freshness, collapses to zero height when idle | |
2 |
link-strip |
utility region: connection phase, rx liveness, catalog state; safety-relevant chips pinned, rest may scroll | |
3 |
safety-strip |
persistent region; ops sorted role-EXEMPT-first; stop sticky-visible within any overflow | |
4 |
settings-card |
a subgroup's fields via the archetype decision table; every disabled control shows WHICH gate disabled it | |
5 |
scope |
multi-lane strip chart: missing samples render as GAPS never zeros; series colors stable by declaration order across reconnects | |
6 |
event-stream |
bounded rings; unknown body fields render generically as key=value, never dropped; auto-scroll with user-scroll override | |
7 |
roster |
list + item actions; pending is a THIRD state distinct from success/failure; locked-by-role honestly distinct from empty | |
8 |
protocol-pane |
the one deliberately device-aware diagnostic surface: wire ids visible by design | |
9 |
pattern-panel |
the standard generator surface: run/stop with live state, pattern selection as an exclusive-choice group, knob sliders for whichever optional roles exist, source.background_run co-located with run/stop | yes |
10 |
generator-advanced |
the fray-d surface: master controls (advgen.* roles incl. its own run/stop advgen.running, RFC-081/RFC-093; the dwells advgen.dwell_crest and advgen.dwell_trough optional, RFC-095) + the modulators that target them (RFC-066), each rendered as a group under its target + preset save/recall via action.store (RFC-067), source.background_run co-located with the master run/stop |
yes |
11 |
transport |
playback: play/pause/seek/queue cluster for hubs that play content | |
12 |
wizard |
stepped ceremony flow: pairing, calibration, provisioning; glance-class projects it as sequential menu screens |