How To Design With Bluetooth Mesh
You can "git" a workspace will all of these files at https://github.com/iotexpert/MouserVTWBluetoothMesh or git@github.com:iotexpert/MouserVTWBluetoothMesh.git
Summary
This lesson walks you through the fundamentals of Bluetooth Mesh Networking. There is actually quite a bit going on from a detail standpoint to make Bluetooth Mesh work as documented in the 713 pages of Bluetooth Mesh specifications:
- Bluetooth Mesh Profile (333 pages)
- Bluetooth Mesh Model (317 pages)
- Bluetooth Device Properties (63 Pages).
However, Cypress has abstracted a significant amount of this complexity into our stack so as to ease your journey.
Specifically in this lesson we will talk about:
- Topology
- Elements
- Addressing
- Messaging
- Subscribe & Publish
- Models
- State
- Complexity
- Security
- Provisioning & Configuration
- Bluetooth Mesh Stack
Bluetooth Mesh Topology
Let’s start by examining a prototypical Bluetooth Mesh network:
The standard node functionality involves sending and receiving mesh messages. Every node in the network must be able to act as a standard node.
Relay Node
Relay nodes can receive a message for the network and then retransmit it to other devices in range. This is the method by which mesh networks can cover larger distances than the range of any single device. For a network to operate, every node must be within range of at least one relay so that its messages can be forwarded on to nodes that it cannot directly communicate with.
It is common for all except low power nodes to implement a relay feature in order to maximize the possible paths through a mesh network.
GATT Proxy Node
Many existing BLE devices support traditional BLE GATT communication but not mesh communication. Most smartphones and tablets fall into this category. Since you may want to interact with a mesh network from one of those devices, the GATT proxy was created. A GATT proxy node has both a mesh interface and a GATT interface. The GATT interface is used to communicate with BLE devices that don’t possess a mesh stack and then relay those messages to/from the mesh network. That is, the GATT proxy acts as a bridge between the mesh network and the traditional BLE GATT device.
Friend and Low Power Nodes
Friend and Low Power Nodes are used to optimize power consumption for constrained devices. Devices that are power constrained (e.g. a battery powered device) are designated as low power nodes. Every low power node in the network must be associated with exactly one friend node. Friend nodes are devices which are not power constrained (e.g. a device plugged into AC power) that support 1 or more low power nodes depending on its capabilities (e.g. available RAM).
When a low power node is added to a mesh network it broadcasts a request for a friend. Each friend in range that can handle a new low power node replies and the low power node selects the best friend based on how many messages the friend can store; the RSSI and the timing accuracy.
Once the relationship is established, the friend node will receive and store messages for any low power nodes that it is associated with. The low power node will periodically ask the friend node for any messages that the friend has stored for it. In this way, the low power node does not need to listen continuously for mesh packets. Instead, it can be in a low power mode most of the time and can wake up only periodically for a very short time.
For example, consider a battery powered mesh connected thermostat. It will measure the actual temperature and may publish a mesh message with the temperature once per minute. This can be done with very low power consumption since the device can be sleeping all the time except for a short period each minute to send the value. However, it must also be possible to change the set point of the thermostat. In this case, instead of sending messages, the thermostat must be listening for messages. If it listens constantly for messages the power consumption will be unacceptably high, but if it only listens occasionally for messages it will likely miss messages. By making the thermostat a low power node we get the best of both worlds – it can send messages once a minute and receive any stored messages regarding the set point from its friend node. No messages are missed even though the thermostat is awake only a very small percentage of the time.
Bluetooth Mesh Elements
An Element is just a “Thing” in the network. For instance a light bulb or a light switch or a temperature sensor. A physical node can be built up of multiple elements. Think of a ceiling fan that also has a light bulb.
Each Element in the network will have an address and be uniquely addressable. This means that a Node may have multiple Bluetooth Mesh addresses, but it will have only one Bluetooth MAC address.
Bluetooth Mesh Addressing
Mesh messages have a source address and a destination address. Both addresses are 16-bit values. There are three types of addresses defined for messages. They are:
1. Unicast
2. Group
3. Virtual
| Address Type | Address Range | Number of Addresses |
|---|---|---|
| Unassigned | 0b0000000000000000 | 1 |
| Unicast | 0b0xxxxxxxxxxxxxxx | 32767 |
| Group | 0b11xxxxxxxxxxxxxx | 16384 |
| Virtual | 0b10xxxxxxxxxxxxxx | 16384 hash values |
Unicast
A unicast address is used to communicate with a single element in a single node. Each element in a network must have a unicast address that is unique to that network. During provisioning, the primary element in a node is assigned a unique unicast address and each additional element in the node uses the next address.
The source address in any message must be a unicast address. That is, the message must specify the specific element that message was sent by. Group and Virtual addresses are not allowed as the source address.
Group
As the name implies, a group address is used to communicate with one or more elements. Group addresses are either defined by the Bluetooth SIG (known as fixed group addresses) or are assigned dynamically for a given mesh network. There are 16K total group addresses available. The SIG has reserved space for 256 of them to be fixed while the rest can be dynamically chosen by the network.
Of the 256 group addresses that the SIG has reserved for fixed addresses, currently only 4 of them are assigned specific purposes. The rest are reserved for future use. They are:
| Fixed Group Address | Name |
|---|---|
| 0b1111111100000000 – 0b1111111111111011 | Reserved |
| 0b1111111111111100 | all-proxies |
| 0b1111111111111101 | all-friends |
| 0b1111111111111110 | all-relays |
| 0b1111111111111111 | all-nodes |
Other group addresses can be assigned for any logical group in the network. For example, room names such as kitchen, bedroom or living room could be identified as group names to control multiple elements at once. As another example, you can have one switch turn on/off multiple bulbs at the same time with a single message to a group address.
Virtual
A virtual address is assigned to one or more elements across one or more nodes. A virtual address takes the form of a 128-bit UUID that any element can be assigned to, like a label. This 128-bit address is used in calculating the message integrity check.
The 14 LSBs of the virtual address are set to a hash of the label UUID such that each hash represents many label UUIDs. When an access message is received for a virtual address with a matching hash, each corresponding label UUID is compared as part of the authentication to see if there is a matching element.
This may be used by a manufacturer to allow mesh networks including those devices to send messages to all similar devices at one time.
Bluetooth Mesh Messaging
The Bluetooth Mesh communication happens using BLE Advertising packets. There are two classes of messages in the Bluetooth Mesh, Control and Access. By and large the control messages are used for network control, and you never see them as they are handled by the stack. The Access messages are ones that matter to us as application developers.
We all know that the BLE advertising packet is only 31 bytes long. This makes things difficult as most of the packet is used up by network protocol overhead leaving only a few bytes for the actual message. The good news is that the stack handles splitting up your payload into as many as 32 packets (called segmented) and getting them re-sequenced automatically.
I’m not very good at limits … but this is what you have to live with in BLE Mesh:
| Message Type | Max Payload Size (Octets) |
|---|---|
| Unsegmented Control or Access | 11 |
| Segmented Control | 256 |
| Segmented Access | 376 or 380 |
Acknowledged vs. Unacknowledged
As the name suggests, acknowledged messages require a response from the node that it is addressed to. The response confirms that the message was received and it may also return data back to the sender (e.g. in response to a GET). If a sender does not receive the expected response from a message it may resend it. Messages must be idempotent so that a message received more than once is no different than if it had only been received once.
GET, SET, STATUS
All access messages are of the three broad types of GET, SET, and STATUS.
GET messages request a state value from one or more nodes. A GET message is always acknowledged.
SET messages are used to change the value of a state. A SET message can be either acknowledged or unacknowledged.
STATUS messages are sent in response to a GET, and acknowledged SET, or may also be sent by a node independently, for example, periodically using a timer. A STATUS message is always unacknowledged. Therefore, if a node sends a GET message but never receives a STATUS return message, it may resend the GET message.
BLE Mesh Publishing
From the BLE Mesh Spec “All communication within a mesh network is accomplished by sending messages. Messages operate on states. For each state, there is a defined set of messages that a server supports and a client may use to request a value of a state or to change a state. A server may also transmit unsolicited messages carrying information about states and/or changing states.”
The BLE Mesh Application communication scheme is based on the Publish/Subscribe & Client/Server paradigm and are embedded automatically into Access messages by the stack. An Element may publish messages (either to a group or a unicast address). And an Element may subscribe to messages from one or more groups.
Models
An Element is not very interesting without a mechanism to interact with it. A Model is exactly that, specifically it is the Bluetooth SIG defined behavior and data/state of an Element. Each Element in your Node will have one or more Models that are attached to it that you can think of as Servers which hold, send and receive data.
Models fall into three categories. Servers, Clients and Control (hybrid Server/Control)
Server: Contains data and sends it out in response to Client GET requests or can update the data based on Client SET requests or may send Status based on changes in the Element.
Clients: Send GET requests to Servers or Send SET requests to Servers.
Control: A Hybrid Model that acts both as a Client and a Server.
Here is an example picture from the AN227069 – Getting Started with Bluetooth Mesh
To make this system work the Bluetooth SIG has also defined the standard behavior for a bunch of different models including:
States
From the Bluetooth Spec “A state is a value representing a condition of an element.” States are associated with a particular server model. That is, the spec defines the states that apply to each server model and how they behave.
Complexity
There is quite a bit more going on in the Bluetooth Mesh specifications including the abilities to handle:
- Scenes (e.g. go in a room and have all the lights, sound, hvac go to the right levels)
- State binding – Multiple states are bound together such that when one changes the others change (e.g. you turn the volume so low that it becomes off)
- State transition times (e.g. Fade the lights up or down over a set time period)
- Alerts (e.g. notify the user with a blinking light)
Security
There are three levels of security in a Bluetooth Mesh network and access is governed by three keys.
All nodes in a mesh network must possess the network key. In fact, possession of the NetKey is what makes a node a member of a given mesh network. The NetKey allows a node to decrypt and authenticate messages at the network Layer. The mesh packet header and address are encrypted and authenticated with the network key. This allows a node to perform relay functions, but it does NOT allow the relay node to decrypt the application data that is stored in a message.
AppKey
The mesh packet payload is encrypted and authenticated with the application key. Therefore, data for a specific application can only be decrypted by nodes that have the AppKey for that application. The AppKeys are used by the upper transport layer to decrypt and authenticate messages before passing them to the access layer.
The existence of AppKeys allows multiple applications to share a mesh network (and therefore gain all the benefits of having more nodes such as increased reliability and range) without each node having access to all messages.
For example, consider a mesh network that has lights, HVAC, and home security devices on it. The light fixtures and light switches would share an AppKey for lighting; the thermostats, furnace, and air conditioner would share an AppKey for HVAC; the door locks and alarm system would share an AppKey for home security. In this way, home security messages can only be decrypted by devices that are part of the home security system, etc.
DevKey
Each device has its own unique device key known only to itself and the provisioner device. This key is used for secure communication during configuration.
Provisioning and Configuration
When a node turns on for the first time it barely knows its own name. It definitely does not know any of the security keys, its addresses (unicast or group) or any of its model configuration information. So what does it do? Simple – it starts to send out a BLE Advertising packet in the format of a BLE Mesh Beacon. Then it waits for a provisioning device to make a BLE GATT connection to provision the node with the network information. The provisioning process assigns the netkey and the unicast address of the primary element.
After the device is provisioned it will be able to hear and decode BLE Mesh packets. But, it won’t know much else to do until the Elements have been configured. So, the next step for the provisioning application is to send the rest of the configuration information. e.g. group subscriptions, application keys etc.
Bluetooth Mesh Stack
3 Comments
Thanks a lot for this, Alan. Your tutorials are always helpful and easy to follow.
Hi Alan, We need some help on custom BLE mesh. Would you be interested in doing a consultancy for our company.
We traded email.
git@github.com:cypresssemiconductorco/mbed-os-example-bluetooth-mesh-gateway.git