Documentation

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 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. Click PAIR NEW if the device has not been authorized yet.
  3. Select a provisioner-capable device from the list.
  4. Click Connect.

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

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.

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 the full commissioning sequence: set its address and baud (COMSET) and confirm the change took, then open a controlled install-mode session, derive and set the SCBK (KEYSET), and finish with two guarantees that matter on a production bus:

  • The new key is verified. After keyset, the workspace completes a fresh secure-channel handshake using the just-set SCBK. That handshake can only succeed if the key landed correctly, so a step only reports success once the key is proven to work — a failure here surfaces as a secure-channel outcome rather than a false success.
  • Install mode is disabled. Setting the key takes the PD out of install mode, so it stops accepting unauthenticated key writes. The device is handed to the production bus already locked into secure operation, not left open for anything listening 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
  • 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
  • keyset_failed — the secure-channel KEYSET exchange failed for another reason
  • user_skipped — the step was skipped by the operator
  • plus internal/secure-channel error outcomes surfaced verbatim from the device for diagnosis

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 treats the slot key material carefully, and it is worth understanding why the SCBKs behave the way they do.

Per-PD SCBKs are not uploaded to the device. Each slot carries a single 16-byte seed, generated on the host with a CSPRNG and sent to the device once, at slot creation. The device derives each step's SCBK on demand from that seed; the host runs the identical derivation locally so it always knows which key landed on which PD.

The custody rules the workspace follows:

  • the host drops its in-memory reference to the seed as soon as the slot is sealed — the device is the authoritative holder
  • the seed is never written to disk, browser storage, or any export artifact
  • on reconnect or restart, the workspace re-fetches slot state (including the seed) from the device
  • derived per-PD SCBKs exist in memory only for as long as they are needed for display or export

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 slot seed itself never appears in any exported file.

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, 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.