Provisioner Workspace

Provisioner Workspace is the device-control workflow for commissioning OSDP peripheral devices (PDs) in the field. It takes the user from device connection, through either a live one-at-a-time quick-step queue or an offline slot-backed batch plan, into per-PD execution with live progress, outcome tracking, and a final SCBK export.

Workspace story ​

Provisioner Workspace is easiest to understand as a three-stage flow:

1. connect provisioner-capable hardware
2. choose a working mode and build or load a provisioning plan
3. drive each PD through address, baud, and secure-channel keying, then export the derived keys

That flow matters because the workspace is not only a form editor. It owns both the persistent slot state on the device and the live execution that programs real PDs on the bus.

What this workspace owns ​

Provisioner Workspace owns provisioner-session UX only:

• selecting and connecting provisioner-capable hardware
• choosing between live quick-step and offline slot-backed modes
• building, importing, viewing, and deleting slot-backed provisioning profiles
• driving per-step execution (try, retry, skip, reset)
• showing live per-PD progress, outcomes, and stage milestones
• deriving and exporting per-PD SCBKs from the operator secret after a slot completes

USB transport ownership, cross-tab exclusivity, and session binding remain outside the workspace in shared managers, exactly as in the other workspaces.

Stage 1: Connect hardware ​

Device setup ​

1. Open a Provisioner tab.
2. If the device is not listed, open the Pair Device dialog from the pair link in the empty-device hint and pair it (browser build only — the desktop build auto-discovers).
3. Click a provisioner-capable device card to connect to it.

If you are using Osprio Mini hardware, make sure the device is running an app that exposes the provisioner role. Provisioning is a field-commissioning workflow, so it is most at home on Osprio Pro's battery-backed hardware.

What happens after connect ​

After the device is connected, the workspace reads the provisioner status from the device. That status reports which execution modes the firmware supports:

• if the device supports only live quick-step execution, the workspace opens directly on the quick-step queue
• if the device supports only offline slot-backed execution, the workspace opens on the slot list
• if the device supports both, the workspace shows a mode picker first

The device — not the host — is the source of truth for which modes are available.

Stage 2: Choose a mode and build a plan ​

Live mode (quick-step queue) ​

Live mode provisions PDs one at a time, interactively. Each quick-step targets a single OSDP address; the workspace sets the address and baud rate and, when the PD is in install mode, keys the SCBK, then streams the outcome back as the attempt finishes. There is no persistent slot — the queue mirrors the live progress stream so each PD row renders the same shape as a batch row.

Use live mode for benched, staged, or one-off commissioning where you want immediate per-device feedback.

Offline mode (slot-backed batch) ​

Offline mode writes a whole provisioning plan into a device slot. The device persists a small number of slots; each slot is an independently executable work queue with one step per target PD (up to 126 steps per slot).

On hardware that advertises offline autonomous execution, the device can keep working through a sealed slot while no host is connected, buffering each progress edge per slot and streaming the buffered edges back when you reconnect. That makes offline mode suitable for "set it running and walk the site" deployments, not just attended ones.

The slot list lets you:

• create a new profile in an empty slot
• import a profile from JSON into a slot
• open an existing slot to view its progress
• delete a slot (legal in any state; returns the slot to empty)

Each slot summary carries its progress counters (total, provisioned, failed, skipped) so the slot list refreshes in a single round-trip.

Profile configuration ​

Creating a profile opens the configuration form. The top-level profile fields are:

• profile name
• device count — how many PDs this plan provisions (up to 126)
• address strategy — sequential, random, or manual
• start address — used by the sequential and random strategies
• manual address list — used by the manual strategy
• baud rate — the bus baud used when driving targets for this slot
• expected capabilities — an optional post-programming verifier; leave empty to skip the capability check
• provisioning timeout — the per-step timeout; 0 uses the firmware default
• auto-verify — when enabled, the device re-reads each target after programming to confirm the address, baud, and key landed
• set SCBK (secure channel) — on by default; when off, the device only sets each PD's address and baud and every step finishes at the verify stage, with no SCBK derived or exported

Steps review ​

After configuration, the workspace expands the profile into a per-PD step list and shows it for review before anything is written to the device. Each row is one target PD with its assigned address and baud. Confirming the review writes the plan to the selected slot, which seals it for execution. For a slot that provisions secure channel, sealing it prompts you for an operator secret (see Key material custody below).

Stage 3: Drive execution and export ​

Once a slot is sealed (or once a live quick-step queue is running), the layout changes from planning to operational control.

What a provisioning step does ​

Each step drives one PD through a fixed pipeline of up to seven stages, shown live on the per-PD stage strip:

1. Baud Scan — discover the device by polling each supported baud rate
2. COMSET — set the target address and baud rate
3. Verify — confirm the device responds at its new address and baud
4. Install SC — bring up the OSDP secure channel using SCBK-D (install mode)
5. Keyset Deact — push the new SCBK via KEYSET, then tear the channel down
6. Final SC — re-open the secure channel using the freshly-set SCBK
7. Soak — hold the link briefly to confirm the device is stable

A step that opts out of secure channel (the set SCBK profile field) stops after Verify. For secure-channel steps, two properties matter on a production bus:

• The new key is proven. A step only reports success after Final SC re-opens the channel with the just-set SCBK — a handshake that can succeed only if the key landed correctly — so a key failure surfaces as a secure-channel outcome rather than a false success.
• Install mode is closed. Setting the key takes the PD out of install mode, so it is handed to the production bus already locked into secure operation rather than left open for anything on RS-485 to re-key.

