Best Practices for App Developers

Provisioning, proxy and state handling from the app side.

1. Keep the Mesh Data (CDB) safe

The Bluetooth® Mesh configuration database (CDB) is often overlooked, yet it serves as the single source of truth for the entire mesh network. If it is lost or corrupted, you lose the ability to add, remove, or communicate with nodes. While the underlying network may continue to function, you lose operational control.

Conversely, if your CDB falls into the hands of an unauthorized user or attacker, they gain complete access to your mesh network.

To keep your CDB secure and reliable, ensure that:

  • it cannot be deleted unintentionally.
  • it remains up to date and in a consistent state (ACID compliant).
  • access is strictly restricted to authorized personnel.
  • users only view the sections of the CDB relevant to their role (for example, regular users do not require access to device keys).
  • encryption is enforced during storage and transmission.

2. Synchronize the CDB to multiple users

Another common oversight in Bluetooth® Mesh projects is single-device provisioning. If all nodes are provisioned using a single phone, the CDB remains siloed on that device until a second phone is introduced. This typically happens when scaling up a network where commissioning requires multiple operators, or when multiple users need simultaneous access to control lights, configure thermostats, or read sensor values.

For multi-device environments to function correctly, all clients require an up-to-date copy of the CDB. A naive approach - such as manually exporting and importing the CDB as JSON - frequently leads to severe issues:

  • State Desynchronization: User A communicates with nodes that User B cannot reach, and vice-versa. This state can flip unexpectedly, leading to a frustrating user experience.
  • Visibility Gaps: Nodes added by one user fail to appear for others on the network.
  • Address Collisions: Provisioner A assigns unicast address 0x1234 to a new node, while Provisioner B independently assigns the same address two days later, resulting in random communication errors and timeouts.

These conflicts typically stem from unmanaged state parameters:

  • User and provisioner unicast addresses
  • Sequence numbers (SEQ) and IV Index
  • The replay protection list (RPL)
  • Provisioner address ranges (unicast addresses, group addresses, scenes, etc.)

The proper solution is centralized user and provisioner management paired with a network-synchronized CDB.

3. Manage your users and provisioners

In a Bluetooth® Mesh system, you generally deal with two distinct layers: the mesh network topology itself, and the application-level architecture built on top of it.

  • Mesh Network Layer: Nodes, groups, keys, provisioners, etc.
  • Application Layer: Users, administrators, permissions, floors, rooms, etc.

When designing a multi-user system where individuals have separate logins, map each user (or more accurately, each device belonging to each user) to a distinct node on the network. Each device must have its own unique unicast address. Sharing a single unicast address across multiple devices results in frequent timeouts as receiving nodes drop conflicting packets.

4. Handling Timeouts and Concurrency

Mesh messaging is inherently asynchronous and unreliable. Requests may generate multiple responses in arbitrary order, combined with variable delays and unsolicited messages. Consequently, your application code must treat concurrency as a first-class citizen: never block while awaiting a reply, do not assume a deterministic response order, and always account for dropped packets. A well-designed Bluetooth Mesh library built with an async-first architecture can significantly simplify this handling.

Configuring appropriate timeouts is critical. A timeout that is too short causes missed replies, while one that is too long leaves the system hanging unnecessarily. Consider the following strategies when determining your timeout thresholds:

Strategy Definition
Hardcoded A fixed value (e.g., 5 seconds). Only suitable if you have a reliable benchmark of your target network’s scale and topology.
User-Settable Exposes timeout settings in the application UI for manual fine-tuning. Less convenient, but safer than a rigid hardcoded value.
Automatic Scales dynamically based on network size and hop count. While optimal, this is often difficult to implement accurately without prior knowledge of network density.

5. Set the right number of Proxy Nodes

Deploying excessive proxy nodes generates unnecessary traffic on advertising channels, consuming valuable bandwidth. Conversely, too few proxy nodes make it difficult for clients to find a reliable connection point.

The On-Demand Private Proxy feature introduced in the Mesh Protocol Specification 1.1 helps mitigate this by activating the proxy function only when explicitly requested by a client device.

Depending on your project requirements, the number of proxy nodes can be determined via:

  • Heuristics: Designating every 10th provisioned node as a proxy.
  • Manual Planning: Pre-configuring proxy placements based on floor plans during site tuning.
  • Algorithmic Discovery: Automatically balancing proxy roles based on node signal strength and coverage mapping. (Note: As of 2026, automated dynamic proxy tuning is largely theoretical, but technically feasible.)

6. Set the right number of Relay Nodes

Similar to proxies, configuring the correct number of relay nodes requires careful balancing. Too many relays flood the network with redundant messages, causing severe congestion; too few relays result in unreachable nodes and broken packet delivery routes.

Optimal placement can be achieved through manual floor-plan design, empirical heuristics, or network probing algorithms combined with strategic testing.

7. Set up subnets to segment network traffic

Relay nodes forward all messages encrypted with a network key they possess, effectively restricting message propagation to specific subnets. To minimize overall network traffic, you can segment large installations into smaller operational subnets. For example, isolating communication within a single room ensures that messages intercepted by a neighboring room are not needlessly relayed further across the facility.