SILICON LABS QSG183 Blue Gecko Bluetooth SoC Wireless Starter Kit User Guide

SILICON LABS QSG183 Blue Gecko Bluetooth SoC Wireless Starter Kit

This document describes how to get started with Bluetooth mesh development using the Bluetooth Mesh Software Development Kit (SDK) and Simplicity Studio® 5 with a compatible wireless starter kit. It includes step-by-step instructions to demonstrate a basic Bluetooth mesh network. In this demo, three devices are provisioned as two Lights and one Switch. The mobile application allows the control of either a group of Lights or an individual. By pressing buttons on the Switch node, you can control the ON/OFF states and brightness for all lights in the same group. The demo is open-sourced and provides a good demonstration of a basic Bluetooth mesh network. This quick- start guide contains information about features specific to Bluetooth mesh specification version 1.1. If you are working with an earlier version of the specification, see QSG176: Bluetooth® Mesh Quick-Start Guide for SDK v2.x and 3.x. For a more elaborate networked lighting setup, see AN1438: Networked Lighting Control. The Bluetooth mesh mobile app is intended to demonstrate the Silicon Labs Bluetooth mesh technology together with the Bluetooth Mesh SDK sample apps. The mobile app is a reference app for the Bluetooth mesh mobile ADK, but it should not be taken as a starting point for customers to create their own mobile apps. For guidance on creating mobile apps with the Bluetooth mesh mobile ADK, refer to AN1200.1: iOS and Android ADK for Bluetooth® Mesh SDK 2.x and Higher. KEY POINTS

• Supports Bluetooth mesh specification version 1.1
• Introducing the Bluetooth mesh development environment
• Using WSTKs to demonstrate a basic Bluetooth mesh network
• Starting Bluetooth mesh application development in Simplicity Studio

Prerequisites

The Silicon Labs Bluetooth mesh lighting demonstration is designed to illustrate Bluetooth mesh operation without any need to config-ure or compile software. To get started with the Bluetooth mesh demo, do the following.

Order Development Kit(s)
The Blue Gecko Bluetooth SoC Wireless Starter Kit is the easiest and fastest way to start the evaluation and development of your own Bluetooth mesh applications. To get started with the Bluetooth mesh demo described in 4. Getting Started with the Bluetooth Mesh Demonstration Software, you need to have three (3) EFR32™ mainboards and radio boards. These can be obtained by ordering any of the Wireless Starter Kit options below.

• Option 1 : PN: SLWSTK6020B kit: https://www.silabs.com/development-tools/wireless/bluetooth/efr32bg-bluetooth-soc-starter-kit
• Option 2 : PN: SLWSTK6000B kit: https://www.silabs.com/development-tools/wireless/zigbee/efr32mg-zigbee-thread-starter-kit
• Option 3 : PN: SLWSTK6006A kit: https://www.silabs.com/development-tools/wireless/efr32xg21-wireless-starter-kit
• Option 4 : PN: SLWSTK6021A kit: https://www.silabs.com/development-tools/wireless/efr32xg22-wireless-starter-kit
• Option 5 : PN: xG24-PK6010A kit: https://www.silabs.com/development-tools/wireless/efr32xg24-pro-kit-20-dbm
• Option 6 : PN: xG27-PK6017A kit: https://www.silabs.com/development-tools/wireless/efr32xg27-pro-kit-8-dbm

Note: Some of these are starter kits with multiple boards included, and some have only one board included. This demo requires either EFR32BG27, EFR32MG27, EFR32BG24, EFR32MG24, EFR32MG21, EFR32BG13, EFR32MG13, EFR32BG12, or EFR32MG12 radio boards. EFR32MG22 and EFR32BG22 can be used but are suggested for Low Power Nodes only. If you already have the mainboards, you can purchase the required radio boards here.

Install Simplicity Studio and the GSDK
The Gecko SDK (GSDK) is the suite of Silicon Labs SDKs that includes the Bluetooth mesh SDK. To quickly get started with the GSDK and Bluetooth mesh, start by installing Simplicity Studio 5, which will set up your development environment. Go to: http://www.silabs.com/simplicity-studio to download the latest SSv5 version compatible with your computer’s operating system. Simplicity Studio 5 includes everything needed for IoT product development with Silicon Labs devices, including a resource and project launcher, software configuration tools, full IDE with GNU toolchain, and analysis tools. Alternatively, Gecko SDK may be installed manually by downloading or cloning the latest from GitHub. See https://github.com/Silicon-Labs/gecko_sdk for more information. This document focuses on development and use in the SSv5 environment. It assumes you are generally familiar with the SSv5 Launch-er perspective. SSv5 installation and getting started instructions, along with a set of detailed references, can be found in the online Simplicity Studio 5 User’s Guide, available on https://docs.silabs.com/ and through the SSv5 help menu.

Download the Mobile App
Download the Bluetooth Mesh by Silicon Labs Mobile App from the App Store or Google Play.

App Store
https://apps.apple.com/us/app/bluetooth-mesh-by-silicon-labs/id1411352948