Per-PD progress ​

Each PD appears as a row with:

• its OSDP address and baud rate
• a step state: pending, attempting, success, failure, or skipped
• an attempt count
• the last outcome (see below)
• a stage milestone indicator showing which provisioning stage was last attempted, is in flight, or has stalled

success and skipped are terminal. failure is intentionally not terminal — retries are unbounded and user-initiated; the device never auto-retries a failed step on its own.

Step actions ​

For each row the operator drives execution with four verbs:

• try — attempt a pending step
• retry — re-attempt a failed step (bumps the attempt count)
• skip — mark a step skipped (it will not be attempted)
• reset — return a step to pending with the attempt count cleared (an escape hatch, always legal)

Terminal outcomes always arrive as a live progress edge after the verb is accepted, so the row reflects what actually happened on the bus rather than just what was requested.

Step outcomes ​

When an attempt ends, the row records why:

• ok — the attempt succeeded
• no_response — the target did not reply at the expected address
• wrong_address — a target replied, but at a different address than expected
• comset_failed — the COMSET address/baud change did not take
• scbk_rejected — the target already holds a different SCBK; address and baud may still have been applied (the detail note says which)
• baud_mismatch — the target responded at a different baud than the profile specified
• install_sc_failed — the install-mode secure channel (SCBK-D) could not be established
• keyset_failed — the KEYSET exchange that sets the new SCBK failed
• final_sc_failed — the secure channel could not be re-opened with the freshly-set SCBK
• soak_failed — the post-keying stability hold failed
• user_skipped — the step was skipped by the operator

Slot lifecycle ​

A slot moves through empty → staging → ready → complete:

• empty — no profile written
• staging — a create is in progress (steps are being uploaded)
• ready — sealed and executable; at least one step is still non-terminal
• complete — every step has reached a terminal state

The workspace surfaces a refresh control and a delete control alongside the progress view. There is no slot-level start/stop — the slot itself is the schedule, and the per-step verbs are the only runtime controls.

Key material custody ​

Provisioner Workspace never uploads per-PD SCBKs to the device, and for slot-backed (offline) plans it never transmits the key seed either. Understanding the custody model explains why the SCBKs behave the way they do — and why you are asked for an operator secret.

Operator secret ​

When an offline slot provisions secure channel, its per-PD keys are anchored to an operator secret you supply before the slot is sealed. You can either:

• generate a high-entropy recovery key — a checksummed Crockford-base32 string in hyphenated groups, designed to be written on paper and re-typed loosely (case-, hyphen-, and misread-insensitive). This is the recommended option.
• type your own passphrase — convenient, but offline-brute-forceable from the public key on the wire, so prefer a strong one.

The operator secret is held only in RAM and is never written to disk, browser storage, or any export artifact.

How the slot key seed is established ​

Slot keys use an ephemeral X25519 key agreement, so the 16-byte key seed that derives each SCBK is never sent over the wire:

• the host derives a private key from the operator secret (scrypt, salted by the slot's session id) and sends only the matching public key to the device at slot creation
• the device contributes its own public key; both sides compute the same shared secret and derive the identical key seed from it (HKDF-SHA256)
• each step's SCBK is derived from that key seed on demand, in memory only, on both the device and the host

Because the seed comes from the operator secret combined with the device's public key, the device and the operator secret together are the holders of record — neither alone can reproduce a key. On reconnect or restart, the workspace re-fetches the device's public key and a key-confirmation tag, then re-derives the keys from the re-entered secret; if the wrong secret is entered, the confirmation tag fails to match and no keys are produced.

Live quick-step provisioning has no seed concept: each quick step carries its SCBK directly rather than deriving it from an operator secret.

Exporting the provisioned keys ​

Derived per-PD SCBKs legitimately leave the app exactly once: a post-completion export, available after a slot reaches complete. It carries one entry per successfully provisioned PD — its OSDP address, baud rate, and derived SCBK — for the operator to load into downstream key-management or access-control tooling. Failed and skipped steps are omitted, and the key seed itself never appears in any exported file.

Because the keys are not stored, the export re-derives them on the spot: it prompts for the operator secret again and verifies it against the device's key-confirmation tag before producing anything, so a wrong secret is rejected rather than exported as garbage.

The same key set can be exported in more than one format so it drops cleanly into whatever consumes it next:

• CSV — a flat table with a pd_address,baudrate,scbk header and one row per provisioned PD. Best for spreadsheets, scripts, and bulk import into a head-end or key vault.
• JSON — a structured document (kind: "osprio-provisioned-scbks", a file version (1), the slot's session_id, and an scbks array of { pdAddress, baudrate, scbkHex }). Best for programmatic ingestion where the session identity and a stable schema matter.

Both formats describe the same provisioned devices; pick the one your downstream tooling reads most easily. Treat either artifact as sensitive key material once it leaves the app.

Session lifecycle and close behavior ​

A provisioner session can be closed freely — unlike a live capture or a running emulation, the workspace does not hold a long-lived "running" state that must be torn down on close, because the slot on the device is the schedule and persists independently.

If hardware disconnects mid-session, the workspace returns to the device-pairing step rather than silently destroying the tab. Because the device persists slot state and progress, reconnecting and reopening the slot restores the full picture — including any progress the device made autonomously while disconnected, which arrives as backfilled edges on reattach.