Best Practices for Firmware Developers
Tips and Tricks to create great performing Bluetooth® Mesh devices.
Even though we do not develop firmware at Kodira, we got some insights into good and bad firmware implementations through multiple projects that we have worked on. The following best practices are mostly focused on topics where app and firmware intersect or topics that are crucial for larger networks to function smoothly. We are aware that there are resource constraints when developing for embedded systems. The following recommendations apply in case the available resources allow them. If not, there will always be a trade-off.
1. Stack Settings
Most embedded Bluetooth Mesh stacks can be configured with the following settings. Most of the settings are a trade-off between (flash) memory consumption and performance.
| Stack Setting | Minimum Recommendation | Our Recommendation | Notes |
|---|---|---|---|
| Number of Network Keys | 2 | 3 or more | The NLC profile specifications 1.0.1 require at least 2 net keys. More can be useful for larger installations. |
| Number of App Keys | 3 | 4 or more | The NLC profile specifications 1.0.1 require at least 3 app keys. More can be useful for larger installations. |
| Number of App Keys that can be bound to each Model | 3 | 4 or more | The NLC profile specifications 1.0.1 require that at least 3 different app keys can be bound to each model. Since multiple app keys can reference the same net key the number of supported app keys should generally be higher than the number of supported net keys. |
| Number of Proxy Filter List entries | 8 | 8 or higher | The NLC profile specifications 1.0.1 require at least 8 entries. This is only relevant for nodes that have the proxy feature enabled. In our experience, 8 should usually be more than enough. |
| Number of Subscriptions per Model | 32 | 32 or higher | The Basic Lightness Controller 1.0.1 NLC profile specification requires at least 32 subscriptions for the Light LC Server model. But since most stacks only have a single setting for all models, we take this as a general recommendation even though for many projects a lower number would be sufficient. |
| Network Message Cache Size | 64 | 128 or higher | The NLC profile specifications 1.0.1 require a network message cache size of at least 64. Generally higher is better since a higher number allows better filtering of duplicated packets and prevents unnecessary relaying. |
| Replay Protection List (RPL) | 255 | 350 or higher | The Basic Lightness Controller 1.0.1 NLC profile specification requires at least a size of 255 entries. Higher numbers allow for subnets with more nodes. E.g. Silvair is using 350 with firmware 2.31. |
While the numbers of app keys and net keys are probably obvious, there are the following less obvious settings that might need more explanation since they are important for the overall network performance.
Network Message Cache
The Network Message Cache is a temporary ring buffer located in a node’s RAM. It stores data from recently seen network packets.
Because Bluetooth® Mesh uses a managed flooding paradigm, a single message can reach a node multiple times via different paths. When a node receives a packet, it extracts distinguishing metrics - such as the Sequence Number, IV Index, and Source Address - and checks them against the cache.
- If a match is found, the packet is a duplicate and is immediately discarded.
- Discarding it early prevents unnecessary decryption operations (saving processing power) and halts continuous packet retransmission loops.
So a larger Network Message Cache reduces the load on the whole network.
Replay Protection List (RPL)
The Replay Protection List (RPL) is a mandatory security structure used to defend the network against replay attacks.
Every valid Bluetooth® Mesh message contains an incrementing Sequence Number (SEQ). The RPL tracks the highest known sequence number received from every individual element/unicast address that communicates with that node. If a node receives a message from a known source, but the SEQ number is equal to or lower than the value recorded in the RPL for that source, the message is flagged as a security violation and dropped.
The Rule of Thumb: The RPL size must be scaled according to the maximum number of unique devices (elements) that will actively talk to this specific node. Nodes that primarily send data (like sensors and switches) can use a smaller RPL, but devices that receive data from a lot of nodes (fixtures, controllers, gateways) should use a larger RPL. If (flash) memory is not an issue, go as high as possible.
Note that the RPL usually should be persisted to flash memory to keep up good security even after reboots or crashes.
2. Auxiliary Server Models to include
Besides the actual core models that you need for your use case (like generic on/off server, light lightness server, etc.) there are a couple of models that might not be needed for the core function but are still useful for developers, administrators, etc.
| Server Model | Why is it useful? |
|---|---|
| Location (Setup) Server | Allows the user or system to set the location of the device in global coordinates and/or local coordinates plus floor number. Unfortunately there is no field for ‘room number’. |
| Time (Setup) Server | This gives the node a sense of time to locally execute schedules and/or to propagate that time to other nodes. |
| Manufacturer Property Server | Use this model to provide information about the firmware version, model number, power-up cycles, etc. |
| Generic Battery Server | If your device is battery powered, this model is needed to communicate battery level, charge state, etc. to others. |
| Scene (Setup) Server | To store scenes on the device locally. Those scenes can be recalled by a client or through a schedule. |
| Schedule (Setup) Server | To recall stored scenes based on a schedule. E.g., turn off the light each evening at 8 pm. |
| Sensor (Setup) Server (for energy monitoring) | If your device controls anything that might take up significant energy (like a light, motor, heater, etc.) use the Sensor Server model to publish the energy consumption. And when doing so, do it according to the Energy Monitor NLC Profile. |
3. Support Periodic Publication
Support periodic publication even if you think you might not need it. E.g., if you are implementing a smart relay, you might think that it is enough to publish the current state each time the state changes. However, for states that do not change often, a periodic publication is helpful to update apps/services/dashboards that only temporarily join the network. That way they can update their state without explicitly querying the device.
4. Reboot after Reset
A node can get deprovisioned/reset through a mesh message. A common flow looks as follows:
- The node receives the reset message through the mesh network.
- The Bluetooth® Mesh stack calls a callback in the application code.
- Inside the callback:
- the mesh configuration (keys, etc.) gets deleted (if not done by the stack before calling the callback).
- some other information (settings, statistics) gets deleted from flash.
- a reboot gets triggered so that the node reboots cleanly into its unprovisioned state.
It is important that, before rebooting, you give the stack some time to send an acknowledgment message to the client. Otherwise the client does not know that the node has received the reset message and thus cannot take appropriate action like removing the node from the app’s local database.
5. Include manual/physical Reset
In addition to the deprovisioning/reset through the mesh network always include a way to manually reset the node. E.g., by long-pressing a button, using a magnet, etc. This is important in cases where the app/gateway lost the keys/credentials of the node and thus is no longer capable of communicating with the node.
6. Test the IV Update Procedure (really!)
The IV Update Procedure is usually irrelevant during development. Developers will reset their nodes so frequently that they will never run out of available sequence numbers. However, in production this will happen - either the sequence numbers actually run out or a node from a different vendor will trigger an IV update based on time (e.g., once every 30 days). In that case the firmware needs to behave properly; otherwise the stability of the whole mesh network is at stake. We have seen networks break in multiple parts, forming islands, etc. - it is a nightmare to debug.
7. Keep Unprovisioned Device Beacons in check
If your customers commission a new network with hundreds of nodes and those nodes send their unprovisioned device beacons too frequently, the beacons will clutter up the Bluetooth® advertising channels, making the whole commissioning slow, unreliable and painful. It’s hard to give a general recommendation, but when in doubt lean toward a slower interval. It is better if commissioners need to wait a second until your device shows up inside the commissioning app than if the whole commissioning process does not work at all. We suggest using around 300 ms or more. Another option is some kind of physical trigger/button to turn on fast advertising only for a couple of minutes and otherwise default to a very slow interval.
8. Use a meaningful CID, PID, and VID
The company ID (CID), product ID (PID), and version ID (VID) should not be an afterthought. Make sure to use a unique PID for each physical product, or at least whenever the product’s mesh interface or intent differs significantly. There are more than 65,000 product IDs available to each company, so you don’t need to worry about running out.
Why is that important? Imagine an app that wants to show a specific UI or icon for each type of product, such as a switch icon for a wall switch and a bulb icon for a light bulb. If you reuse the PID across several types of products, this will not work. Reusing the PID across multiple products makes the device more difficult to integrate with others and less likely to be used in a mixed-vendor installation.
However, reusing the PID across multiple products is fine if they - for example - only differ in color or shape, but share the same intent, mesh elements, and mesh models.
Contact us if you have any other best practices regarding Bluetooth® Mesh that we should add. And also contact us if you disagree with any of the above.