Google Play
https://play.google.com/store/apps/details?id=com.siliconlabs.bluetoothmesh&hl=en

Note: The minimum requirement for the smartphone is Android 11 (API30) or iOS 14.

Documentation
Hardware-specific documentation may be accessed through links on the part Overview tab in Simplicity Studio 5.

SDK documentation, User’s Guides, and other references are available through the Documentation tab.

Key documentation for the Bluetooth mesh SDK is summarized as follows:

• QSG148: Getting Started with the Silicon Labs Bluetooth Mesh Lighting Demonstration
• AN1098: Understanding the Silicon Labs Bluetooth Mesh Lighting Demonstration
• UG103.14: Bluetooth® LE Fundamentals
• QSG139: Bluetooth® SDK Quick Start Guide
• UG144: EFR32BG1 2.4 GHz 10.5 dBm Radio Board User’s Guide
• UG122: BGM111 Bluetooth Module Radio Board User’s Guide
• UG250: Thunderboard Sense User’s Guide
• UG136: Silicon Labs Bluetooth® C Application Developer’s Guide
• UG118: Bluetooth® Profile Toolkit Developer’s Guide
• UG266: Silicon Labs Gecko Bootloader User’s Guide
• AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications
• AN1042: Using the Silicon Labs Bluetooth® Stack in Network Co-Processor Mode
• UG118: Bluetooth® Profile Toolkit Developer’s Guide
• UG266: Silicon Labs Gecko Bootloader User’s Guide
• AN1086: Using the Gecko Bootloader with Silicon Labs Bluetooth® Applications

Obtaining Support
You can access the Silicon Labs support portal at https://www.silabs.com/support through Simplicity Studio Resources or on the Simplicity Studio 5 welcome page under Learn and Support.

About the Bluetooth Mesh SDK

The Silicon Labs Bluetooth mesh stack is an advanced Bluetooth mesh protocol stack implementing the Bluetooth mesh standard. It can run alongside the Bluetooth Low Energy (LE) stack, using a common link layer, which allows using LE features in parallel. The Silicon Labs Bluetooth mesh stack is meant for Silicon labs Wireless Gecko SoCs and modules. The Silicon Labs Bluetooth mesh stack provides multiple APIs for the developer to access the Bluetooth mesh functionality. Two modes are supported.

1. Standalone mode (also referenced as SoC mode), where both the Bluetooth mesh stack and the application run in a Wireless Gecko SoC or module. The application can be developed with the C programming language.
2. Network Co-Processor (NCP) mode, where the Bluetooth stack runs in a Wireless Gecko and the application runs on a separate host MCU. For this use case, the Bluetooth stack can be configured into NCP mode where the API is exposed over a serial interface such as UART. For more information, see AN1259: Using the Silicon Labs Bluetooth® Stack v3.x and Higher in Network Co- Processor Mode.

Bluetooth Mesh Stack Features
The features of the Silicon Labs Bluetooth mesh stack are listed in the following table. For details on the features of the Bluetooth Low Energy stack, refer to QSG169: Bluetooth® Quick-Start Guide for SDK v3.x and Higher.

Table 2.1. Bluetooth Mesh Stack Features

Provisioning bearers

| PB-ADV PB-GATT

PB-Remote (Remote Provisioning, RPR)

GATT services| Proxy Provisioning

Security

| ECDH

AES-128 encryption, authentication, and obfuscation OoB authentication

Certificate-based provisioning Replay protection

Key refresh (reject list)

Host (NCP) interfaces

| 4-wire UART with RTS/CTS control or 2-wire UART without RTS/CTS GPIOs for sleep and wake-up management

Secure NCP option for data encryption between NCP target and host

Wi-Fi Coexistence| Using Packet Trace Arbitration (PTA)

Bootloaders

| Secure Gecko Bootloader supporting authenticated and encrypted updates over OTA (over GATT) or UART and Secure Boot. The Gecko Bootloader also supports flash partitioning and both internal and exter- nal (SPI) flash.

Non-volatile memory

| EFR32[B|M]G12, EFR32[B|M]G13: NVM3 or Persistent Store (PS). (Note: Example applications in the SDK use NVM3 by default.)

EFR32[B|M]G21, EFR32[B|M]G22, EFR32[B|M]G24, EFR32[B|M]G27: NVM3

Mesh 1.1 new features

| Device Firmware Update (Mesh DFU), Mesh Blob Transfer, Mesh Remote Provisioning, Certificate-Based Provisioning, Mesh Private Beacons, Enhanced Device Composition Data page, i.e. Large Composition Data, Configurable SAR timing, Proxy Service Solicitation, On-Demand Private Proxy

Table 2.2. Supported Models

Model Group: NA
Vendor| N/A| N/A
Model Group: Foundation
Configuration Server Configuration Client| 0x0000

0x0001

| All

BT Mesh Host Provisioner

Health Server Health Client| 0x0002

0x0003

| N/A N/A
Remote Provisioning Server Remote Provisioning Client| 0x0004

0x0005

