OpenValence Download

Valence

The protocol for motion machines. The machine describes its own controls, and any app can draw them.

Spec v1.0-draft.

Compared to the web

On the web, a server sends a page and any browser can draw it. Valence works the same way for a machine.

On the webIn Valence
Website
The machineIts firmware runs a hub that holds the machine's state.
Browser
The appPhosphor, a script, a plugin or a hardware remote. Any number can connect at once and stay in sync.
HTTP and HTML
ValenceThe wire format, plus the catalog the machine sends to describe itself.
Server-side checks
Machine-side limitsThe machine checks every request, whatever the app thinks.
One catalog entry drawn as three different controls. The desktop is Phosphor; the phone and the remote are sketches of what any app could draw. The machine holds the value and tells every app what it is.

The catalog

A Valence machine sends a catalog: what each setting is, its unit, its range and who may change it. It sends no layout, colors or widget hints.

name jog_speed
desc Speed ceiling for manual jogs
unit mm/s
range 1 to 2000
default 50
group Jog limits
Jog limits
Speed ceiling for manual jogs50 mm/s
12000
Left: one setting as Nucleus declares it. Right: one way an app can draw it. Another app could draw a knob or a number box from the same entry.

A setting added in the firmware shows up in every app the next time it connects, with no app update.

Safety

The machine checks every request, because any client can be wrong: an old version, a buggy plugin or a script with a bad number in it.

Access tiers

The pairing diagram shows how you get each one.

What's in the repo

  • The spec

    The protocol, in one document, plus the registry that assigns every wire number. CC BY 4.0.

  • The library

    A C++20 reference implementation. Header-only, no hardware, no dependencies. MIT.

  • Clients

    A JavaScript client and Valence Connect, a plugin for MultiFunPlayer.

  • Valence Bench

    A reference hub that runs with no hardware, for testing a client.

  • Tools

    A wire-level conformance probe, a tracer, a soak tester.

Status: pre-release. The spec is v1.0-draft and changes through RFCs. Wire numbers are not frozen yet. The name "Valence" is reserved for implementations that pass conformance.

Developer docs

Repo · Docs · Diagrams · All components