Skip to content

stub

Hub implementer guide#

This page is not written yet

This page is a stub. It lists the intended content and the source material.

Content follows the v1.0 tag.

What belongs on this page#

What a firmware author needs to adopt Valence, and how much work each part takes.

  • Author your catalog. Catalog authoring is the largest part of the work. Cover the 242-byte snapshot budget, the per-entry size cap, and splitting a state group across channels when it does not fit.
  • Wire the delegate. Apply intents through your existing arbitration and safety gates. Do not bypass them. The protocol passes intents to your existing motion authority and does not replace it.
  • Echo applied values. Echo the post-clamp values read back from the driver, not the requested values.
  • Retain and seed. Keep the latest snapshot of every STATE channel, and seed the safety snapshot at construction. A fresh boot that retained nothing hands a connecting client an empty latch.
  • One teardown path. Every way a session can end runs the same loss policy.
  • Implement a transport by writing an adapter, outside the library.

Known traps#

The page will cover these failure modes:

  • Do not implement reset() as whole-object assignment: it builds a nine-kilobyte stack temporary and overflows the task stack on every client connect. Host tests do not catch it because host thread stacks are megabytes in size.
  • Do not place a large service in static memory: it starves the internal heap and leaves the network stack without memory, and the linker report does not show it.
  • Do not release ownership only from the liveness pump: every other exit path leaks ownership. The leak stays hidden while each deploy reboots the device between tests.

Source material#

  • spec/SPEC.md ยง13.1: the binding contract every transport must satisfy.
  • lib/valence/README.md: how to vendor the library, and the layering rules.
  • hub/bench/ (this repo): a working, machine-agnostic composition root and WebSocket transport adapter, config-file-driven rather than wired to real hardware.
  • Nucleus's src/comms/ValenceHubService.* and ValenceWsTransport.* (machine repo): a working composition root and transport adapter wired to real hardware.

Where to go next#

  • CLI guide: verify a hub with the probe and Valence Trace.
  • Local testing: the simulator, the golden vectors, and the back-to-back-sessions pattern that finds teardown bugs.