| N/A N/A
Mesh Private Beacon Server Mesh Private Beacon Client| 0x000A

0x000B

| N/A N/A
Model| SIG Model ID| Example App (1)
---|---|---
Model Group: Generic
Generic OnOff Server Generic OnOff Client| 0x1000

0x1001

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller, PyBGAPI NCP Host Light

SoC Switch CTL, SoC Switch CTL Low Power, NLC Dimming Control, NLC Dimming Control Low Power, PyBGAPI NCP Host Switch

Generic Level Server Generic Level Client| 0x1002

0x1003

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller, PyBGAPI NCP Host Light

NLC Basic Scene Selector, NLC Dimming Control

Generic Default Transition Time Server Generic Default Transition Time Client| 0x1004

0x1005

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller N/A
Generic Power OnOff Server Generic Power OnOff Setup Server Generic Power OnOff Client| 0x1006

0x1007

0x1008

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller N/A
Generic Power Level Server Generic Power Level Setup Server Generic Power Level Client| 0x1009

0x100A

0x100B

| N/A N/A N/A
Generic Battery Server Generic Battery Client| 0x100C

0x100D

| N/A N/A
Generic Location Server Generic Location Setup Server Generic Location Client| 0x100E

0x100F

0x1010

| N/A N/A N/A
Generic Admin Property Server| 0x1011| N/A
Generic Manufacturer Property Server| 0x1012| N/A
Generic User Property Server| 0x1013| N/A
Generic Client Property Server| 0x1014| N/A
Generic Property Client| 0x1015| N/A
Model Group: Sensors
Sensor Server Sensor Setup Server

Sensor Client

| 0x1100

0x1101

0x1102

| SoC Sensor Thermometer, NLC Occupancy Sensor, NLC Ambient Light Sensor

SoC Sensor Thermometer, NLC Occupancy Sensor, NLC Ambient Light Sensor

SoC Sensor Client

Model Group: Times and Scenes
Time Server

Time Setup Server Time Client

| 0x1200

0x1201

0x1202

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller N/A
Scene Server Scene Setup Server Scene Client| 0x1203

0x1204

0x1205

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller, PyBGAPI NCP Host Light

SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller

SoC Switch CTL, SoC Switch CTL Low Power, NLC Basic Scene Selector, PyBGAPI NCP Host Switch

Scheduler Server Scheduler Setup Server Scheduler Client| 0x1206

0x1207

0x1208

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller N/A
Model Group: Lighting
Model| SIG Model ID| Example App (1)
---|---|---
Light Lightness Server

Light Lightness Setup Server Light Lightness Client

| 0x1300

0x1301

0x1302

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller, PyBGAPI NCP Host Light

SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller

SoC Switch CTL, SoC Switch CTL Low Power, PyBGAPI NCP Host Switch

Light CTL Server

Light CTL Setup Server Light CTL Client

Light CTL Temperature Server

| 0x1303

0x1304

0x1305

0x1306

| SoC Light CTL, PyBGAPI NCP Host Light SoC Light CTL

SoC Switch CTL, SoC Switch CTL Low Power, PyBGAPI NCP Host Switch

SoC Light CTL

Light HSL Server

Light HSL Setup Server Light HSL Client

Light HSL Hue Server

Light HSL Saturation Server

| 0x1307

0x1308

0x1309

0x130A

0x130B

| SoC Light HSL SoC Light HSL N/A

SoC Light HSL SoC Light HSL

Light LC Server

Light LC Setup Server Light LC Client

| 0x130F

0x1310

0x1311

| SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller SoC Light CTL, SoC Light HSL, NLC Basic Lightness Controller N/A
Model Group: Firmware Update
BLOB Transfer Server BLOB Transfer Client| 0x1400

0x1401

| SoC DFU Distributor N/A
Firmware Update Server Firmware Update Client| 0x1402

0x1403

| SoC DFU Distributor N/A
Firmware Distribution Server Firmware Distribution Client| 0x1404

0x1405

| SoC DFU Distributor SoC DFU Distributor

In Simplicity Studio 5, example app names are preceded with ‘Bluetooth Mesh -‘. Additional Models for Mesh 1.1 features: Remote Provisioning, Private Beacon, On-demand Private Proxy, SAR Configuration, Large Composition Data, Solicitation PDU Replay Protection List Configuration, Firmware Distribution, Firmware Update, BLOB Transfer.

Bluetooth Mesh Stack Limitations

available RAM and NVM3)
Concurrent segmented messages being re- ceived| Maximum of 255 (depending on available RAM)
Concurrent segmented messages being sent| Maximum of 255 (depending on available RAM)
Parallel provisioning sessions| Maximum of 1
Faults reported on the health server| Maximum of 5
Mesh Provisioner (EFR32)| Maximum number of supported nodes| 512
Maximum number of network keys per node| Maximum of 7
Maximum number of application keys per node| Maximum of 8
Replay protection list size| Maximum of 4096 (depending on available RAM and NVM3. Network size limit is still 512)
Parallel provisioning sessions| 1
Concurrent key refresh operations| Maximum of 16
Mesh Provisioner (ADK)| Replay protection list size (max network node count)| 32768
Maximum number of network keys per node| Maximum of 7
Maximum number of application keys per node| Maximum of 8
Parallel provisioning sessions| 1

