This topic describes how to develop a private-label Bluetooth Mesh light product, and how to use a development board and the Cloud Intelligence app to test network provisioning and device control.
Background information
The IoT Platform supports the creation of Bluetooth Mesh products for private-label projects. If you develop your product based on the TG7100B chip, follow the instructions in Mesh light application firmware based on TG7100B to download the software development kit (SDK) V1.3.4, and then compile and run the firmware. If you develop your product based on the TG7120B or TG7121B chip, you must download and use SDK V1.3.5 or a later version. After you create a product, you must write the device certificate to the device. You can then use the Cloud Intelligence app (V3.8.0 or later) to provision and control the Bluetooth Mesh product.
Custom apps do not yet support network provisioning and control for Bluetooth Mesh products.
Create and configure a product
Create a private-label project.
Create a product. Enter a product name. Set Product Category to Electrical & Lighting/Light, Node Type to Device, and Connect to Gateway to Yes. Set Gateway Protocol to BLE Mesh.
Define product features. Select the hardware reset event, switch property, brightness property, color temperature property, and mode property.
Configure the human-computer interaction (HCI) for the product. Enable Use Public App to Control Product to allow verification using the Cloud Intelligence app. You must complete all six configuration steps. You do not need to select a Sharing Method. Only the preemptive method is currently supported.
Configure the device panel.
The `light_ctl` application supports only switch, brightness, color temperature, and mode control. You can build a simple panel as shown in the following figures.
Configure the network provisioning guide. In the upper-right corner, click I want to customize network provisioning to switch to the configuration interface.
Confirm that the provisioning method is Bluetooth Mesh Provisioning. Click the configuration items to configure the provisioning guide text and images. For more information, see the following figures. Default text is provided for the provisioning guide, which you can also customize. If you select each language, default multilingual text is automatically generated.
Configure multilingual settings and save the configuration.
Configure device testing. First, select a certified module or chip that corresponds to the chip you are using.
The Online Debugging feature is not supported for private-label projects that do not have a Mesh gateway.
Publish the product and purchase activation codes.
When you purchase activation codes, select Private-label Bluetooth Device.
Generate and burn device certificates
On the Device Debugging page, click Add Test Device to generate a test device certificate. You can enter a valid MAC address as the DeviceName, or leave it blank and the platform will assign one automatically.
NoteThe DeviceName and MAC address of a Bluetooth Mesh device must be the same. When you enter a valid MAC address as the DeviceName, do not use the same MAC address as the DeviceName for different products during the testing phase. This prevents potential conflicts. Ensure that each MAC address is unique.
Copy the Product ID, Device Secret, and Device Name as shown in the following figure.
Use the `set_tt` command to burn the device certificate to the development board.
set_tt 8xxxxx4 exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxd 28fa7aa4cac5 /* Enter the command. */ 8xxxxx4 exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxd 28fa7aa4cac5 /* Returned result. */Use the `reboot` command to restart the device. The device enters the network provisioning state.
Test adding a device with the Cloud Intelligence app
Open the Cloud Intelligence app, go to the Auto Discovery page, and add the device. The process is shown in the following figure.
Key device-side logs for app network provisioning:
Key logs for provisioning:
DEVICE:light APP VER:1.3.1 GenieSDK:V1.3.4-tg7100b PROUDUCT:ALI_AOS_TG7100B MAC:28:FA:7A:A4:CA:C5 ais pre init [000609]<I> GenieE:3 [000638]<I> SigE:11 [000648]<I> SigE:12 [000708]<I> GenieE:12 [proxy_connected]conn(0x2000b63c) reason 0x00 /* A proxy connection is established between the app and the device. */ [000939]<I> GenieE:11 [001604]<I> SigE:14 [001614]<I> SigE:4 [001624]<I> GenieE:55 [light_save_state]save 1 58982 20000 /* The default switch state is 1, brightness is 58982 (90%), and color temperature is 20000 (100%). */ [ALI_PROV][D] prov_invite , 1--->2 [001960]<I> GenieE:20 [ALI_PROV][D] prov_start , 2--->3 [ALI_PROV][D] prov_pub_key , 3--->4 [ALI_PROV][D] prov_confirm , 4--->5 [ALI_PROV][D] prov_random , 5--->6 [ALI_PROV][D] prov_data , 6--->7 [002606]<I> GenieE:21Key logs for device binding:
...... [004731]<I> GenieE:30 ...... [004965]<I> GenieE:23 ...... [005309]<I> GenieE:37Logs for reporting all device properties: The switch (Attr Type 0x0100) property value is 0x01 (on). The brightness (Attr Type 0x0121) property value is 0xE666, which is 90% of the maximum value 0xFFFF. The color temperature (Attr Type 0x0122) property value is 0x4E20, which is 100% of the maximum value 20000. The mode (Attr Type 0xF004) property value is 0x0000.
[009552]<I> User report data [009566]<I> SendTID(82) [TX] SRC: 0x1634 [TX] DST: 0xF000 [TX] msg size: 19 [TX] D4 A8 01 82 00 01 01 21 01 66 E6 22 01 20 4E 04 [TX] F0 00 00Logs for the power-on event: The event report (Attr Type 0xF009) indicates a power-on event (0x03).
[009787]<I> SendTID(84) [TX] SRC: 0x1634 [TX] DST: 0xF000 [TX] msg size: 7 [TX] D4 A8 01 84 09 F0 03
Test controlling the device with the Cloud Intelligence app
Control the device in the Cloud Intelligence app, as shown in the following figure.
Key device-side logs:
Turning on the light:
[RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0x8202 [RX] Payload size: 4 [RX] 01 C0 41 00 [116958]<I> SigE:20 [116968]<I> SIG mesg ElemID(0) +MESHMSGRX:6,820201C04100 /* The app sends a command to turn on the light: Generic OnOff Set message, Opcode 0x8202, OnOff 0x01. */ [117000]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0x128 [TX] msg size: 5 [TX] 82 04 01 01 41 /* The device replies with a Generic OnOff Status message, Opcode 0x8204, Target OnOff 0x01. */ [117065]<I> SigE:1 [117075]<I> SigE:12 [117106]<I> SigE:14 [117116]<I> SigE:4 [117126]<I> SigE:5 [117136]<I> SendTID(85) [117148]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0xF000 [TX] msg size: 11 [TX] D4 A8 01 85 00 01 01 21 01 66 E6 /* The device reports an Indication: TID 0x85, switch 0x01, brightness 0xE666 (90%). */ [117223]<I> GenieE:55 [117342]<I> RX Info [RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0xD501A8 [RX] Payload size: 1 [RX] 85 /* The device receives a Confirmation: TID 0x85, which confirms the previous report. */Turning off the light:
[RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0x8202 [RX] Payload size: 4 [RX] 00 C1 41 00 [126978]<I> SigE:20 [126988]<I> SIG mesg ElemID(0) +MESHMSGRX:6,820200C14100 /* The app sends a command to turn off the light: Generic OnOff Set message, Opcode 0x8202, OnOff 0x00. */ [127021]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0x128 [TX] msg size: 5 [TX] 82 04 01 00 41 /* The device replies with a Generic OnOff Status message, Opcode 0x8204, Target OnOff 0x00. */ [127086]<I> SigE:1 [127095]<I> SigE:12 [127946]<I> SigE:14 [127956]<I> SigE:4 [127966]<I> SigE:5 [127976]<I> SendTID(86) [127988]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0xF000 [TX] msg size: 11 [TX] D4 A8 01 86 00 01 00 21 01 00 00 /* The device reports an Indication: TID 0x86, switch 0, brightness 0. */ [128063]<I> GenieE:55 [light_save_state]save 0 58982 20000 /* Save switch state 0. */ [128259]<I> RX Info [RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0xD501A8 [RX] Payload size: 1 [RX] 86 /* The device receives a Confirmation: TID 0x86, which confirms the previous report. */Setting the light brightness: The platform sends a Light Lightness Set (Opcode 0x824C) message to set the brightness. The 16-bit Lightness field in the message indicates the brightness level. A value of 0xFFFF (65535) represents the maximum brightness (100%). In this example, 0xE666 (58982) is 90% of 0xFFFF (65535), and 0x828F (33423) is 51% of 0xFFFF (65535).
[RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0x824C [RX] Payload size: 5 [RX] 8F 82 C3 41 00 [146540]<I> SigE:20 [146550]<I> SIG mesg ElemID(0) +MESHMSGRX:7,824C8F82C34100 /* Set brightness to 51%: Light Lightness Set message, Opcode 0x824C, Lightness 0x828F. */ [146584]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0x128 [TX] msg size: 7 [TX] 82 4E 66 E6 8F 82 41 /* The device replies with a Light Lightness Status message, Opcode 0x824E. Brightness changes from 0xE666 to 0x828F. */ [146652]<I> SigE:1 [146662]<I> SigE:12 [147513]<I> SigE:14 [147523]<I> SigE:4 [147533]<I> SigE:5 [147543]<I> SendTID(88) [147555]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0xF000 [TX] msg size: 8 [TX] D4 A8 01 88 21 01 8F 82 /* The device reports an Indication: TID 0x88, brightness 0x828F (33423). */ [147624]<I> GenieE:55 [light_save_state]save 1 33423 20000 /* Save switch state 1, brightness 33423 (51%), color temperature 20000 (100%). */ [147850]<I> RX Info [RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0xD501A8 [RX] Payload size: 1 [RX] 88 /* The device receives a Confirmation: TID 0x88, which confirms the previous report. */Setting the light color temperature: The platform sends a Light CTL Set (Opcode 0x825E) message to set the color temperature. The 16-bit CTL Temperature field in the message indicates the color temperature. The value ranges from 800 (0x0320) to 20000 (0x4E20). A value of 0x0320 (800) represents the lowest color temperature (0%). A value of 0x4E20 (20000) represents the highest color temperature (100%). Intermediate values are calculated proportionally. For example, 0x3020 (12320) corresponds to 60%.
[RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0x825E [RX] Payload size: 9 [RX] FF FF 20 30 00 00 C5 41 00 [160694]<I> SigE:20 [160704]<I> SIG mesg ElemID(0) +MESHMSGRX:11,825EFFFF20300000C54100 /* Opcode 0x825F, Lightness 0xFFFF is ignored, color temperature 0x3020. */ [160744]<I> uv:0 lightness:65535 [160760]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0x128 [TX] msg size: 11 [TX] 82 60 8F 02 20 4E 8F 02 20 30 41/* The device replies with a Light CTL Status message, Opcode 0x8260, target color temperature 0x3020. */ [160836]<I> SigE:1 [160846]<I> SigE:12 [161696]<I> SigE:14 [161706]<I> SigE:4 [161716]<I> SigE:5 [161726]<I> SendTID(8A) [161738]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0xF000 [TX] msg size: 8 [TX] D4 A8 01 8A 22 01 20 30 /* The device reports an Indication: TID 0x8A, color temperature 0x3020 (12320). */ [161806]<I> GenieE:55 /* Light effect execution is complete. */ [light_save_state]save 1 655 12320 /* Save switch state 1, brightness 655 (1%), color temperature 12320 (60%). */ [162070]<I> RX Info [RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0xD501A8 [RX] Payload size: 1 [RX] 8A /* The device receives a Confirmation: TID 0x8A, which confirms the previous report. */Setting the light mode: The platform sends a Scene Set (Opcode 0x8242) message to set the light mode. The 16-bit Scene Number field in the message indicates the light scene mode. This is an enumerated data type. For example, a value of 0x0003 corresponds to reading mode, and a value of 0x0004 corresponds to cinema mode.
[RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0x8242 [RX] Payload size: 5 [RX] 03 00 C8 00 00 [182079][gatt_proxy_advertise]Connectable advertising deferred (max connections) /* The device already has a proxy connection. */ [182138]<I> SigE:20 [182148]<I> SIG mesg ElemID(0) +MESHMSGRX:7,82420300C80000 /* Opcode 0x8242, target scene number 0x0003, TID 0xC8, transition time 0, delay 0. */ [182181]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0x128 [TX] msg size: 3 [TX] 5E 03 00 /* The device replies with a Scene Status message, Opcode 0x5E, target scene number 0x0003. */ [182243]<I> SigE:1 [182252]<I> SigE:4 [182262]<I> SigE:5 [182272]<I> GenieE:55 /* Light effect execution is complete. */ [182360]<I> RX Info [RX] RSSI: 0 [RX] SRC: 0x128 [182395]<I> ReTID(8C), LR(1) [182409]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0xF000 [TX] msg size: 8 [TX] D4 A8 01 8C 04 F0 03 00 /* The device reports an Indication: TID 0x8C, mode property 0x0003 (reading mode). */ [RX] DST: 0x1634 [RX] OPCODE: 0xD501A8 [RX] Payload size: 1 [RX] 8C /* The device receives a Confirmation: TID 0x8C, which confirms the previous report. */
Test detaching a device with the Cloud Intelligence app
Detach the device in the Cloud Intelligence app, as shown in the following figure.
Key device-side logs for detaching from the Cloud Intelligence app (Prerequisite: A proxy connection is established between the Cloud Intelligence app and the network):
[RX] RSSI: 0 [RX] SRC: 0x128 [RX] DST: 0x1634 [RX] OPCODE: 0x8049 /* The device receives a Config Node Reset message, Opcode 0x8049, and is detached. */ [RX] Payload size: 0 [311956]<I> TX Info [TX] SRC: 0x1634 [TX] DST: 0x128 [TX] msg size: 2 [TX] 80 4A /* The device replies with a Config Node Reset Status message, Opcode 0x804A, confirming detachment. */ [312022]<I> GenieE:1 /* 1: GENIE_EVT_SW_RESET */ [proxy_disconnected]conn(0x2000b63c) reason 0x16 /* Disconnect the proxy connection. */ [315125]<I> GenieE:10 /* 10: AIS connection is disconnected. */ [315143]<I> GenieE:12 /* 12: GENIE_EVT_SDK_MESH_PBADV_START, start waiting for network provisioning. */NoteIn a network that contains only an app and no gateway, a device can receive the detach command only if a proxy connection exists between the app and a node in the network. This connection allows communication between the app and the device that is being deleted.
In a network that contains only an app and no gateway, if a device initiates a hardware reset (factory reset) and reports a hardware reset event, a proxy connection between the app and a node in the network is not guaranteed. Therefore, the app may not receive the hardware reset event from the device. The device clears its provisioning information and enters the network provisioning state. Because Mesh devices use a preemptive model, the app can directly provision the device again.
Test sharing and controlling a device with the Cloud Intelligence app
Share the device from the sharer's account and accept the share from the recipient's account, as shown in the following figure.
To control the device from the recipient's account, the recipient's app must also connect to the sharer's network through a proxy connection. If the sharer's network has only one node, only one proxy can be connected at a time. This means the sharer and the recipient cannot access the node's proxy service simultaneously. If the sharer's network has N devices, N user apps can theoretically access the network at the same time through the proxy services of the N nodes.
Test group control with the Cloud Intelligence app
Group control lets you synchronously control devices of the same model. You must have two or more devices of the same model (with the same Product Key) to add a group. This feature is currently supported only for light and socket products.
The following figures show how to add a group and use group control.
When you add a group, the Cloud Intelligence app configures a multicast address for the device. Therefore, the device can be added to the group successfully only if communication is possible between the app and the device. This communication can be established through a direct proxy connection or forwarded by another proxy node.
Key device-side logs for adding a group:
[RX] RSSI: 0 [RX] SRC: 0x133 [RX] DST: 0x2870 [RX] OPCODE: 0x801B /* The device receives a Config Model Sub Add message, Opcode: 0x801B. */ [RX] Payload size: 6 [RX] 70 28 12 E7 00 10 /* Element Address 0x2870, add multicast address 0xE712. */ [116470]<I> TX Info [TX] SRC: 0x2870 [TX] DST: 0x133 [TX] msg size: 9 [TX] 80 1F 00 70 28 12 E7 00 10 /* The device replies with a Config Model Sub Status message, Opcode: 0x801F, Status 0: Added successfully. */Key device-side logs for group control:
[RX] RSSI: 0 [RX] SRC: 0x133 [RX] DST: 0xE712 /* The destination is the multicast address 0xE712. */ [RX] OPCODE: 0x825E /* The device receives a Light CTL Set message, Opcode: 0x825E. */ [RX] Payload size: 9 [RX] 66 E6 20 30 00 00 2E 41 00 /* Target color temperature value 0x3020 (12320), which is 60%. */ [152135]<I> SigE:20 [152149]<I> SIG mesg ElemID(0) +MESHMSGRX:11,825E66E6203000002E4100 /* Adjust color temperature to 0x3020, which is 60%. */ [152251]<I> TX Info [TX] SRC: 0x2870 [TX] DST: 0x133 [TX] msg size: 11 [TX] 82 60 66 E6 20 4E 66 E6 20 30 41 /* The device replies with a Light CTL Status message through unicast. */ [152327]<I> SigE:1 [152337]<I> SigE:12 [gatt_proxy_advertise]Connectable advertising deferred (max connections) /* This node has a proxy connection and is a proxy node. */ [153229]<I> SigE:14 [153239]<I> SigE:4 [153249]<I> SigE:5 [153260]<I> SendTID(B1) [153271]<I> TX Info [TX] SRC: 0x2870 [TX] DST: 0xF000 [TX] msg size: 8 [TX] D4 A8 01 B1 22 01 20 30 /* The device reports an Indication: TID 0xB1, color temperature property 0x3020 (60%). */ [153340]<I> GenieE:55 [light_save_state]save 1 58982 12320 /* Save switch state 1, brightness 90%, color temperature 60%. */ [RX] RSSI: 0 [RX] SRC: 0x133 [RX] DST: 0x2870 [RX] OPCODE: 0xD501A8 [RX] Payload size: 1 [RX] B1 /* The device receives a Confirmation: TID 0xB1, which confirms the previous report. */Key device-side logs for deleting a group:
[RX] RSSI: 0 [RX] SRC: 0x133 [RX] DST: 0x2870 [RX] OPCODE: 0x801C /* The device receives a Config Model Sub Delete message, Opcode: 0x801C. */ [RX] Payload size: 6 [RX] 70 28 12 E7 00 10 /* Element Address 0x2870, delete multicast address 0xE712. */ [116470]<I> TX Info [TX] SRC: 0x2870 [TX] DST: 0x133 [TX] msg size: 9 [TX] 80 1F 00 70 28 12 E7 00 10 /* The device replies with a Config Model Sub Status message, Opcode: 0x801F, Status 0: Deleted successfully. */
Local timer
Local timers are not supported for private-label Bluetooth Mesh products.
Firmware OTA
The Cloud Intelligence app V3.10.0 and later supports firmware over-the-air (OTA) updates for private-label Bluetooth Mesh devices. Before you start an OTA update, make sure that your Cloud Intelligence app is updated to the required version.
Go to the Operations Hub of the IoT Platform.
Go to and select the product under the corresponding project.
Obtain the firmware file and version information for the update. After the firmware is compiled, the fota.bin file is the binary file for the OTA update.
The version number is the value of the PROJECT_SW_VERSION macro specified when compiling the OTA binary file. The version number format must follow the rules described in Version format.
Go to Firmware Upgrade and perform the following steps in the Firmware List window.
Click Add Firmware.
In the Firmware Version field, enter the OTA firmware version.
In the Signature Algorithm field, select MD5.
Under Select Firmware, click Upload Firmware and select the update binary file.
Click OK to add the firmware.
Run the Verify Firmware operation for the newly added firmware. For Device to be Verified, select the DeviceName of the test device.
Open the Cloud Intelligence app, go to the Device Settings page for your device, and click Upgrade Now to start the OTA update.
After the upgrade is complete, you can check the upgrade status in the Operations Hub.
View the key device-side logs.
GenieE:11 /* Establish an AIS connection. */ ais cmd:0x10 state:1 len:20 ais rsp err(0) p_ind(0x1fffd718) ais cmd:0x12 state:2 len:5 ais rsp err(0) p_ind(0x1fffd718) ais cmd:0x20 state:3 len:20 ais cmd:0x20 state:3 len:20 ais cmd:0x22 state:3 len:20 [3696.886]<I>AOSBT genie_ota_handle_update_request:ota ver:0x00010202 imgT:0 imgS:202568 maxS:217088 /* New firmware version and size. */ [3697.192]<I>AOSBT genie_ota_status_report:ota last[15] total[15] size[1984] err[0] … ota progress:10 … ota progress:20 … ota progress:30 … ota progress:40 … ota progress:50 … ota progress:60 … ota progress:70 … ota progress:80 … ota progress:90 … ota progress:100 [3732.236]<I>AOSBT genie_ota_status_report:ota last[1] total[1] size[202568] err[0] ais cmd:0x25 state:4 len:20 ais notify msgid:0 cmd:26 len:16 ais timeout disconnect /* Disconnect the AIS connection. */ proxy disconn:0x1fff94e8 reason:0x16 [ 0.004]<I>INIT Build:Oct 12 2021,16:34:29 /* Restart. */ [ 0.009]<I>INIT find 7 partitions [ 0.217]<I>AOSBT application_start:BTIME:Oct 12 2021,16:34:29 DEVICE:GenieLight APP VER:1.2.2 GenieSDK:V1.3.6 PROUDUCT:TG7120B MAC:28:FA:7A:A4:CA:C5 ais pre init …. GenieE:3
Notes for mass-produced devices
When you purchase activation codes, select Private-label Bluetooth Device.
For products in private-label projects, the IoT Platform can provide MAC address ranges.
If you use the MAC addresses provided by the IoT Platform, you can set Activation Code Generation Method to Auto-generate.
To upload your own MAC addresses to use as DeviceNames for device certificates, set Activation Code Generation Method to Batch Upload.
