In the last post in this series on Bluetooth mesh (found here), we provided a high-level overview of the nRF5 SDK for Bluetooth mesh. We also listed the different examples provided as part of the Nordic SDK. The most complete of these examples is the lighting example, and this is the one we’ll go forward with demoing and explaining. In this week’s post, we’ll go over building and running this example and understanding the different parts within it. In the upcoming posts, we’ll get into the details of the source code for each device.
Here’s a diagram showing the network and the devices we’ll be using within it:
Hardware and Software Requirements
The different hardware devices required in this example include:
- Two nRF52 boards (I will be using the nRF52840 development boards). One board will be programmed with the proxy server, and the other with the proxy client. We’ll be using proxy nodes to allow the mobile phone to discover and provision them (since mobile OS’s do not support communicating with non-proxy mesh devices).
- A mobile phone (iOS or Android) running the nRF Mesh mobile application.
- A PC to build the example code, interface with and program the development boards.
The different software packages required for building the examples are:
- Segger Embedded Studio (SES) (found here).
- Nordic nRF5 SDK version 15.0.0 (found here).
- Nordic nRF5 SDK for Mesh version 2.2.0 (found here).
- nRF Mesh iOS or Android app installed on your mobile phone (found here for iOS and here for Android).
The nRF5 SDK for Mesh requires nRF5 SDK version 15.0.0 to build. The steps needed to get this done are:
- Make sure you download both the nRF5 SDK for Mesh and the nRF5 SDK.
- Place the extracted folders (from the ZIP files) in the same folder. This is what my folder structure looks like:
└── nRF Mesh Project/
│ ├── nRF5_SDK_15.0.0_a53641a/
│ └── nrf5_SDK_for_Mesh_v2.2.0_src/
- By default, Segger Embedded Studio (SES) will pick up the nRF5 SDK if it’s placed alongside the nRF5 Mesh SDK. You can, however, place it in a different location and modify the SDK_ROOT macro from within SES to point to this different path (by following the instructions here).
The Light Switch Mesh Example
General Description of Operation
The basic operation of this example is to form a Bluetooth mesh network that consists of a smartphone (which is used as a provisioner) and two nRF52 development boards: one used as a light switch, and the other used as a light bulb. The provisioner (smartphone in this case) configures the whole network by:
- Assigning each device a unique address.
- Distributing the necessary network and application keys that are appropriate for each device.
- Configuring the mesh models for each device.
The nRF Mesh mobile application (which we’ll be using as the provisioner) gives us a lot of flexibility and control over each step of the provisioning process. This can be a bit confusing and overwhelming at first, but it serves as a great way to learn about the different concepts and operations within a Bluetooth mesh network.
Running the Example Step-By-Step
Before building and flashing the development boards with this example for the first time, we will need to erase the flash.
Erase the Development Boards
To do that follow these steps for each of the two development boards:
- First, connect only one of the development boards to your computer via the USB cable.
- Open Segger Embedded Studio (SES). If you haven’t gone through downloading and setting up SES yet, you might want to check out my previous tutorial first: The complete cross-platform nRF development tutorial
- Open one of the Solutions for the example: either the light switch proxy client or light switch proxy server:
│ ├── examples
│ ├── light_switch
│ ├── proxy_client
│ ├── light_switch_proxy_client_nrf52840_xxAA_s140_6_0_0.emProject
│ ├── proxy_server
│ ├── light_switch_proxy_server_nrf52840_xxAA_s140_6_0_0.emProject
- Navigate to the Target menu item and choose Connect J-Link:
- Next, navigate to the Target menu again and verify that J-Link is now connected. You will now see that the other options (such as Reset, Download, Erase All, and Download) are all available (not grayed-out anymore). Select Erase All. This operation will take a few seconds, up to a minute or so, but is necessary to make sure the development board is cleared of any previous older versions of the SoftDevice and data saved in memory.
- Wait for the operation to finish (usually when the following message shows up):
Building and Flashing the Example
Once you’re finished with erasing each of the development boards, you’re now ready to build the proxy server and proxy client projects and flash each of them to a development board.
- Make sure you have only one development board connected to your computer.
- Open one of the SES Solution files for either the light switch proxy client or light switch proxy server.
- Build and Flash the project. You can use the Build and Debug option under the Build menu for this.
- Once you’ve flashed the board and you’ve started the debugging process, you’ll see that the application halts at main() waiting for you to continue execution. You’ll also see the following in the debug terminal output window:
Light Switch Proxy Server:
Light Switch Proxy Client:
- At this point, you can simply turn off the development board (or disconnect it), and move on to flashing the other one. Turning on the development board later will run the application as it has already been flashed and no need to execute it from the computer anymore.
- If you see a message telling you that the RAM start can be adjusted to a different address, then you’ll have to modify the project macros to match the suggested values. You can do this by:
- Right-clicking on the Project name
- Clicking on Edit options
- From the Configurations drop-down menu, choose Common
- Select Linker
- Double-click on Section Placement Macros
- Modify RAM Start to match the value printed in the Debug Terminal window
- Make sure you have each development board labeled or at least recognized with the role it was flashed with (Client/Switch or Server/Light). This will make it easier to identify later when provisioning and when operating and testing the network.
- Once you have the development boards flashed with the server and client examples, you’re ready to move on to running the example and configuring the mesh network.
Configuring the Network (Provisioning)
Now, we’re ready to configure our mesh network and provision each of the light switch proxy server and proxy client devices.
- First, make sure you have the iOS or Android nRF Mesh app installed on your smartphone
- Launch the nRF Mesh app
- Click on Add new device
- The app will start scanning for devices that are unprovisioned and beaconing in the surrounding area
- You should see both the nRF5x Mesh Light and nRF5x Mesh Switch devices show up in the list
- Click on one of them in the list and then click on Identify
- Wait for the process to finish and populate the information, then hit Provision
- This process will take a few seconds, up to a minute or so (the progress will be shown at the bottom right-hand corner of the screen indicating the percentage completed)
- Repeat the provisioning process is finished for the other device
Here’s a video showing the process:
- Once you have both devices provisioned, you’re ready to configure them.
- From the Network tab, you’ll see the list of two devices: nRF5x Mesh Switch and nRF5x Mesh Light.
- Click on the nRF5x Mesh Switch. This is the device we want to configure to behave as a client (a light switch that controls other light bulbs in the network).
- Click on Generic OnOff Client. The GenericOnOff model is a Bluetooth SIG-defined model which the use case of a basic on/off switch (such as a light switch).
- Next, we want to bind the Client to an AppKey. Let’s choose the first one in the list (AppKey 1). Once it’s bound, you’ll see that it’s listed as Key index 0000.
- Since this is a Client, we want it to publish to an address. So, let’s define that. Select Publication Address and enter an address if not already set (I entered CEEF in my case). Once you enter it, you can hit Apply Publication.
- If successful, you should then see it listed under Publication Address.
- Now, let’s configure the Server. Go back to the Network tab and select the nRF5x Mesh Light device in the list.
- Click on Generic OnOff Server. Select AppKey Binding and choose the first key in the list (AppKey 1).
- Next, we want to set the Subscription Address since this device will behave as a Server, meaning it will listen and act on messages and commands sent to it from Clients.
- Enter the same address (CEEF in my case). You should now see it listed under Subscription Addresses.
Here’s a recording of this process:
Testing the Network Operation
- Now, you’re ready to test the operation of the network.
- Press Button #1 on the Client/Light Switch board.
- You should see that LED #1 on the other board (Server/Light Bulb) turns on.
- Press Button #2 on the Client/Light Switch board and it should turn LED #1 off on the other board (Server/Light Bulb).
In this post, we went through the basics of building, flashing and running the Light Switch mesh example on the nRF development kits. We only covered the basics of getting the network set up and tested. As you’ve probably noticed, the nRF Mesh mobile app is full of options and configurations, but it’s always a good idea to start with just a simple example and then expand into the different bells and whistles once we have a basic network set up.
In the following posts, we’ll start digging into the actual source code for the different types of devices (Client and Server Nodes) as well as into more details of the provisioning process.