Ublox ANNA-B112, NINA-B111, NINA-B112, NINA-B311, NINA-B312 User Manual
...
blox modules in a Bluetooth
Implementing Bluetooth
mesh with u-connectXpress
software
Bluetooth mesh
Application note
Abstract
This application note describes how to use Bluetooth mesh-enabled umesh network.
UBX-19025268 - R06
C1-Public www.u-blox.com
Implementing Bluetooth mesh with u-connectXpress software - Application note
u-blox or third parties may hold intellectual property rights in the products, names, logos and designs included in this
document. Copying, reproduction, modification or disclosure to third parties of this document or any part thereof is only
permitted with the
The information contained herein is provided “as is” and u
implied, is given, including but not limited
purpose of the information. This document may be revised by u
documents, visit www.u
Copyright © u
Document information
Title
Implementing Bluetooth mesh with u-connectXpress software
Subtitle Bluetooth mesh
Document type
Document number
Application note
UBX-19025268
Revision and date R06 12-Feb-2021
Disclosure restriction C1-Public
This document applies to the following products:
Product name u-connectXpress software version
ANNA-B112 MESH-2.1.0
NINA-B111 MESH-5.1.0
NINA-B112 MESH-5. 1.0
NINA-B311 v3.0.0
NINA-B312 v3.0.0
NINA-B316 v3.0.0
express written permission of u-blox.
-blox assumes no liability for its use. No warranty, either express or
to, with respect to the accuracy, correctness, reliability and fitness for a particular
-blox at any time without notice. For the most recent
-blox.com.
-blox AG.
UBX-19025268 - R06 Document information Page 2 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
Contents
Document information ............................................................................................................................. 2
Contents ....................................................................................................................................................... 3
1 Introduction .......................................................................................................................................... 7
1.1 General information about Bluetooth® mesh ....................................................................................... 7
1.2 Bluetooth mesh with u-connect software ............................................................................................. 8
1.3 Example used in this document ............................................................................................................... 8
1.4 Configuring the evaluation kits ................................................................................................................ 9
1.5 Clearing the non-volatile memory .......................................................................................................... 10
2 Mesh models in u-connectXpress software ............................................................................. 11
2.1 Introduction ................................................................................................................................................ 11
2.2 Example client model in u-connectXpress ........................................................................................... 11
2.3 Example server model in u-connectXpress .......................................................................................... 12
3 Provisioning u-connectXpress modules .................................................................................... 13
3.1 Introduction ................................................................................................................................................ 13
3.2 Provisioning using AT commands ......................................................................................................... 14
3.2.1 Client node ......................................................................................................................................... 14
3.2.2 Server node ........................................................................................................................................ 14
3.3 Provisioning using a smartphone application ..................................................................................... 15
4 Configuring u-connectXpress mesh node ................................................................................ 16
4.1 Client node .................................................................................................................................................. 16
4.2 Server node ................................................................................................................................................. 16
4.3 Remote configuration .............................................................................................................................. 16
5 Running the sample mesh network ............................................................................................ 18
Appendix .................................................................................................................................................... 20
A AT commands for Bluetooth mesh ............................................................................................. 20
A.1 Set Bluetooth mode +UBTMODE ........................................................................................................... 20
A.1.1 Description ......................................................................................................................................... 20
A.1.2 Syntax ................................................................................................................................................. 20
A.1.3 Defined values ................................................................................................................................... 20
A.1.4 Notes ................................................................................................................................................... 20
A.2 Set device info +UBTMDID ...................................................................................................................... 20
A.2.1 Description ......................................................................................................................................... 20
A.2.2 Syntax ................................................................................................................................................. 20
A.2.3 Defined values ................................................................................................................................... 21
A.3 Add Model +UBTMMOD ........................................................................................................................... 21
A.3.1 Description ......................................................................................................................................... 21
A.3.2 Syntax ................................................................................................................................................. 21
A.3.3 Defined values ................................................................................................................................... 21
A.4 Add generic model +UBTMMODG ......................................................................................................... 21
A.4.1 Description ......................................................................................................................................... 22
UBX-19025268 - R06 Contents Page 3 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
A.4.2 Syntax ................................................................................................................................................. 22
A.4.3 Defined values ................................................................................................................................... 22
A.5 Bind device key to remote configuration server +UBTMCCB .......................................................... 22
A.5.1 Description ......................................................................................................................................... 22
A.5.2 Syntax ................................................................................................................................................. 22
A.5.3 Defined values ................................................................................................................................... 23
A.6 Unbind device key of remote configuration server +UBTMCCU ..................................................... 23
A.6.1 Description ......................................................................................................................................... 23
A.6.2 Syntax ................................................................................................................................................. 23
A.6.3 Defined values ................................................................................................................................... 23
A.7 Set mesh configuration parameters +UBTMCFG .............................................................................. 23
A.7.1 Description ......................................................................................................................................... 23
A.7.2 Syntax ................................................................................................................................................. 23
A.7.3 Defined values ................................................................................................................................... 24
A.8 Mesh configuration event +UUBTMC ................................................................................................... 24
A.8.1 Description ......................................................................................................................................... 24
A.8.2 Defined values ................................................................................................................................... 24
A.9 Add opcode +UBTMOPC .......................................................................................................................... 24
A.9.1 Description ......................................................................................................................................... 24
A.9.2 Syntax ................................................................................................................................................. 24
A.9.3 Defined values ................................................................................................................................... 24
A.10 Add element +UBTMELM ........................................................................................................................ 25
A.10.1 Description ......................................................................................................................................... 25
A.10.2 Syntax ................................................................................................................................................. 25
A.10.3 Defined values ................................................................................................................................... 25
A.11 Publish opcode +UBTMPUB .................................................................................................................... 25
A.11.1 Description ......................................................................................................................................... 25
A.11.2 Syntax ................................................................................................................................................. 25
A.11.3 Defined values ................................................................................................................................... 26
A.12 Reliable publish of opcode +UBTMRPUB ............................................................................................. 26
A.12.1 Description ......................................................................................................................................... 26
A.12.2 Syntax ................................................................................................................................................. 26
A.12.3 Defined values ................................................................................................................................... 26
A.13 Reply to a message +UBTMRPY ............................................................................................................ 27
A.13.1 Description ......................................................................................................................................... 27
A.13.2 Syntax ................................................................................................................................................. 27
A.13.3 Defined values ................................................................................................................................... 27
A.14 Message event +UUBTMRCV ................................................................................................................. 27
A.14.1 Description ......................................................................................................................................... 27
A.14.2 Defined values ................................................................................................................................... 27
A.15 Publish status event +UUBTMPSE ....................................................................................................... 28
A.15.1 Description ......................................................................................................................................... 28
A.15.2 Defined values ................................................................................................................................... 28
UBX-19025268 - R06 Contents Page 4 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
A.16 Node version +UBTMVER ........................................................................................................................ 28
A.16.1 Description ......................................................................................................................................... 28
A.16.2 Defined values ................................................................................................................................... 28
A.16.3 Defined values ................................................................................................................................... 29
A.17 Define network key +UBTMNKY ............................................................................................................ 29
A.17.1 Description ......................................................................................................................................... 29
A.17.2 Syntax ................................................................................................................................................. 29
A.17.3 Defined values ................................................................................................................................... 29
A.18 Define application key +UBTMAKY ....................................................................................................... 29
A.18.1 Description ......................................................................................................................................... 29
A.18.2 Syntax ................................................................................................................................................. 29
A.18.3 Defined values ................................................................................................................................... 30
A.19 Add subscription address +UBTMSUB ................................................................................................ 30
A.19.1 Description ......................................................................................................................................... 30
A.19.2 Syntax ................................................................................................................................................. 30
A.19.3 Defined values ................................................................................................................................... 30
A.20 Delete subscription +UBTMSUBD ......................................................................................................... 30
A.20.1 Description ......................................................................................................................................... 30
A.20.2 Syntax ................................................................................................................................................. 30
A.20.3 Defined values ................................................................................................................................... 31
A.21 Add local address +UBTMADR ............................................................................................................... 31
A.21.1 Description ......................................................................................................................................... 31
A.21.2 Syntax ................................................................................................................................................. 31
A.21.3 Defined values ................................................................................................................................... 31
A.22 Clear local address +UBTMADRCLR ..................................................................................................... 31
A.22.1 Description ......................................................................................................................................... 31
A.22.2 Syntax ................................................................................................................................................. 32
A.23 Bind application key +UBTMAKB ........................................................................................................... 32
A.23.1 Description ......................................................................................................................................... 32
A.23.2 Syntax ................................................................................................................................................. 32
A.23.3 Defined values ................................................................................................................................... 33
A.24 Add publish address +UBTMPAD .......................................................................................................... 33
A.24.1 Description ......................................................................................................................................... 33
A.24.2 Syntax ................................................................................................................................................. 33
A.24.3 Defined values ................................................................................................................................... 33
A.25 Add device key +UBTMDKY .................................................................................................................... 33
A.25.1 Description ......................................................................................................................................... 33
A.25.2 Syntax ................................................................................................................................................. 33
A.25.3 Defined values ................................................................................................................................... 34
A.26 Set element model parameters +UBTMEMP ...................................................................................... 34
A.26.1 Description ......................................................................................................................................... 34
A.26.2 Defined values ................................................................................................................................... 34
A.27 Set relay status +UBTMRLY ................................................................................................................... 34
UBX-19025268 - R06 Contents Page 5 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
A.27.1 Description ......................................................................................................................................... 34
A.27.2 Syntax ................................................................................................................................................. 35
A.27.3 Defined values ................................................................................................................................... 35
A.28 Clear mesh stack flash storage +UBTMCLR ....................................................................................... 35
A.28.1 Description ......................................................................................................................................... 35
A.28.2 Syntax ................................................................................................................................................. 35
B Limitations ......................................................................................................................................... 36
C Power consumption ......................................................................................................................... 37
D Glossary .............................................................................................................................................. 38
Related documentation ......................................................................................................................... 39
Revision history ....................................................................................................................................... 40
Contact ....................................................................................................................................................... 41
UBX-19025268 - R06 Contents Page 6 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
1 Introduction
1.1 General information about Bluetooth® mesh
Bluetooth mesh is a specification for forming mesh networks developed by the Bluetooth SIG
(http://www.bluetooth.org). See reference [2] for additional information. It was developed to support
a number of use cases for large scale networks. The nodes can communicate using one-to-one,
one-to-many, and many-to-many communication. Each node in a Bluetooth mesh network has one of
the defined node types as shown in Figure 1.
Figure 1: Different node types in Bluetooth mesh network
The nodes communicate using messages defined by opcodes, which is a number that identifies the
message.
Each node has a “model”, which defines the functionality of the node, similar to the general structure
of a mesh node in Figure 2. The models can be generic, as is predefined in the Bluetooth mesh
standard, or proprietary and defined by the implementer. With u-connect software, the models for the
node functionality can be provided using AT commands and letting an external MCU handle the logic
of the node, as described in chapter 2.
To add a device to a mesh network, you need to “provision” it, meaning you give it an address on the
network and add crypto keys for the network; see chapter 3 for a detailed description. Information
about the “configuration” of a node, or how to add publish and subscription addresses for the models
in the node are also provided in chapter 3.
UBX-19025268 - R06 Introduction Page 7 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
Node
Subscriptions
Elements
Publication
Models
Figure 2: Elements and models in Bluetooth mesh
In a mesh node that is based on u-connect software, define the models first and then provision and
configure the node.
For more information about Bluetooth Mesh in general, see [2] and [3].
Operations
(Opcodes)
Per model;
Get (read), Set (write), Set
Unacked and
Status operations
1.2 Bluetooth mesh with u-connect software
Bluetooth mesh can be used with u-connectXpress software. With u-connectXpress software, you
need to add an external MCU to handle events.
This application note will describe how to:
• Use u-connectXpress software in a Bluetooth mesh network
• Provision and configure a u-blox module running u-connectXpress for a Bluetooth mesh network
The applicable software versions are listed on page 2 in this document. Separate mesh-enabled
software is used in ANNA-B1 and NINA-B1 products.
The limitations of mesh-enabled u-connectXpress software and u-connectXpress software in mesh
mode are described in appendix B.
1.3 Example used in this document
This document provides sample instructions for building a very small mesh network with two nodes
using u-connect software. The sample setup has one server node and one client node. The server node
will implement an OnOff server that enables turning on or off an LED over the mesh network,
corresponding to a mesh-enabled lightbulb or smart-plug.
Both the server and client are running on NINA-B3 Evaluation kits.
UBX-19025268 - R06 Introduction Page 8 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
OnOff client
Address: 0x5002
Implemented using u-connectXpress
Figure 3: Overview of the sample application
For details on the NINA-B3 evaluation kits, see the EVK-NINA-B3 user guide [9].
OnOff server
Address: 0x5000
Implemented using u-connectXpress
1.4 Configuring the evaluation kits
This section provides information on how to configure the nodes in order to communicate on the same
network and with the applications running on each node.
A node in a mesh network needs to go through a number of stages in order to be functional:
1. Define models and opcodes for node
2. Provision node with keys in order to connect to a Bluetooth mesh network
3. Configure node with publish and subscribe addresses
This document describes the various configuration steps in the following chapters:
1. One evaluation kit is configured as a client in chapter 2.2.
2. One evaluation kit is configured as a server in chapter 2.3.
3. The kits are provisioned with network keys in chapter 3.
4. The kits are configured with addresses in chapter 4.
5. In chapter 5 the example is run using AT commands.
☞ All u-connect software mesh nodes have the Bluetooth mesh relay node functionality enabled by
default so that it is possible to easily extend this example to several nodes.
UBX-19025268 - R06 Introduction Page 9 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
1.5 Clearing the non-volatile memory
During development, more than just AT+UFACTORY is required to make a complete factory reset,
including removing all mesh configuration, provisioning data and model definitions:
# 1) Clear the mesh stack’s flash memory (provisioning) and clear the local unicast address:
AT+UBTMCLR
# The module will restart again
AT+ UBTMADRCLR
AT&W
AT+CPWROFF
# The module will restart again
# 2) Clear the model definition:
AT+UFACTORY
AT+CPWROFF
If it is only desired to go to an unprovisioned state, step 1 above is enough. In that case, the previously
defined model is kept.
☞ Note that this action may have implications on the network you are using. Normally it is not
allowed to reuse an address until the network keys have been changed, so this should only be done
when the whole network is reset.
UBX-19025268 - R06 Introduction Page 10 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
Sensors and actuators
2 Mesh models in u-connectXpress software
2.1 Introduction
In u-connectXpress, the functionality of the models is implemented using AT commands and the logic
must reside on an external MCU. The external MCU communicates over a serial interface (UART)
using AT commands as shown in Figure 4.
Figure 4: Software architecture of u-connectXpress
The mesh functionality in u-connectXpress is implemented using AT commands described in the
u-connect AT commands manual [1].
u-connectXpress nodes can be configured easily using the s-center application [6] from u-blox;
however, any terminal application that can connect to a UART can also be used. If you are unfamiliar
with u-connectXpress, watch the introductory video provided in reference [7].
Before the model definition can start you need to set the module in mesh mode:
# Set module in Bluetooth Low Energy + mesh mode
AT+UBTMODE=6
AT&W
AT+CPWROFF
For AT command examples and further information about the parameters, see appendix A.
2.2 Example client model in u-connectXpress
In this section a Generic OnOff client is defined in the u-connectXpress node.
When using the predefined Bluetooth SIG models, messages need not be added explicitly as they are
already included in the stored model. The models are identified using the numbers as described in the
Mesh Model Specification [2]. The Generic OnOff client has the SIG Model ID - 0x1001.
# Model index 0, Generic OnOff client
AT+UBTMMODG=0,1001
AT+UBTMELM=0,0
AT&W
AT+CPWROFF
As shown above, add a generic model (AT+UBTMMODG) and then instantiate it to an element on the node
(
AT+UBTMELM). Then, store the new model and element and restart the node.
The node is now ready to be provisioned and configured as described in sections 3.2.1 and 4.1.
UBX-19025268 - R06 Mesh models in u-connectXpress software Page 11 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
If using a proprietary model, define the model and its associated messages using AT+UBTMMOD and
define your opcodes using
AT+UBTMOPC, see appendix A for additional information.
2.3 Example server model in u-connectXpress
The code examples in this chapter implement the Generic OnOff Server as described in section 1.3.
The Generic OnOff server has the SIG Model ID - 0x1000, see the Mesh Model Specification [2].
# Model index 0, Generic OnOff Server
AT+UBTMMODG=0,1000
AT+UBTMELM=0,0
AT&W
AT+CPWROFF
UBX-19025268 - R06 Mesh models in u-connectXpress software Page 12 of 41
C1-Public
Implementing Bluetooth mesh with u-connectXpress software - Application note
3 Provisioning u-connectXpress modules
3.1 Introduction
A mesh node needs to be provisioned with the following:
• Network key(s)
• Device key
• Application key(s)
• Unicast Address
A u-blox mesh module can be provisioned either using AT commands or a smartphone application.
The configuration step is needed in order to give the u-blox module some information that is specific
to the elements and models configured on the module, such as:
• Publishing address for messages
• Connecting application keys to the model instances
• Subscription addresses
Provisioning and configuration is done after the node is loaded with the initial models.
The node goes through the following five states during the provisioning and configuration, as
described in Table 1.
State Description
0 Node completely empty. Add elements and opcodes followed by store and reboot (AT&W + AT+CPWROFF). This is
described in chapter 2.
1 Internal structures built. Needs a new reboot with AT+CPWROFF
2 Node can now be provisioned with AT commands or via GATT proxy (smartphone app)
3 Node is provisioned but needs to be configured for publish/subscribe. AT+UBTMCLR will bring node back to State 2
4 Node subscribes to at least one address. AT+UBTMCLR will bring node back to State 2
Table 1: State transitions during the setup of a mesh node
The AT commands shown in Table 1 are described in the u-connect AT commands manual [1] or as
specific mesh commands in Appendix A.
The u-connectXpress nodes are provisioned and configured either using AT commands over UART or
the nRF Mesh application [4] as described in the following sections.
After provisioning, the module has enough information to connect to the local mesh network but
needs further configuration regarding binding application keys to models, publishing and
subscription.
For the initial release of the u-connect software, the module must subscribe to at least one address
(could be a dummy address) to reach the configuration state 4 mentioned in Table 1.
UBX-19025268 - R06 Provisioning u-connectXpress modules Page 13 of 41
C1-Public
Loading...