• The node belongs to a single network, but the network may have multiple network keys to encrypt the traffic.

About Demos and Examples

Because starting application development from scratch is difficult, the Bluetooth Mesh SDK comes with a number of built-in demos and examples covering the most frequent use cases, as shown in the following figure. Demos are pre- built application images that you can run immediately. Software examples can be modified before building the application image. Demos with the same name as Software examples are built from their respective example. Click View Project Documentation to see additional information about some examples. This is also displayed on a readme tab when you create a project based on the example. Use the Demos and Example Projects switches to filter on only examples or only demos. Demos are also noted by the blue Demo tag in the upper left of the card .

Note: The demos and examples you see are determined by the part selected. If you are using a custom solution with more than one part, click the part you are working with to see only the items applicable to that part. Some functionality in these demos and examples depends on the features of the part, such as whether or not an LCD is included on the mainboard. To download and run a demo on your device, click [RUN] on the desired demo card. The demo automatically downloads to the selected device.

Bluetooth Mesh Examples and Demos
The following examples are provided. Examples with (*) in their names have a matching pre-built demo for some devices. Demos contain both a bootloader and the application. The compatible bootloader information provided for some examples is for later software development purposes. See Getting Started with Application Development for more information.

• The NCP examples require the BGAPI UART DFU Bootloader. The rest require one of the Internal Storage Bootloader (single image) variants, depending on device’s memory.

*Bluetooth Mesh – NCP Empty():** An NCP Target C application that makes it possible for the NCP Host Controller to access the Bluetooth Mesh stack via UART. It provides access to the host layer via BGAPI and not to the link layer via HCI.

• A separate example is available for EFR32xG22, which has limited RAM and flash, and therefore some of the stack classes are disabled by default.

Bluetooth Mesh – NCP Empty v1.1(*): An NCP Target C application that makes it possible for the NCP Host Controller to access the Bluetooth Mesh stack via UART. It provides access to the host layer via BGAPI and not to the link layer via HCI. Contains models from BT mesh specification 1.1.

*Bluetooth Mesh – SoC CSR Generator (Secure Vault)():** Certificate generating firmware example. The software generates the device EC key pair, the signing request for the device certificate, and other related data. The generated data can be read out by the Central Authority.

• *Bluetooth Mesh – SoC DFU Distributor():** Demonstrates the Firmware Distributor role based on the BT Mesh Model specification. Distributor is responsible for delivering new firmware images to the Target nodes and monitoring the progress of the firmware update.

• Bluetooth Mesh – SoC Empty : Demonstrates the bare minimum needed for a Bluetooth Mesh C application. The application starts Unprovisioned Device Beaconing after booting, then waits to be provisioned.

• Bluetooth Mesh – SoC Empty with Certificate-Based Provisioning support : Demonstrates the bare minimum needed for a Bluetooth Mesh C application that allows Certificate-Based Provisioning (CBP). The application starts Unprovisioned Device Beaconing after boot waiting to be provisioned to a Mesh Network.

• *Bluetooth Mesh – SoC Light CTL():** An out-of-the-box software demo where the LEDs of the mainboard/WSTK can be switched on and off, and their lighting intensity, color temperature, and delta UV can be set.

• The Thunderboard Sense 2 board can be switched on and off, and their lighting intensity, color temperature, and delta UV can be set.

• *Bluetooth Mesh – SoC Light HSL():** An out-of-the-box software demo where the LEDs of the mainboard can be switched on and off, and their lighting intensity, hue, and saturation can be set. The example also tries to establish friendship as a Friend node.

• The Thunderboard Sense 2 can be switched on and off, and their lighting intensity, hue, and saturation can be set.

• *Bluetooth Mesh – NLC Basic Lightness Controller():** An out-of-the-box software demo where the device acts as a Basic Lightness Controller in a Networked Lighting Control (NLC) system. The device listens to messages from other NLC devices, namely the Occupancy Sensor, Ambient Light Sensor, Dimming Control and Basic Scene Selector nodes.

• This project uses the RGB LED on the xG24 Dev Kit/Thunderboard Sense 2 board or LEDs on the mainboard/WSTK and display (if available).

• *Bluetooth Mesh – NLC Basic Scene Selector():** An out-of-the-box Software Demo where the device acts as a Basic Scene Selector in a Networked Lighting Control (NLC) system. Push Button presses control Basic Lightness Controllers in the network by scene recall requests.

• *Bluetooth Mesh – NLC Basic Scene Selector Low Power():** An out-of-the-box Software Demo where the device acts as a Basic Scene Selector in a Networked Lighting Control (NLC) system. It is optimized for low current consumption with disabled CLI, logging, and LCD. Push Button presses control Basic Lightness Controllers in the network by scene recall requests.

