Thread Commissioning Workbench

Trace how a Thread Joiner is authorized, authenticated, provisioned, and attached without exposing its joining credential over the air

animation
thread
commissioning
meshcop
dtls
security
matter
Learner-ready Thread commissioning workbench with Play/Step flow, Joiner Router relay visualization, PSKd guardrails, failure scenarios, quick reference, guided practice, and primary Thread/OpenThread source links.
Thread MeshCoP DTLS PSKd

Thread commissioning, from QR code to attached device

Follow the secure onboarding path for a new Thread Joiner. The workbench shows which role speaks, when the Joiner Router only relays traffic, why the device passphrase is not the network key, and where common IoT commissioning failures occur.

Current phase Open join window
Security state Joiner authorized
Join decision Proceed
Visual workbench

Commissioning message path

The Commissioner opens a time-limited join window for one expected device.

Specific EUI-64 120 s window PSKd ready
Thread commissioning roles and message token Commissioner, Joiner Router, Joiner, and Thread Network lanes with an animated token showing the active commissioning message. PSKd-authenticated DTLS channel The Joiner Credential is used to authenticate; it is not sent as plaintext. C Commissioner App or Thread device JR Joiner Router Existing Thread router J Joiner Factory-new device NET Thread network Operational dataset protected Attach after commissioning Security checkpoint PSKd is derived from the Joiner Credential plus Thread network identity inputs. The device passphrase authorizes commissioning; it is not the network-wide key. OPEN
1 Authorize Commissioner starts and adds a joiner entry.
2 Discover Joiner scans and matches steering data.
3 Relay Joiner Router forwards MeshCoP traffic.
4 Authenticate DTLS is authenticated with PSKd.
5 Provision Operational dataset is delivered securely.
6 Attach MLE attach makes the Joiner a network child.
Outcome Ready to commission

The Joiner is authorized for a short window. Start the Joiner before the entry times out.

Security evidence Credential stays out of the air

The Joiner Credential and PSKd authenticate the DTLS exchange; learners should not model them as plaintext packet payloads.

IoT caveat Field setup is operational work

A strong protocol still depends on short windows, unique device credentials, logs, and a recovery path for failed joins.

Beginner ramp

What the learner should know first

Thread commissioning is an authorization and credential-provisioning workflow, not just a radio association.

Three roles, different jobs

The Commissioner approves the join. The Joiner Router relays traffic from the not-yet-attached device. The Joiner is the factory-new device being added.

PSKd is not the network key

The Joiner Credential helps derive PSKd for device authentication. It should be unique per device and should not be reused as a fleet password.

Attach happens after commissioning

After the secure commissioning exchange, the device starts normal Thread operation and attaches with MLE as a child or router-capable device.

Quick reference

Commissioning checks

Credential rule

PSKd = derived(joiner credential, network name, extended PAN ID). The credential is used for authentication, not sent as the Thread network key.

Join window

Short windows reduce the time an unauthorized device can try. Long windows are convenient but increase operational exposure.

Steering data

Discovery responses indicate whether a Joiner should try this network. Wildcard steering is acceptable for a lab, not a safe deployment default.

Operational dataset

The Joiner ultimately needs channel, PAN identity, network name, network key, and related parameters before it can attach normally.

Guided practice

Try these commissioning decisions

Factory QR setup

Select QR single device, step to DTLS, and identify which evidence proves the Joiner knew the expected credential without sending it in plaintext.

Lab shortcut risk

Select Wildcard lab. Keep the flow successful, but explain why a wildcard and a short shared credential should not ship in a production installer.

Support ticket triage

Select Wrong credential or Window expired. Use the active message, outcome card, and badge state to decide what the installer should check first.

Deeper material

Details that prevent common misconceptions

Commissioner, Joiner Router, and Leader are easy to mix up

A Commissioner is the authority that accepts or rejects a Joiner. A Joiner Router is an existing Thread router that relays packets for a Joiner that is not yet attached. The Leader manages Thread network data. In real products these functions may run on different devices, so this workbench labels the function being performed rather than implying one fixed box always owns every secret.

What "secure credential delivery" means in this teaching model

The Joiner starts with an out-of-band Joiner Credential, often printed in a QR code or label. That credential is used to derive PSKd for commissioning authentication. The operational dataset is then delivered through a protected commissioning path. The important learner takeaway is that sniffing the commissioning exchange should not reveal a reusable plaintext password or raw network key.

Why MLE attach is shown after commissioning

Mesh Link Establishment handles normal Thread discovery, parent selection, and child attachment. Commissioning gives the Joiner the information it needs to become a valid network participant; MLE attach then turns that provisioned device into an operational child or router-capable Thread device.

Primary sources

References used for the model

OpenThread On-mesh commissioning guide

Commissioner and Joiner roles, Joiner Credential, PSKd, and join success flow.

 OpenThread External commissioning CLI

External Commissioner flow through a Border Router and Joiner start sequence.

 OpenThread API Commissioner API reference

Joiner entries, EUI-64 or wildcard authorization, and timeout behavior.

 Thread Group Commissioning white paper

Commissioning terminology and security intent for Thread onboarding.