Introduction

This article aims at helping those developers who want to use the vendor specific models in their Bluetooth Mesh products.

What are Models?

The concept ‘Model’ is defined in the section 2.3.6 of Mesh Profile Specification 1.0. It’s good to understand the concepts client and server model, in the following example, we will use this architecture.

What are vendor models?

It’s also defined in the section 2.3.6 of Mesh Profile Specification 1.0.

“Models may be defined and adopted by Bluetooth SIG and may be defined by vendors. Models defined by Bluetooth SIG are known as SIG adopted models, and models defined by vendors are known as vendor models. Models are identified by unique identifiers, which can be either 16 bits, for SIG adopted models, or 32 bits, for vendor models.”

Before reading this article, it’s recommended to read the article - Log System first. The output information will be shown from the RTT or serial terminal as they were introduced in that article.

Environments

• IDE – Simplicity Studio 4
• SDK – Bluetooth Mesh SDK 1.4.0 GA or newer
• Hardware – At least 3 Bluetooth Mesh compatible boards - EFR32xG12 or EFR32xG13 (x= M, B) based, SLWRB4104A and SLWRB4103A are recommended.
• Tools – J-Link RTT viewer or serial terminal, if using serial terminal, the parameters are as below:
  • Baud rate: 115200
  • Data bits: 8
  • Stop bit: 1
  • Flow control: False

Details about the example

There are 3 projects in the example.

• prov_bg12_130 – It’s the “SoC provisioner” designed to run on SLWRB4103A board directly and used to provision the vendor devices. For more information, go to https://www.silabs.com/community/wireless/bluetooth/forum.topic.html/appkey_deploymentfa-SJYZ.
• vendor_model_client – The vendor client model
• vendor_model_server – The vendor server model

Provisioning

The example supports both being provisioned by a standard provisioner, or being provisioned by the node itself by the test class command. The symbol PROV_LOCALLY in the file my_model_def.h decides which way the node uses. If it is defined, the nodes will provisioned themselves at boot time when they are unprovisioned, and the server node will publish to the group address the client node subscribes from and subscribe from the group address that the client node publishes to, the same for client node. If the symbol is not defined, they will send out the unprovisioned device beacon after boot when they are unprovisioned, waiting for a provisioner to provision and configure them.

Server and Client Model

Before introducing the server and client model, there are 3 concepts I want to introduce firstly. See figure 1, figure 2 and figure 3. This are the standard behaviors that the client and server models follow, which means all the opcodes defined later with the name “xxx Get/Set/Set unacknowledged” will use the “Reliable Get/Reliable Set/Unreliable Set”.

Figure 1. Reliable Get

Figure 2. Reliable Set

Figure 3. Unreliable Set

To be simple, there is only one group created and the provisioner configures both the client and server model to publish and subscribe to this group. Below are the definitions of the Client and server models

• Vendor ID - 0x1111, a 16-bit Company Identifier, use this value only for demo purpose.
• Server Model ID – 0x1111
• Client Model ID – 0x2222
• States
  • Temperature – 4 bytes (uint32) to store the temperature value with the unit milliCelsius or milliFahrenheit.
  • Unit
    • 0x1 – Celsius
    • 0x2 – Fahrenheit
  • Update period – The period that the vendor server updates the temperature to the client periodically. The format of this value aligns to the section 4.2.2.2 of Mesh Profile Specification 1.0.
• Opcodes
  • 0x1 – Temperature Get – it’s an acknowledged message used to get the Temperature Status of the server side.
  • 0x2 – Temperature Status – It can be the acknowledge to Temperature Get or an update to publishing group
  • 0x3 – Unit Get – it’s an acknowledged message used to get the Unit Status of the server side.
  • 0x4 – Unit Set – it’s an acknowledged message used to set the Unit Status of the server side.
  • 0x5 – Unit Set Unacknowledged – it’s an unacknowledged message used to set the Unit Status of the server side.
  • 0x6 – Unit Status – It can be the acknowledge to Unit Get or an update to publishing group
  • 0x7 – Update Period Get – It’s an acknowledged message used to get the Update Period Status of the server side.
  • 0x8 – Update Period Set – It’s an acknowledged message used to set the Update Period Status of the server side.
  • 0x9 – Update Period Set Unacknowledged – It’s an unacknowledged message used to set the Update Period Status of the server side.
  • 0xA – Update Period Status - It can be the acknowledge to Update Period Get or an update to publishing group