• *Bluetooth Mesh – NLC Dimming Control():** An out-of-the-box Software Demo where the device acts as a Dimming Control in a Networked Lighting Control (NLC) system. Push Button presses control Basic Lightness Controllers in the network by Generic Level Delta or Generic On/Off messages.

• *Bluetooth Mesh – NLC Dimming Control Low Power():** An out-of-the-box Software Demo where the device acts as a Dimming Control in a Networked Lighting Control (NLC) system. It is optimized for low current consumption with disabled CLI, logging, and LCD. Push Button presses control Basic Lightness Controllers in the network by Generic Level Delta or Generic On/Off messages.

• *Bluetooth Mesh – NLC Ambient Light Sensor():** An out-of-the-box Software Demo where the device acts as an Ambient Light Sensor in a Networked Lighting Control (NLC) system. The device measures ambient light and sends these measurements to the network. Properly configured NLC Basic Lightness Controllers then can act on the received data.

• *Bluetooth Mesh – NLC Ambient Light Sensor (Mock)():** An out-of-the-box Software Demo where the device acts as an ambient light sensor in a Networked Lighting Control (NLC) system. The device simulates ambient light measurements and sends these to the network. Properly configured NLC Basic Lightness Controllers then can act on the received data.

• *Bluetooth Mesh – NLC Occupancy Sensor():** An out-of-the-box Software Demo where the device acts as an Occupancy Sensor in a Networked Lighting Control (NLC) system. Push Button presses imitate people count changes which can control a properly configured NLC Basic Lightness Controller.

• *Bluetooth Mesh – SoC Sensor Client():** This example demonstrates the Bluetooth Mesh Sensor Client Model. It collects and displays sensor measurement data from a remote device(s) (e.g., btmesh_soc_sensor_server).

• *Bluetooth Mesh – SoC Sensor Thermometer():** This example demonstrates the Bluetooth Mesh Sensor Server Model and Sensor Setup Server Model. It measures temperature and sends the measurement data to a remote device (e.g., btmesh_soc_sensor_client).

• For certain devices, if available, it measures CPU temperature and uses that data as a temperature reading. Otherwise, it sends mocked temperature data to a remote device (e.g., btmesh_soc_sensor_client).

• *Bluetooth Mesh – SoC Switch CTL(): An out-of-the-box Software Demo where the device acts as a switch using the Light CTL Client Model. Push Button presses or CLI commands can control the lightness and color temperature of the LEDs on a remote device.
  Note:** This example is not compatible with the Dimming Control NLC Profile.

• *Bluetooth Mesh – SoC Switch CTL Low Power(): An out-of-the-box Software Demo where the device acts as a switch using the Light CTL Client Model. It is optimized for low current consumption with disabled CLI, logging, and LCD. Push Button presses or CLI commands can control the lightness and color temperature of the LEDs on a remote device.
  Note:** This example is not compatible with the Dimming Control NLC Profile.

• BT Mesh Host Provisioner : NCP-mode host application for testing host provisioning including Remote Provisioning, for use with the Bluetooth Mesh – NCP Empty 1.1 NCP-mode target application, located in app/btmesh/example_host/ btmesh_host_provisioner. Quick instructions: Compile with a POSIX-compatible toolchain with make parameters RPR=1 UI=1. See the README.txt included for more information.

Interoperability Test Demos
The interoperability (IOP) tests check if the Bluetooth mesh stack running on the board is compatible with a smartphone or not. These are test procedures containing several test cases for each Bluetooth mesh operation. The demos are meant to be used with the Bluetooth mesh mobile application.

• *Bluetooth Mesh – SoC IOP Test – Friend node():** Friend example for IOP test. This node acts as a friend for the low-power node and caches messages sent to it when the low-power node is sleeping.
• *Bluetooth Mesh – SoC IOP Test – LPN node():** Low power node example for IOP test. This node acts as a typical low-power device and sleeps most of the time. It needs a friend node to cache messages and forward them when polled.
• *Bluetooth Mesh – SoC IOP Test – Proxy node():** Proxy example for IOP test. This node forwards/relays messages between GATT and advertising bearers in the network.
• *Bluetooth Mesh – SoC IOP Test – Relay node():** Relay example for IOP test. This node acts as a relay, that is, if a node is out of range for another node, it relays messages between the two, provided the relay node is in range for both.
• *Bluetooth Mesh – SoC Provisioner Light Lightness():** An out-of-the-box software demo that can provision and configure nearby switch devices. The LEDs of the mainboard can be switched on and off, and their lighting intensity set, either by push buttons or by the provisioned switches.

NCP Host Examples
See also BT Mesh Host Provisioner, described above under Bluetooth Mesh Examples and Demos. btmesh_host_empty: Minimal host-side project structure, used as a starting point for NCP host applications. Use it with either the Bluetooth Mesh – NCP Empty v1.1 or Bluetooth Mesh – NCP Empty NCP target application flashed to the radio board. Access is to the NCP target stack layer via BGAPI and not to the link layer via HCI. The examples can be found in the GSDK install folder under app/ btmesh/example_host. The example requires a POSIX environment for compilation, such as Linux, macOS, or Windows MSYS2.

