Skip to content

Quickstart#

This page builds one connected client that reads live machine state and sends one intent.

Develop against Nucleus's neutrino-sim. It embeds that device's hub, motion engine and catalog behind the same wire protocol.

neutrino-sim machine --homed --headless --duration 120

Session sequence#

A Valence client performs these steps in this order.

sequenceDiagram
    autonumber
    participant C as Client
    participant H as Hub
    C->>H: connect (subprotocol valence.v1)
    C->>H: HELLO
    H->>C: WELCOME (session id, catalog etag, limits, deadman)
    Note over C: fetch the catalog, or reuse the one cached under that etag
    C->>H: CATALOG_READY (the etag you decode against)
    C->>H: SUBSCRIBE
    H->>C: GRANT + retained STATE
    C->>H: INTENT
    H->>C: ECHO (applied, post-clamp)

Steps 1 to 3 identify both parties. Step 4 is the ready gate. Steps 5 to 7 are the working session.

Python#

The probe is import-safe: everything with a side effect lives under its main(). The example imports it as the wire library and writes only the session.

import os, sys, time, websocket

sys.path.insert(0, "tools")            # the probe is import-safe: use it as the wire library
import valence_probe as ss

ws = websocket.create_connection("ws://127.0.0.1:82/",
                                 subprotocols=[ss.WS_SUBPROTOCOL], timeout=5)


def wait_for(*types, timeout=5.0):
    """Return the next frame of any of `types`."""
    deadline = time.time() + timeout
    while time.time() < deadline:
        got = ss.recv_frame(ws, deadline)
        if got is None:
            break
        hdr, payload = got
        if hdr["type"] in types:
            return hdr, payload
    raise TimeoutError("no %s within %.1fs" % (types, timeout))


# 1. HELLO -> WELCOME
ss.send_frame(ws, ss.FRAME["HELLO"], 0,
              ss.build_hello("demo", "quickstart.py", os.urandom(8)))
_, payload = wait_for(ss.FRAME["WELCOME"])
w = ss.cb_decode_full(payload)
etag = w[ss.K["catalog_etag"]]
print("WELCOME  session=%d  etag=%s  deadman=%dms"
      % (w[ss.K["session_id"]], etag.hex(), w[ss.K["deadman_ms"]]))

# 2. CATALOG_READY: declare the catalog you decode against. The hub sends no STATE and refuses intents until this frame.
ss.send_frame(ws, ss.FRAME["CATALOG_READY"], 0, etag)
print("CATALOG_READY sent")

# 3. SUBSCRIBE: safety on-change, motion at 20 Hz
ss.send_frame(ws, ss.FRAME["SUBSCRIBE"], 0, ss.build_subscribe([
    (ss.CH_SAFETY, 0.0, ss.PRIORITY["critical"]),
    (ss.CH_MOTION, 20.0, ss.PRIORITY["elevated"]),
]))

# 4. Retained STATE arrives immediately: adopt it; do not assume a default.
hdr, payload = wait_for(ss.FRAME["STATE"])
while hdr["channel"] != ss.CH_MOTION:
    hdr, payload = wait_for(ss.FRAME["STATE"])
pos = ss.decode_motion_state(payload)["pos_mm"]
print("STATE    motion pos=%.2fmm" % pos)

# 5. One INTENT, then read the post-clamp ECHO the hub applied.
target = pos + 5.0
ss.send_frame(ws, ss.FRAME["INTENT"], ss.CH_MOVE_INTENT,
              ss.build_intent(ss.CH_MOVE_INTENT, 1,
                              [(1, ss.cb_f32(target)), (2, ss.cb_bool(False))]))
kind, payload = wait_for(ss.FRAME["ECHO"], ss.FRAME["NACK"])
body = ss.cb_decode_full(payload)
if kind["type"] == ss.FRAME["ECHO"]:
    print("ECHO     asked %.2fmm -> applied %s" % (target, body.get(ss.K["applied"])))
else:
    print("NACK     %s" % ss.nack_name(body.get(ss.K["code"])))

ss.send_frame(ws, ss.FRAME["GOODBYE"], 0, ss.build_goodbye(0))
ws.close()

Run it from the repository root, against a simulator that is already up:

WELCOME  session=3497637577  etag=0458eec408a43692  deadman=600ms
CATALOG_READY sent
STATE    motion pos=0.00mm
ECHO     asked 5.00mm -> applied {1: 5.0, 2: False}

