Catalog vocabulary#
The catalog describes what a hub's channels are. These are the registered words it uses to do that.
Packed field types#
A packed layout has static field offsets. Every type below is fixed-width, which is what makes append-only evolution safe.
| Value | Type | Notes |
|---|---|---|
0 |
u8 |
|
1 |
i8 |
|
2 |
u16 |
|
3 |
i16 |
|
4 |
u32 |
|
5 |
i32 |
|
6 |
f32 |
|
7 |
bitfield8 |
bit meanings enumerated in catalog entry |
8 |
str16 |
16 bytes, zero-padded UTF-8 (RFC-026). The default string width: session-roster names, device names, secret settings. |
9 |
str32 |
32 bytes, zero-padded UTF-8 (RFC-026) |
10 |
str64 |
64 bytes, zero-padded UTF-8 (RFC-026). 26% of a 242 B snapshot: use deliberately. |
STREAM sample layouts stay string-free. The motion path never pays for text.
Field roles#
A role is the semantic tag on a catalog field. It is a text string, not a number, because action roles carry a device-chosen suffix.
Roles are opportunities, never requirements. A client that recognizes a role may render a bespoke widget. A client that does not must render it generically instead, by type and constraints. An unknown role is never an error.
| Role | Meaning |
|---|---|
limit.jog.speed |
speed ceiling of the JOG (manual) limit set: jog moves and the override return run at it. CEILING, never a target. RFC-085 renamed it from limit.user.speed. |
limit.jog.accel |
accel ceiling of the jog limit set. RFC-085 renamed it from limit.user.accel. |
limit.input.speed |
speed ceiling of the INPUT (machine-driven: patterns, streams, TCode) limit set |
limit.input.accel |
accel ceiling of the input limit set |
limit.input.jerk |
jerk ceiling of the input limit set |
geometry.max_travel |
the configured travel ceiling: how far the machine's rail geometry allows it to search/move (0x0081 max_rail is the worked example: also the sensorless-homing search sweep bound). Distinct from window.min/max, which is the operator-chosen SUB-range within this travel. |
geometry.measured_travel |
the usable travel a real home actually measured between the two hard stops, as opposed to geometry.max_travel's configured ceiling. Zero/absent-of-meaning until the first successful home this session; a client MUST NOT treat zero as a real measurement. |
window.min |
stroke window lower bound. Limits normalized against the window are window-relative and therefore MOVE when it does: which is exactly why this is a STATE field and not a one-shot WELCOME value. |
window.max |
stroke window upper bound |
telemetry.position |
live actuator position |
telemetry.target |
RFC-032: the position the machine is currently COMMANDED to, as opposed to telemetry.position which is where it measurably is. Lag is deliberately NOT a role: it is target - position, computed client-side: registering a third field for a subtraction would invite two sources of truth for one number. On an EVENT body field (SPEC §8.8, §9.4, RFC-122) it is the target as commanded at emit time, in mm, bound within that entry. |
telemetry.velocity |
live actuator velocity |
telemetry.current |
motor/drive current |
telemetry.power.bus |
DC bus voltage or power |
telemetry.temp |
a temperature reading; the field's own name/unit says which |
telemetry.uptime |
hub uptime |
telemetry.sample_time |
RFC-113 (§9.1, §7.2): the hub time at which every other field of the same layout was sampled: u32 microseconds (unit_ids 24 us), wrapping under §7.2's STREAM rule. At most one per layout, and only on a periodic STATE channel (max_rate_hz > 0): on an on-change channel a fresh stamp makes every refresh a change and defeats conflation. An accessory declaration (§17.1.1) MUST NOT carry it: an accessory runs no CLOCK. Consumed, never drawn as a value: a declaration ranks it diagnostic. A client SHOULD time the snapshot by it, through its CLOCK offset, rather than by its arrival. |
identity.name |
the writable machine-name setting (RFC-026 tier 2, str16/str32). Its READ-ONLY twin is WELCOME identity.hub_name. |
meta.enabled_mask |
RFC-009.4: a bitfield8 field whose bit i gates the i-th setting-annotated field of the SAME layout. On-change, retained, conflated: every client grays from one ground truth. Disabled means GRAY, never hide. |
meta.trial_pending |
RFC-099 (§8.8): a bitfield8 field whose bit i marks the i-th setting-annotated field of the SAME layout as holding a TRIAL value (cbor_keys 51), any session's: indexed exactly as meta.enabled_mask. On-change, retained. A set bit means the effective value shown is not the stored one and reverts when its trial ends. |
meta.reset_gen |
RFC-019: increments on every applied reset in this counter group, so ALL subscribers observe the reset, not just the sender who asked for it. |
pattern.running |
whether the built-in (classic) pattern generator is currently driving the machine. The advanced generator has its own advgen.running (RFC-093). |
pattern.select |
which built-in pattern the generator plays; options are the device's pattern names, index-aligned with the wire value |
pattern.speed |
pattern generator speed knob, as a percentage of its own range |
pattern.depth |
pattern generator depth knob: how far into the stroke window it reaches |
pattern.stroke |
pattern generator stroke-length knob, as a percentage of the available depth |
pattern.sensation |
pattern generator character knob; what it changes depends on the selected pattern |
command.position |
RFC-032: INTENT field carrying a commanded ABSOLUTE target position in the channel's own unit. A client that finds it MAY render a positional control (rail, tape, slider) and send the value on that field's channel. |
axis.flipped |
RFC-088 (§9.6): a stored, writable bool (or two-option select) setting: the rail's direction flip. On, position 0 is the far end; the hub mirrors telemetry, the travel window and every c2h target against geometry.measured_travel. A change is refused SOURCE_CONFLICT while a source owns the rail, NOT_HOMED while unhomed, INTERLOCK under override or in motion. Rendered as the confirm-gated Flip toggle on the axis control row. |
input.target |
RFC-071: the commanded position of a motion-input sample or segment, in the field's own unit and scale. REQUIRED on a c2h STREAM entry that accepts motion. |
input.velocity |
RFC-071: a samples-kind point's instantaneous velocity hint. Optional; a client that does not understand it leaves the field at its unspecified sentinel (§5.4). |
input.duration |
RFC-071: a segments-kind sample's commanded time extent |
input.end_velocity |
RFC-071: a segments-kind sample's velocity at its end (the §9.6 handoff); its type minimum means unspecified (RFC-058) |
plan.start |
normalized start position of the segment in flight |
plan.end |
normalized end position of the segment in flight |
plan.current |
normalized current position along the plan |
plan.velocity |
current planned velocity |
plan.elapsed |
elapsed time within the segment in flight |
plan.duration |
total duration of the segment in flight |
plan.latency |
RFC-059: optional live telemetry twin of a grant's schedule_latency_us (cbor key 49), for diagnostics and generic renderers. Not required for conformance. |
plan.style |
which planning style produced the segment; options are the device's style names, index-aligned with the wire value |
plan.flags |
RFC-100 (§8.8): bitfield8, bits per plan_flags: set when a segment plans, from that plan, cleared when the next segment plans clean, zero while no plan is in flight. A segment planned ahead of its start sets it then, up to one schedule horizon early. A client reads the plan as infeasible when any of bits 0-2 is set; there is no plan.feasible role (one field, one source of truth). |
advgen.running |
RFC-093: bool, the advanced generator's own run/stop (essential binding of generator-advanced). The advanced generator is a separate §11.4 source: starting it while the classic generator (pattern.running) owns the rail is refused SOURCE_CONFLICT until that one stops, and vice versa. No auto-handoff. |
advgen.master |
RFC-081: overall rate scale of the advanced program, percent of its own range |
advgen.depth_max |
RFC-081: the deep stroke bound the program swings to, percent of the stroke window |
advgen.depth_min |
RFC-081: the shallow stroke bound the program swings to, percent of the stroke window |
advgen.speed_in |
RFC-081: inward stroke speed base |
advgen.speed_out |
RFC-081: outward stroke speed base |
advgen.accel_in |
RFC-081: inward acceleration base |
advgen.accel_out |
RFC-081: outward acceleration base |
advgen.dwell_crest |
RFC-095: hold at the deep bound (advgen.depth_max) after the inward half completes and before the reversal, unit strokes (the period of one stroke as the clock, two decimals), 0 = no hold. Additive: the stroke period grows by the dwell, the moving halves keep their speed and acceleration, and one stroke on the modulators' clock (RFC-066) is the whole cycle, both dwells included. A modulator whose mod_target is a dwell varies it per stroke. Optional binding of generator-advanced. |
advgen.dwell_trough |
RFC-095: hold at the shallow bound (advgen.depth_min) after the outward half completes and before the reversal, unit strokes (the period of one stroke as the clock, two decimals), 0 = no hold. Additive, as advgen.dwell_crest. Optional binding of generator-advanced. |
mod.amount |
RFC-066: how far the modulator swings its target, in the target's terms; 0 = no modulation |
mod.rise |
RFC-066: duration of the rising leg of the cycle (field unit: strokes or seconds) |
mod.hold |
RFC-066: dwell at the top of the cycle (field unit: strokes or seconds) |
mod.fall |
RFC-066: duration of the falling leg of the cycle (field unit: strokes or seconds) |
mod.rest |
RFC-066: dwell at the bottom of the cycle (field unit: strokes or seconds) |
mod.phase |
RFC-066: offset of this modulator's cycle start (field unit: strokes or seconds) |
mod.shape |
RFC-066: optional select naming the cycle shape; absent = the cycling trapezoid (rise, hold, fall, rest) |
osc.enabled |
RFC-103: bool, the oscillator runs. Never persisted (false at boot); cleared by the hub when the session that set it ends by any §6.9 door, the deadman included. |
osc.frequency |
RFC-103, RFC-112: f32, Hz, 0 .. WELCOME limits osc_max_hz (key 7), clamped: the hub's frequency cap, chosen from what its input ceilings let a sine render (§9.7). The moving part of one cycle takes 1 / frequency; dwells stretch the period beyond it. Driven by osc.frequency.drive. |
osc.amplitude |
RFC-103, RFC-112: f32, mm: the PEAK displacement from the planned position (the swing is twice it), 0 .. the field's catalog max, which it MUST declare: the hub's amplitude ceiling, chosen from what its input ceilings let a sine render (§9.7). Static: no window, travel or flip change rescales or rewrites it. What the ceilings and the window leave of it is osc.amplitude_effective. Driven by osc.amplitude.drive. |
osc.dwell_crest |
RFC-103: f32, two decimals, 0 = no hold: the share of the moving cycle (1 / frequency) held at the crest, added to it as RFC-095's dwells add to a stroke, so the period becomes (1 + dwell_crest + dwell_trough) / frequency and the moving halves keep their speed. A dwelled sine renders its halves as rest-to-rest quintics. |
osc.dwell_trough |
RFC-103: f32, two decimals, 0 = no hold: the share of the moving cycle held at the trough, as osc.dwell_crest. A dwelled sine is the oscillator's one square-ness (RFC-112). |
osc.frequency.drive |
RFC-103: select over osc_drives: what sets osc.frequency. fixed = the field's own value (the bounds unused); speed, position = the planned motion the oscillator rides; axis = the osc.drive stream's frequency field. The other three map the drive's input through osc.frequency.in_min/in_max/out_min/out_max as §8.11's linear_clamp, the output clamped into 0 .. osc_max_hz. |
osc.frequency.in_min |
RFC-103: f32, the drive's input at which osc.frequency reads out_min (the drive's own unit: telemetry.velocity's for speed, telemetry.target's for position, 0 .. 1 for axis) |
osc.frequency.in_max |
RFC-103: f32, the drive's input at which osc.frequency reads out_max; in_min != in_max |
osc.frequency.out_min |
RFC-103: f32, Hz, the frequency at in_min |
osc.frequency.out_max |
RFC-103: f32, Hz, the frequency at in_max |
osc.amplitude.drive |
RFC-103, RFC-112: select over osc_drives: what sets osc.amplitude, as osc.frequency.drive; axis = the osc.drive stream's amplitude field; the output clamped into 0 .. osc.amplitude's catalog max, mm. |
osc.amplitude.in_min |
RFC-103: f32, the drive's input at which osc.amplitude reads out_min (the drive's own unit, as osc.frequency.in_min) |
osc.amplitude.in_max |
RFC-103: f32, the drive's input at which osc.amplitude reads out_max; in_min != in_max |
osc.amplitude.out_min |
RFC-103, RFC-112: f32, mm, in osc.amplitude's range (the same min and max), the amplitude at in_min |
osc.amplitude.out_max |
RFC-103, RFC-112: f32, mm, in osc.amplitude's range (the same min and max), the amplitude at in_max |
osc.active |
RFC-103: STATE bool: the oscillator is enabled and rendering a nonzero amplitude this instant. False under PAUSE and ESTOP. |
osc.amplitude_effective |
RFC-103, RFC-112: STATE f32, mm: the peak the ceilings and the window left after shaping (the oscillator yields first), 0 while inactive. Where shaping cut it, plan.flags bit2 clamped (RFC-100) is set. |
store.slot |
RFC-089 (§8.7): uint, the item's slot in the writer's store. Required by load, delete and rename; optional on save (absent, the hub picks a free slot and ECHO applied carries it; no free slot is INVALID_VALUE with a detail naming the store full). Binds within the entry carrying the action.store op select. |
store.name |
RFC-089 (§8.7): text, the item's name, fitting the store's name_max. Required by save and rename. Binds within the entry carrying the action.store op select. |
store.item |
RFC-089 (§8.7): byte string carrying one whole store-item document (the blob_keys map: slot, name, kind, payload, optional digest), never the bare payload. Optional on save (absent, the hub captures live state; a store with no live state to capture requires it). Its slot and name MUST equal store.slot and store.name, else INVALID_VALUE. One frame: an item past the binding's max_frame is FRAME_TOO_LARGE. Binds within the entry carrying the action.store op select. |
color.red |
RFC-083: writable numeric red channel of one color group; color.red/green/blue together trigger the color archetype (all three essential) |
color.green |
RFC-083: writable numeric green channel of one color group |
color.blue |
RFC-083: writable numeric blue channel of one color group |
datetime.moment |
RFC-083: a scheduled moment in HUB TIME: whole seconds in the hub's §7.1 timebase (unit_ids hub_s), never Unix epoch. Valid for the current boot_id; a client re-arms after a hub reboot. Triggers the datetime archetype. |
datetime.start |
RFC-083: interval start, hub time seconds (as datetime.moment); with datetime.end in one group triggers the datetime archetype |
datetime.end |
RFC-083: interval end, hub time seconds (as datetime.moment) |
source.background_run |
bool, setting_key-annotated: whether THIS autonomous source keeps running when its owning session ends. false (DEFAULT) = the source stops when its controlling session ends. true = the source deliberately continues in the background, reachable only by the role-exempt pause/estop ops (§11.1, §11.2) from any session. Applies to any hub-autonomous source, never to a command-driven one. |
Two conventions extend the list without registering entries:
<role>.peakis the peak companion of any telemetry role.action.<name>marks an INTENT field as a verb, not a value.
Channel roles#
A channel role is the entry-level role (catalog entry key 18). It
names the purpose of a whole channel, where a field role names one
field. The same doctrine applies: unknown roles render generically.
| Role | Meaning |
|---|---|
events.anomaly |
EVENT entry: edges reporting the machine did something other than what it was asked (a clamped command, a trimmed knot, a piece over a ceiling, a refused knot). A client giving anomalies a dedicated surface MUST bind by this role or core identity, never by name. |
anomaly.summary |
STATE entry: the latched counters twin of an events.anomaly channel (§9.4 duality rule), so the event log and its counters bind together. |
osc.drive |
RFC-103, RFC-112: c2h samples-kind STREAM entry, the external axis driving the oscillator. The role fixes the layout: amplitude (f32, 0 .. 1, a norm, never a length) then frequency (f32, 0 .. 1), each mapped through its parameter's own bounds where that parameter's drive is axis. Carries no input.target, so it is never motion input and never owns the rail. Quiet for stream_quiet_release_ms, an axis-driven parameter reads 0. The reference hub names its entry osc-drive. |
Setting flags#
| Mask | Bit | Name | Notes |
|---|---|---|---|
0x01 |
bit 0 |
advanced |
hide behind an 'advanced' affordance by default; NEVER remove from the surface |
0x02 |
bit 1 |
restart_required |
the applied value takes effect on the next boot (distinct from RFC-020's reboot_in_ms, which is the hub rebooting ITSELF to commit) |
0x04 |
bit 2 |
secret |
NORMATIVE (RFC-009.5): the value NEVER appears in STATE. The snapshot carries only a set/unset presence bit. Writes ride the paired INTENT normally and ECHO confirms application WITHOUT echoing the value: the applied key carries the CBOR value true in its place (RFC-069), and a client MUST accept true for a secret key whatever the field's type. A WiFi password must never ride a retained snapshot that open-access watch sessions receive. |
0x08 |
bit 3 |
destructive |
RFC-063: on a schema field with an action.* role, invoking the verb loses state the operator cannot restore from the client (configuration, stored items, counters, sessions, uptime); on a writable layout field, writing it has that effect. Rendering metadata only: a client MUST confirm-gate (RENDERING.md §8.4 trigger), a hub MUST NOT change wire behavior on it. Per-option form: schema-field destructive_options (SPEC §8.8). |
Plan flags#
The bits of the plan.flags field role (SPEC §8.8): how the planner
bent a segment in flight. Any of bits 0 to 3 means infeasible.
| Mask | Bit | Name | Notes |
|---|---|---|---|
0x01 |
bit 0 |
shaped |
the planner trimmed a knot toward the previous one to fit the ceilings (amplitude gives, time never) |
0x02 |
bit 1 |
stretched |
the knot lands after its commanded time: a jog's fastest move, or the newest knot finishing late |
0x04 |
bit 2 |
clamped |
a ceiling or the travel window changed the command |
Procedure phases#
Only the lifecycle phases are registered. Any generic client can render
these without knowing the procedure. Values 128 to 255 are device-defined
intermediate steps. A client that does not recognize one renders it as
running.
| Value | Phase | Notes |
|---|---|---|
0 |
idle |
not running; the reconnect-safe resting value |
1 |
running |
started and in progress; progress 0-100 is advisory |
2 |
succeeded |
terminal, ok. Also EVENTed (RFC-020). |
3 |
failed |
terminal, error: result u16 carries a nack_codes value or a device code |
4 |
aborted |
terminal, canceled or superseded |
Curve families#
The curve_family sub-key is CBOR key 45, inside a publishes or granted_publishes entry. It names which smoothness class a segment stream's sender means. The wish rides on HELLO or PUBLISH. The grant echoes the effective family, so a client can tell honored from downgraded.
| Value | Family | Notes |
|---|---|---|
0 |
unspecified |
RETIRED pre-tag by RFC-106: no declaration. Never emitted, never reused. |
1 |
g1 |
RETIRED pre-tag by RFC-106: a velocity-continuous sender. Never emitted, never reused. |
2 |
g2 |
RETIRED pre-tag by RFC-106: an acceleration-continuous sender. Never emitted, never reused. |
3 |
step |
RETIRED pre-tag by RFC-106: a held value with instantaneous transitions. Never emitted, never reused. |
Oscillator shapes#
Retired pre-tag by RFC-112 with the osc.shape role that selected them: the oscillator renders a sine only (SPEC §9.7). The numbers are never reissued.
| Value | Shape | Notes |
|---|---|---|
0 |
sine |
RETIRED pre-tag by RFC-112: the select is gone; the sine is the oscillator's only waveform. Never emitted, never reused. |
1 |
square |
RETIRED pre-tag by RFC-112: a dwelled sine is the one square-ness. Never emitted, never reused. |
2 |
saw |
RETIRED pre-tag by RFC-112. Never emitted, never reused. |
3 |
saw_reverse |
RETIRED pre-tag by RFC-112. Never emitted, never reused. |
Oscillator drives#
The osc.frequency.drive and osc.amplitude.drive selects (RFC-103, SPEC §9.7): what sets the parameter. A driven parameter maps its source through linear_clamp (SPEC §8.11) with the entry's in_min/in_max/out_min/out_max fields.
| Value | Drive | Notes |
|---|---|---|
0 |
fixed |
the parameter is its own field's value; the bounds are unused |
1 |
speed |
the magnitude of the commanded speed the oscillator rides, in the unit of the hub's telemetry.velocity field |
2 |
position |
the commanded position the oscillator rides, in the unit of the hub's telemetry.target field |
3 |
axis |
the osc.drive stream's field of the same name (amplitude or frequency), 0 .. 1; 0 once the stream has been quiet for stream_quiet_release_ms |