Python-Based NCP Host Examples
Python-based NCP host examples can be accessed at https://github.com/SiliconLabs/pybgapi-examples. These examples are meant to be used with PyBGAPI (https://pypi.org/project/pybgapi/). Use either the Bluetooth Mesh – NCP Empty v1.1 or Bluetooth Mesh – NCP Empty NCP target application flashed to the radio board.

GitHub Mesh Stack Features
For additional Mesh examples, see our GitHub repository which, provides examples for use-cases (such as Embedded Provisioner, Remote Provisioning, IV Update/Recovery, etc.) not covered by Simplicity Studio: https://github.com/SiliconLabs/bluetooth_mesh_stack_features.

Getting Started with the Bluetooth Mesh Demonstration Software

To get started with Bluetooth mesh demo software, you should have downloaded Simplicity Studio 5 (SSv5) and the Bluetooth Mesh SDK as described in the Simplicity Studio 5 User’s Guide, available online and through the SSv5 help menu. This section focuses on a light-switch demonstration using SDK 4.x examples. To see how to demonstrate mesh 1.1 Device Firmware Update functionality, see AN1370: Bluetooth® Mesh Device Firmware Update Example Walkthrough. To see how to demonstrate Remote Provisioning, see AN1368: Bluetooth Mesh Remote Provisioning. For building a network, based on the Networked Lighting Control profiles, see AN1438: Networked Lighting Control.

Preparing the Mainboard
The layout of the Wireless Starter Kit mainboard with the attached EFR32xG24B radio board is shown in the following figure:

1. Connect a Blue Gecko Radio Board to the mainboard. Use radio board BRD4187C EFR32xG24B 2.4 GHz (+20 dBm) (or similar) for this demo experience.
2. Connect the mainboard to a PC using the “J-Link USB” connector and the cable provided with the starter kit.
3. If not already set, turn the Power switch to the “AEM” position.
4. Repeat the above steps for the other two kits so all three kits are connected to your computer.

Verifying the Setup:

1. Check that the blue “USB Connection Indicator” LED (next to “J-Link USB”) turns on or starts blinking.
2. Check that the mainboard LCD turns on and displays a Silicon Labs logo.

Install the Demonstration Firmware
When the devices are connected to your PC with a USB cable, you can see three devices listed in the Debug Adapters view in Simplicity Studio. Select the J-link for a device to display demonstrations, examples, and documentation associated with the Bluetooth Mesh SDK. For this demo, you need to flash two devices with Bluetooth Mesh – SoC Light CTL and one device with Bluetooth Mesh – SoC Switch CTL. Go to the Example Projects & Demos tab. Click the target device in the Debug Adapters view and click [RUN] next to the desired demo (if available). If the demo is not available, click [CREATE] for an instance of the selected example, build it, and flash it. (In this case, the bootloader is required. See Getting Started with Application Development).

Use the Demo with an Android Smartphone
Make sure that all three devices have the status of unprovisioned on the device LCD screen before starting with the application. Open the Bluetooth Mesh App by Silicon Labs on your Android phone.

Follow the procedures below to set up and use the demonstration.

1. Go to provisioning view and tap scan to search for unprovisioned devices.
2. Select the Bluetooth mesh device you want to provision and configure.
3. Enter the descriptive name for the device and select the network you want to add it to.

Note: The Android application has a pre-generated subnetwork and appkey, but you can add more to the application if you like. The subnetwork and node database can be erased by either left-swiping or long-pressing the subnetwork in the main view and by pressing the trash icon.

The network and node database can be erased by long-pressing the network in the main view and by pressing the trash icon.

To configure the newly provisioned Bluetooth mesh device:

1. Right after provisioning, the Android application connects the proxy service on the node.
2. During configuration select the Bluetooth mesh features (proxy, relay, low power, and friend) that you want to enable. Notice that if you disable proxy, the node can no longer be directly accessed over GATT.
3. Select the Functionality (mesh model) that you want to enable.
4. Select the AppKey you want to associate the device with.

Note: The information view shows the Bluetooth mesh node features, such as Unicast address, UUID, and security keys as well as the supported mesh models. It can be used for debugging purposes.

To control a Bluetooth mesh node with the Android application:

1. Select the Subnet and AppKey you want to control.
2. The application will show the available nodes assigned to that appkey.
3. You can control the light:
   • Pressing the light bulb icon will send an On/Off message.
   • Moving the upper slider will send Light Lightness (dimming) messages.
   • Moving the medium and lower sliders will send CTL (temperature and delta UV) messages.
   • Pressing [STORE] stores the corresponding scene.
4. By going to devices view and either left-swiping or long-pressing a node you can then either delete or reconfigure the node.

Once the Android application has been used to provision a light bulb and a light switch to a subnetwork and appkey, the light switch (WSTK) can also be used to control the light bulb (WSTK) with the PB0 and PB1 buttons.

PB0 button

