A device appears in the scan results. You click Add, the log reports successful provisioning, and the gateway gains a new entry. Everything looks finished.
Then you send an On command. Nothing happens.
It is tempting to blame radio coverage, chip compatibility or serial framing. But in SIG Mesh, another question deserves attention first: joining the network does not mean the device is configured to participate in the application.
The previous article explored turning custom advertising into a multihop network. Here we return to the standard, following a controller adding one light through discovery, provisioning, keys, model binding and publish/subscribe.
This is an explanation of the mechanisms, not a completed hardware test report or a guide to one vendor's serial protocol.
Discovery only tells you a device is available
An unprovisioned device can advertise an Unprovisioned Device Beacon. A phone or gateway discovers it, and whichever component acts as the Provisioner initiates the process.
Provisioner is a role. It does not have to be a phone or be permanently tied to the gateway. A product may combine provisioning, configuration and everyday control in one application, but separating those responsibilities helps explain the protocol.
Finding an advertisement does not prove it belongs to the light you intend to add. Discovery identifies a candidate; onboarding still needs identity confirmation and the appropriate security procedure.
With several identical lights nearby, how does the installer select the right one? A button, product-supplied information or supported input/output authentication may be involved. Design that interaction before the installer faces a list of indistinguishable names.
Provisioning establishes network identity
Provisioning is more than writing a password.
The Provisioner and device exchange capabilities, select a supported authentication method, perform public-key-related exchanges and authentication, and securely establish the state needed to join. Input/output capabilities, authentication choices and implementation all matter. Encrypted communication alone does not establish that this is the intended device.
Afterward, the device is a Mesh node with an initial NetKey, IV Index, allocated unicast addressing and its DevKey. The two sides independently derive the DevKey; it is not sent over the air as a plaintext setting. It has a different purpose from the shared NetKey.
The node now has a network identity. The application key for lighting, the model that accepts commands and the group it should listen to may still need configuration. I would label this state “Provisioned; configuration pending,” rather than “Ready to use.”
Three keys with different jobs
Treating NetKey, AppKey and DevKey as interchangeable Bluetooth passwords makes troubleshooting harder.
| Key | Main responsibility | What it does not imply |
|---|---|---|
| NetKey | Network/subnet security and network-layer processing | Access to every application's plaintext |
| AppKey | Protect application messages, with model binding | Every model can use a key merely because it is stored |
| DevKey | Protect configuration communication for that node | A shared everyday control key for the lighting group |
A hallway light may relay other devices' traffic. It needs network-layer processing, not automatic access to every application's contents. Separating NetKey and AppKey separates carrying a message from understanding it. Relaying does not prove the node has the permission or model to execute the command.
An AppKey Index in a log is an index, not the key. Matching numbers in two places do not prove matching key material and context. Verify mappings through trusted configuration records without printing real keys into ordinary logs or screenshots.
Read composition before guessing addresses
The Configuration Client communicates with the node's Configuration Server to inspect and change settings. Composition Data identifies elements, their models and relevant capabilities.
Node, element and model are different levels. One enclosure may contain several independently described elements, each implementing multiple models.
For a multichannel controller, inspect its actual composition. Do not assume every channel lives in the primary element or that the primary address plus an OnOff command controls all outputs. Address allocation must reserve the required space for elements and avoid collisions between nodes.
For our example, identify the light's element and confirm that it implements Generic OnOff Server. The controller must send the corresponding messages and handle the required status responses.
Discovering or provisioning a device does not prove support for your desired application model. Increasing transmit power cannot fix a model mismatch.
AppKey Add and Model App Bind are separate operations
First, add the required AppKey to the target node with the appropriate NetKey association. Then bind that AppKey to the application model that needs it.
Neither step substitutes for the other. A stored key does not automatically authorize every model to process its protected messages. Binding the wrong element or model may change configuration without making the intended light controllable.
The sender also needs the appropriate key and model configuration. Configuring only the lamp does not establish the whole communication relationship. Nor does every model use AppKey binding: Configuration models use DevKey and must not be treated like lighting models.
The Silicon Labs Configuration Client API exposes adding an AppKey and binding a model separately, with result events. This makes three distinct facts visible: the local interface accepted a request, the remote node reported a configuration result, and the required capability actually works.
A successful host function return is not a reason to mark every subsequent stage complete. Follow the selected SDK's result handling and check node, element, model and status. A timeout leaves the outcome uncertain; it does not prove nothing happened remotely.
Make one light respond before adding groups
Start with the shortest diagnostic path: send a unicast command to the confirmed lighting element and observe the corresponding status response.
Unicast control does not require adding that element's model to a group subscription first. Likewise, an API that lets the caller specify a destination explicitly does not necessarily require a preset model publication address for every send.
Once unicast works, introduce grouping. For a wall switch controlling several hallway lights:
- The switch's relevant client model publishes to the hallway group address.
- Each light's relevant server model subscribes to that address.
- Both sides have matching application keys and model configuration.
A new light can join after provisioning, application configuration and subscription, without rewriting an explicit list of lamps in the switch.
The human-readable group name is just a label. “Hallway lights” does not itself establish any subscription. Subscriptions apply to particular models; dragging a device into a room in an app does not prove the radio-side configuration is complete.
Publication also determines where state goes
Control traffic is only half the system. A light can return status for a request that calls for a response. A local button change may instead require an unsolicited report. These are different paths.
Model publication settings can include destination, AppKey and supported publication parameters. Setting a destination does not guarantee every model reports at the period you imagine, or that the application handles every local change correctly.
“Can turn the light on” and “knows its current reported state” deserve separate acceptance checks. For a Matter bridge, a wall-switch change that never reaches the gateway leaves the upper-level app displaying the last command rather than fresh device state.
Even a state report has limits: an output reported as on does not prove the lamp physically works unless the product has appropriate feedback.
Configuration needs recovery, not just a command sequence
Power loss halfway through setup, a missing reply and a host restart are ordinary failure cases. A program that only sends Add Key, Bind Model, Add Subscription and Set Publication has little basis for deciding where to resume.
Record desired configuration and confirmed results. On recovery, inspect the necessary state and reconcile differences. After an AppKey Add timeout, use the protocol and SDK's query capabilities before deciding whether to retry. Repeated-operation behavior depends on the command; not every configuration operation is automatically harmless to repeat.
Persist address allocations, node identities and required key/configuration records, with access control and backups. Otherwise devices can remain in a network the manager has forgotten how to manage.
Factory reset is not the first response to every error: it changes state and may break existing bindings. Distinguish unprovisioned devices, provisioned-but-unconfigured nodes, and working nodes whose management records were lost.
Match the symptom to the layer
| Symptom | Check first |
|---|---|
| Discovered, but provisioning fails | Onboarding mode, bearer support, authentication and reported errors |
| Provisioned, but configuration times out | Addresses, DevKey/network context, reachability and response association; LPN receive timing |
| Configuration works, unicast control does not | Element/model, AppKey addition and binding, sender configuration |
| Unicast works, group control does not | Actual destination, model subscriptions, keys and sending settings |
| Control works, displayed state does not update | Responses, unsolicited publication, reception and upper-layer mapping |
| Failure after restart | Persistence, address records, configuration recovery and key context |
This is a troubleshooting order, not a diagnosis based on symptoms alone. Use state queries, logs and packet captures where necessary to locate the failed stage.
Prove unicast and state feedback first, then groups and reports after local changes, then interrupted setup and restart recovery. Explicit success criteria are more useful than a final note that “the light came on.”
Adding a device is a workflow
The UI may show one Add button, but the implementation has several states: discovered, provisioned, composition identified, application configured, and control/state verified.
Separating them lets the program explain what is done, what remains and where it can resume, without requiring users to learn every protocol detail.
SIG Mesh supplies shared mechanisms. It does not promise automatic interoperability across every brand, model and ecosystem after provisioning. The gateway's work includes the distance between a node joining the network and a device becoming reliably manageable.
Next, we return to Xiaomi Mesh: beyond standard networking and models, what product definitions, identities and platform requirements does Xiaomi Home integration add?
References
- Bluetooth SIG: Mesh Networking Primer — addresses, publish/subscribe, keys, provisioning and configuration.
- Silicon Labs: Configuration Client API — composition, application keys, binding, subscriptions and publication. Use documentation matching your SDK version.
Cover: Japanwikisan, CC BY 4.0.
Originally published at ay3s.com.
Top comments (0)