5.0 is what the hub applied, after its own clamp. Render the applied value, not the value you sent.

DEMO-CANDIDATE: run this exact script live against an in-browser simulator, and highlight each line of output as its frame arrives.

JavaScript#

clients/js/ is the browser client, and it is a v1.0 reference implementation. It performs the handshake, including the ready gate, and emits events.

import { createSession, CH, PRIORITY } from './clients/js/index.js';

const s = createSession({
  host: location.hostname,
  clientKind: 'webui',
  clientName: 'My Valence Client',
  subscriptions: [                     // [channelId, rateHz, priority]
    [CH.SAFETY, 0, PRIORITY.critical],     // on-change, never shed
    [CH.MOTION, 20, PRIORITY.elevated],    // live carriage feed
    [CH.HUB_STATUS, 1, PRIORITY.background],
  ],
});

s.on('welcome', (w) => { /* w.sessionId, w.roles, w.deadmanMs, w.cfgGen */ });
s.on('catalog', (entries) => { /* build UI from the catalog, not from constants */ });
s.on('state', (channelId, sample) => {
  if (channelId === CH.MOTION) render(sample.pos_10um, sample.tgt_10um, sample.flags_bits);
});
s.on('nack', (n) => console.warn('NACK', n.name, n.detail));
s.connect();

Field names come from the catalog verbatim, already scaled to millimeters. Write calls resolve with the applied value:

const { applied } = await s.sendConfigSet({ 1: windowMinMm, 2: windowMaxMm });
// applied[1] / applied[2] are the DEVICE's clamped values; render those.
await s.sendMove(targetMm);

Motion input is a c2h STREAM that the client publishes, not an intent: find the channel in the catalog, ask the hub for a grant, then send samples keyed by the layout's own field names. Every refusal (not granted, over the granted rate, a malformed bundle, a segment scheduled too far ahead) throws a PublishError with a PUBLISH_ERROR code; the client raises an error for every refused sample.

import { CHANNEL_CLASS, STREAM_KIND } from './clients/js/index.js';

const input = s.catalog.find((e) => e.cls === CHANNEL_CLASS.STREAM &&
  e.dirName === 'c2h' && e.streamKind === STREAM_KIND.samples);
await s.publish([[input.id, 50]]);          // [channelId, rateHz, burst?, curveFamily?]
s.publishSamples(input.id, { target_norm: 0.5, vel_norm: 0 });  // stamped hub-now
s.publishSegment(segmentChannelId,           // a segments-kind channel
  { target_norm: 0.8, duration_ms: 120, end_vel_norm: 0 },
  { anchor: s.hubNowUs() + 60000 });         // execution start, in hub time

Test your build against a hub by running the full read-only session twice back to back. This is the mandatory pattern for anything touching session lifecycle. clients/js/test/valence-wire.test.mjs in this repo proves the wire codec byte-for-byte. For a live check, run tools/valence_probe.py twice against the same hub.

The ready gate#

Send CATALOG_READY before anything else

The hub gates both planes until your session declares which catalog it operates against. Before that declaration you get no STATE, no stream, and every intent is refused NOT_READY.

Output of the same script with the CATALOG_READY line removed:

WELCOME  session=2929602731  etag=0458eec408a43692  deadman=600ms
CATALOG_READY deliberately NOT sent
STATE    nothing arrived in 2.0s
NACK     NOT_READY

Connect and subscribe succeed without error, no STATE arrives, and the intent is refused NOT_READY.

The gate is a safety rule. A client that has not adopted the retained safety latch must not act, and the hub enforces this by gating the control plane on the same declaration.

What to declare. Send the etag of the catalog you decode against.

  • If you fetched the catalog, verify its bytes hash to the etag WELCOME advertised, then declare that etag.
  • If you already had that etag cached, skip the fetch and declare it.
  • If you hardcode layouts, like the probe does, declare the hub's etag only because it matches what you compiled against. The hub cannot detect a false declaration.

Client rules#

Adopt retained STATE. Retained STATE arrives on grant. Do not render defaults before it arrives.

Render the echo. The ECHO carries applied, post-clamp values. See ground truth.

Send PING. Liveness is silence-based, and it is measured on what you send. Received frames do not count, so a subscriber that only receives counts as silent. Send PING on your own clock, well inside the advertised deadman_ms.

Treat a NACK as a normal response. NOT_HOMED on an unhomed machine is expected behavior. Show it; do not retry it in a loop.

Where to go next#