• Short press: Decrease Light Lightness by 10%
• Medium press: Decrease CTL (temperature) value
• Long press: Send Off message
• Very long press (5 seconds or more): Recall scene 1

PB1 button:

• Short press: Increase Light Lightness by 10%
• Medium press: Increase CTL (temperature) value
• Long press: Send On message
• Very long press (5 seconds or more): Recall scene 2

On devices with only one button, such as Thunderboard BG22:

• Short press: Decrease Light Lightness by 10%, wraps back to 100% after 0%
• Medium press: Decrease CTL (temperature) value, wraps back to maximum after minimum
• Long press: Toggle sending Off message and On message
• Very long press (5 seconds or more): Recall scene 1

Button presses during startup (power-on or reset) execute the following actions:

• On devices with two buttons: PB0 = Full factory reset; PB1 = Node reset
• On devices with one button: PB0 = Full factory reset

Use the Demo with an iOS Smartphone
Make sure that all three devices have the status of “unprovisioned” on the device LCD screen before starting with the Mobile App. Open the Bluetooth Mesh App by Silicon Labs on your iOS phone.

Follow the procedures below to set up and use the demonstration.

1. Go to the provisioning view and tap scan to search for unprovisioned devices.
2. Select the Bluetooth mesh device you want to provision and configure.
3. Enter the descriptive name for the device and select the network you want to add it to.

The subnetwork and node database can be erased by left-swiping the network in the main view and then pressing the trash icon.

To provision a Bluetooth mesh device and configure the node:

1. During provisioning select the subnetwork you want to add the device to.
2. During configuration select the Bluetooth mesh features (proxy, relay, low power and friend) that you want to enable. Notice that if you disable proxy, the node can no longer be directly accessed over GATT.
3. Select the AppKey you want to associate the device with.
4. Finally, select the Functionality (mesh model) that you want to enable.

Note: The information view shows the Bluetooth mesh node features, such as Unicast address, UUID, and security keys as well as the supported mesh models. It can be used for debugging purposes.

To control a Bluetooth mesh node with the iOS application:

1. Select the Subnetwork and AppKey you want to control.
2. The application will show the available nodes associated with that AppKey.
3. You can control the light:
   • Pressing the light bulb icon will send an On/Off message.
   • Moving the upper slider will send Light Lightness (dimming) messages.
   • Moving the medium and lower sliders will send CTL (temperature and delta UV) messages.
   • Pressing [STORE] stores the corresponding scene.
4. By going to the Devices view and tapping a node name you can reconfigure the node. To remove the node from the subnetwork, left-swipe it and press the trash icon.

Once the iOS application has been used to provision a light bulb and a light switch to a subnetwork and apply, the light switch (WSTK) can also be used to control the light bulb (WSTK) with the PB0 and PB1 buttons.

PB0 button

• Short press : Decrease Light Lightness by 10%
• Medium press : Decrease CTL (temperature) value
• Long press : Send Off message
• Very long press (5 seconds or more): Recall scene 1

PB1 button

• Short press : Increase Light Lightness by 10%
• Medium press : Increase CTL (temperature) value
• Long press : Send On message
• Very long press (5 seconds or more): Recall scene 2

On devices with only one button, such as Thunderboard BG22:

• Short press : Decrease Light Lightness by 10%, wraps back to 100% after 0%
• Medium press : Decrease CTL (temperature) value, wraps back to maximum after minimum
• Long press : Toggle sending Off message and On message
• Very long press (5 seconds or more): Recall scene 1

Button presses during startup (power-on or reset) execute the following actions:

• On devices with two buttons: PB0 = Full factory reset; PB1 = Node reset
• On devices with one button: PB0 = Full factory reset

The most common starting point for application development is the Bluetooth Mesh – SoC Empty example. This example demonstrates the bare minimum needed for a Bluetooth mesh C application. The application starts Unprovisioned Device Beaconing after boot waiting to be provisioned to a Mesh Network. All Bluetooth mesh devices must be loaded with the Gecko Bootloader as well as the application. While you are getting started, the easiest way to do this is to load any of the precompiled demo images that come with the bootloader configured as part of the image. When you flash your application it overwrites the demo application, but the bootloader remains. Subsequently, you may wish to build your bootloader, as described in UG266: Silicon Labs Gecko Bootloader User’s Guide for GSDK 3.2 and Lower and UG489: Sili-con Labs Gecko Bootloader User’s Guide for GSDK 4.0 and Higher. If the application requires a specific bootloader type, it is noted in the example description in 3. About Demos and Examples.

New Project creation is done through three dialogs:

• Target, SDK, and Toolchain Selection
• Example Project Selection
• Project Configuration

You can start a project from different locations in the Launcher Perspective, as described in the Simplicity Studio 5 User’s Guide. While you are getting started, we suggest starting from the File menu, as that takes you through all three of the above dialogs.