• Operations
  • For both sides – Keep PB1 pressing while boot will trigger a factory reset, which will erase all the stored data including the network key, application key, publication address, subscription addresses etc. and result in forcing the device to unprovisioned state.
  • Client Model
    • Short Press PB0 – send the Temperature Get to publishing group
    • Long Press PB0 – send “Update Period Set Unacknowledge” with sequent parameters as below
      • 300ms
      • Off
      • 2s
      • Off
      • 10s
      • Off
      • 2min
      • Off
      • 10min
      • Off
    • Short Press PB1 – send the Unit Get to publishing group
    • Long Press PB1 – send "Unit Set(Celsius)" and "Unit Set Unacknowledged(Fahrenheit)" back and forth.
• Server Model
  • Press PB0 – Measure the current temperature and send Temperature Status to publishing group
  • Press PB1 – Send the Unit Status to the publishing group

Running the example

This example is originally designed to use SLWRB4104A as the mesh nodes and SLWRB4103A as the provisioner. If you don’t have them, you probably need to migrate the existing projects to fit your boards. Below steps assume that you have the desired boards, and the migration effort is not covered. Follow below steps to run this example.

1. Download the attachment and extract it. The provisioner project is available from https://github.com/KevinFuSilabs/vendor_model_provisioner, Import the provisioner project to your Simplicity Studio. Step 2, 6 shall be passed if using the self-provision method.
2. Program the provisioner project to a SLWRB4103A board, optionally, you can develop your own provisioner.
3. Create 2 projects in Simplicity Studio 4 named vmec (Vendor model example client) and vmes (Vendor model example server).
4. Copy the (ROLE)_app.c, (ROLE)_app.h, main.c, my_model_def.h and self_test.h to the corresponding project. Open the $(PROJECT_NAME).isc file and click the "+" on the right of Vendor models label to add a vendor model to the project, set the ID of server model to 0x11111111, and the client model to 0x22221111, then click generate button on the top right corner. Build and program to at least one client and one server boards.
5. Open corresponding number of RTT terminals or the serial terminals and connect them to your nodes. And Open a serial terminal connected to the provisioner.
6. The nodes should have started sending unprovisioned beacons, and you should get message like figure 4 shows in the provisioner serial terminal. Press PB1 to start provisioning and configuring if this is your device waiting to be provisioned and configured, whereas, PB0 to ignore.

Figure 4. Provisioner Serial Terminal

7. Make sure that all the nodes are properly provisioned and configured. If there is no problem with the provisioning and configuring, you should get the “configuration complete” message from the serial terminal, and it starts to scan for other unprovisioned beacons.
8. Press the keys to verify the processes. If everything goes well, you should be able to see the logging from RTT like below. Figure 5 and figure 6 are a pair of nodes in the same network, and they are the logging for the actions – Pressing PB1 on client -> PB0 on client -> PB1 on server -> PB0 on server.

Figure 5. Client RTT Terminal

Figure 6. Server RTT terminal

Words in the end

This article doesn't aim at introducing the soc provisioner, the reason why we use it is because the Bluetooth Mesh app doesn't support configuring the vendor models yet. Some codes in the provisioner project are hardcoded to fix value so it can't be used as a generic provisioner. I know my colleague has an updated version covering both the SIG and vendor models, please navigate to above link for more information.

This example implements the periodical status update feature in the application layer. This can also be implemented using the model publication state in configuration server, section 4.2.2 of Mesh Profile Specification 1.0. I prefer to implement it in the application layer since only the nodes implementing the configuration client can modify the period value in publication value if using the configuration server, however, the client nodes probably don't.