KBA_BT_0502: Bluetooth Mesh Vendor Specific Model Example
06/166/2018 | 06:55 AM
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.
“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.
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.
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.
Program the provisioner project to a SLWRB4103A board, optionally, you can develop your own provisioner.
Create 2 projects in Simplicity Studio 4 named vmec (Vendor model example client) and vmes (Vendor model example server).
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.
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.
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
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.
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.
The article has been updated to the Bluetooth Mesh 1.3.0 GA SDK, and the images should load now. New feature - periodical update added.
Thanks,
Kevin
0
Hi,
I download the"vendor_model_client". the folder"log_module" is empty. when build the project, a error showing:
../app.c:5:10: fatal error: log.h: No such file or directory
#include "log.h"
compilation terminated.
make: *** [app.o] Error 1
thank you
0
Hi layne,
I had the same issue, the files are in the log_module folder on the github repo but they don't download when you download the whole thing (not sure why). You can just download them manually and put them back into the log_module folder of the project you are trying to build and it will work.
Here is a direct link to the subfolder on Kevin's github.
Best,
- Chris
1
Hi,
I used git and the log module is a submodule in the project, so you can type "git submodule update --init" or add "--recursive" when you clone the project. If you download it directly not using git, you can download the log module from here.
Thanks,
Kevin
0
Hi,
Thanks for this mesh vendor model example.
I have been able to modify the model in order to transfer an uint8_t buffer instead. Howerver, I can't send a buffer payload of 192 bytes or up to the (256-9) limit of the publish function. The publish function (gecko_cmd_mesh_vendor_model_publish) returns no errors, and actually works at the first or second attempt but after a short while no more messages are sent to the other nodes. When I limit the buffer to 191 bytes, all goes well.
Can you please help?
Thanks,
TC
0
I have noticed that what is actually happening is that the message is being split into two messages. The maximum payload of each messages seems to be 128 bytes.
- Is there a way to increase this limit in order to avoid message splitting?
- Alternatively, is there a way to find out is the received message is part of a larger message ?
I have since discovered that recv_evt has a "final" field to indicate if the message being received has been split.
Thanks,
TC
0
I got above error when i was trying to load the provisioning firmware to the SLWRB4103A, is anyone facing the same problem?
0
Hi,
The example has been updated to the latest Bluetooth Mesh 1.4.0-GA SDK.
Thanks,
Kevin
0
@WAI KIN KOH, can you please create a ticket to our support portal, there will be dedicated Studio support engineer to help you.
KBA_BT_0502: Bluetooth Mesh Vendor Specific Model Example
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.
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
Details about the example
There are 3 projects in the example.
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
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.
Figure 4. Provisioner Serial Terminal
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.
Hi,
The images do not load on this article.
Could you check it?
Thank you.
Hi,
The article has been updated to the Bluetooth Mesh 1.3.0 GA SDK, and the images should load now. New feature - periodical update added.
Thanks,
Kevin
Hi,
I download the"vendor_model_client". the folder"log_module" is empty. when build the project, a error showing:
../app.c:5:10: fatal error: log.h: No such file or directory
#include "log.h"
compilation terminated.
make: *** [app.o] Error 1
thank you
Hi layne,
I had the same issue, the files are in the log_module folder on the github repo but they don't download when you download the whole thing (not sure why). You can just download them manually and put them back into the log_module folder of the project you are trying to build and it will work.
Here is a direct link to the subfolder on Kevin's github.
Best,
- Chris
Hi,
I used git and the log module is a submodule in the project, so you can type "git submodule update --init" or add "--recursive" when you clone the project. If you download it directly not using git, you can download the log module from here.
Thanks,
Kevin
Hi,
Thanks for this mesh vendor model example.
I have been able to modify the model in order to transfer an uint8_t buffer instead. Howerver, I can't send a buffer payload of 192 bytes or up to the (256-9) limit of the publish function. The publish function (gecko_cmd_mesh_vendor_model_publish) returns no errors, and actually works at the first or second attempt but after a short while no more messages are sent to the other nodes. When I limit the buffer to 191 bytes, all goes well.
Can you please help?
Thanks,
TC
I have since discovered that recv_evt has a "final" field to indicate if the message being received has been split.
Thanks,
TC
Hi,
The example has been updated to the latest Bluetooth Mesh 1.4.0-GA SDK.
Thanks,
Kevin
@WAI KIN KOH, can you please create a ticket to our support portal, there will be dedicated Studio support engineer to help you.
Thanks,
Kevin