1. Select New >> Silicon Labs Project Wizard.
2. Review your SDK and toolchain. If you wish to use IAR instead of GCC, be sure to change it here. Once you have created a project it is difficult to change toolchains. Click [NEXT].
3. On the Example Project Selection dialog, filter on Bluetooth Mesh and select Bluetooth Mesh – SoC Empty. Click [NEXT].
4. On the Project Configuration dialog, rename your project if you wish. Note that if you change any linked resource, it is changed for any other project that references it. While you are getting started the default choice to include project files but link to the SDK is best. Click [FINISH].

When you create a Bluetooth mesh project, four tabs open automatically: a README file that describes the example, the GATT Config-urator (gatt_configuration.btconf), .the slcp or Project Configurator (.slcp), and the Mesh Configurator (dcd_con-fig.btmeshconf). Note that a Simplicity IDE perspective control is now included in the upper right of the screen. GATT configuration is the same for both Bluetooth and Bluetooth mesh projects. UG438: GATT Configurator User’s Guide for Blue-tooth® LE and Bluetooth Mesh describes how to configure the GATT database.

The Project Configurator and its associated Component Editor provide access to components. All the Bluetooth mesh functionality is provided as components. You can customize projects by installing or uninstalling the components based on the use cases and require-ments, and then configuring installed components using the Component Editor. The Bluetooth Mesh Component group shows the components specific to Bluetooth mesh projects.

The Bluetooth Mesh Configurator provides access to Device Composition Data (DCD). This contains information about a Bluetooth mesh node, the elements it includes, and the supported models. DCD exposes the node information to a configuration client so that it knows the potential functionalities the node supports and, based on that, can configure the node.

For more details on node configuration using the Project Configurator and Bluetooth Mesh Configurator, see UG472: Bluetooth® Mesh Stack and Bluetooth® Mesh Configurator User’s Guide for SDK v2.x and Higher. To build and debug your project click Debug (bug icon) in the upper left corner of the Simplicity IDE perspective. It will build and down-load your project, and open the Debug perspective. Click Play to start running you project on the device.

Simplicity Studio
One-click access to MCU and wireless tools, documentation, software, source code libraries & more. Available for Windows, Mac and Linux!

• IoT Portfolio
  • www.silabs.com/IoT
• SW/HW
  • www.silabs.com/simplicity
• Quality
  • www.silabs.com/quality
• Support & Community
  • www.silabs.com/community

Disclaimer
Silicon Labs intends to provide customers with the latest, accurate, and in- depth documentation of all peripherals and modules available for system and software implementers using or intending to use Silicon Labs products. Characterization data, available modules and peripherals, memory sizes, and memory addresses refer to each specific device, and “Typical” parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Labs reserves the right to make changes without further notice to the product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the included information. Without prior notification, Silicon Labs may update product firmware during the manufacturing process for security or reliability reasons. Such changes will not alter the specifications or the performance of the product. Silicon Labs shall have no liability for the consequences of the use of the information supplied in this document. This document does not imply or expressly grant any license to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any FDA Class III devices, applications for which FDA premarket approval is required or Life Support Systems without the specific written consent of Silicon Labs. A “Life Support System” is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant personal injury or death. Silicon Labs products are not designed or authorized for military applications. Silicon Labs products shall under no circumstances be used in weapons of mass destruction including (but not limited to) nuclear, biological, or chemical weapons, or missiles capable of delivering such weapons. Silicon Labs disclaims all express and implied warranties and shall not be responsible or liable for any injuries or damages related to the use of a Silicon Labs product in such unauthorized applications. Note: This content may contain offensive terminology that is now obsolete. Silicon Labs is replacing these terms with inclusive language wherever possible. For more information, visit www.silabs.com/about-us /inclusive-lexicon-project

Trademark Information
Silicon Laboratories Inc.®, Silicon Laboratories®, Silicon Labs®, SiLabs® and the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, EFM®, EFM32®, EFR, Ember®, Energy Micro, Energy Micro logo and combinations thereof, “the world’s most energy friendly microcontrollers”, Redpine Signals®, WiSeConnect, n-Link, ThreadArch®, EZLink®, EZRadio®, EZRadioPRO®, Gecko®, Gecko OS, Gecko OS Studio, Precision32®, Simplicity Studio®, Telegesis, the Telegesis Logo®, USBXpress®, Zentri, the Zentri logo and Zentri DMS, Z-Wave®, and others are trademarks or registered trademarks of Silicon Labs. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. Wi-Fi is a registered trademark of the Wi-Fi Alliance. All other products or brand names mentioned herein are trademarks of their respective holders.

Silicon Laboratories Inc. 400 West Cesar Chavez Austin, TX 78701 USA

• www.silabs.com

References

• Silicon Labs
• Simplicity Studio - Silicon Labs
• Simplicity Studio - Silicon Labs
• Overview - latest - Simplicity Studio 5 Users Guide Silicon Labs
• Overview - latest - Simplicity Studio 5 Users Guide Silicon Labs
• GitHub - SiliconLabs/bluetooth_mesh_stack_features: Bluetooth Mesh stack features. Go to https://github.com/SiliconLabs/application_examples
• Wireless Development Tools - Silicon Labs
• Technical Support - Silicon Labs

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>