Bluetooth Mesh Lighting SDK

This topic describes the demo for developing Telink TLSR825x-based Bluetooth mesh lighting products and how to set up the debugging environment.

The following diagram shows the development architecture of lighting products.

Things to note

• Do not change the original denotation of any control commands.
• Do not add any control commands other than these mentioned in this topic. If you have specific requirements for control commands, contact Tuya’s technical support.

Data point (DP) introduction

Standard Bluetooth mesh commands

Tuya Developer Platform takes standard Bluetooth mesh commands as custom commands. When the mobile app and gateway communicate with the device, the custom commands will be converted into standard Bluetooth mesh commands.

Note: The standard DP function for Bluetooth mesh is void tuya_mesh_data_recv_callback(uint16_t src_addr, uint16_t dst_addr, uint32_t opcode, uint8_t *data, uint16_t data_len, uint8_t ttl). For more information about the standard Bluetooth mesh commands, see Mesh Model Specification.

Tuya’s DP definition

• DP IDs 1 to 30 represent generic features that apply to most product categories. These DP IDs are unique.

• DP IDs 31 to 50 represent newly introduced features that apply to most product categories. These DP IDs are unique.

• DP IDs 51 to 100 represent features that apply to specific product categories.

• DP IDs 101 to 200 represent user-defined features that apply to custom solutions.

• DP IDs 201 to 250 represent system features that can be reused for electrical products and sensors.

  Note: You can add the custom DP in the function void app_tuya_vendor_light_dp_data(u8 *par, int par_len).

Note: The raw protocol for DP 6 scene and DP 8 music sync is relatively long, which is not friendly to Bluetooth mesh. Tuya compresses the protocol in the application and gateway layers. When the device receives these two DPs, it needs to decompress the protocol before using it. This step has been implemented in the SDK.

DP of scene

Raw data (same as the scene data of the Wi-Fi protocol)

• Data type: string

• Value: 0011223344445555666677778888

  Value	Description
  00	The scene number
  11	The interval for transitions between units (0–100)
  22	The interval between each unit (0–100)
  33	The unit change mode (static, gradient, and jumping)
  4444	H (hue: 0–360, 0x0000–0x0168)
  5555	S (saturation: 0–1000, 0x0000–0x03E8)
  6666	V (value: 0–1000, 0x0000–0x03E8)
  7777	Brightness (0–1000, 0x0000–0x03E8)
  8888	Color temperature (0–1000, 0x0000–0x03E8)

  Note: The scene number indicates the number of units in one scene. Up to eight units are allowed.

• The compressed Bluetooth mesh protocol

  Common header				The first unit
  0000 11xx	x222 2222		Colored light	3xx4 5566	4444 4444	5555 5555	6666 6666
  			White light	3xxx 4455	4444 4444	5555 5555	xxxx xxxx

  	Value	Description
  	0	The scene number: a 4-bit value, ranging from one to eight.
  	1	The unit change mode: a 2-bit value, representing static, gradient, or jumping mode.
  	2	The interval between each unit: a 7-bit value, ranging from 0 to 100, which shares the same data format with the interval for transitions between units.
  	3	Color mode: a 1-bit value, which can be 0 (white light) or 1 (colored light). The data of the scene unit varies depending on color modes.
  Colored light	4	Hue: a 9-bit value.
  Colored light	5	Saturation: a 10-bit value.
  Colored light	6	Value: a 10-bit value.
  White light	4	Brightness: a 10-bit value.
  White light	5	Color temperature: a 10-bit value.
  White light	6	Null

Music sync

Raw data (same as the scene data of the Wi-Fi protocol)

• Data type: string

• Value: 011112222333344445555

  Value	Description
  0	The change mode (0: jumping. 1: gradient.)
  1111	H (hue: 0–360, 0x0000–0x0168)
  2222	S (saturation: 0–1000, 0x0000–0x03E8)
  3333	V (value: 0–1000, 0x0000–0x03E8)
  4444	Brightness (0–1000, 0x0000–0x03E8)
  5555	Color temperature (0–1000, 0x0000–0x03E8)

• The compressed Bluetooth mesh protocol

  1st byte	2nd byte	3rd byte	4th byte
  01xx 2233	1111 1111	2222 2222	3333 3333

  Value	Field	Length (byte)	Description
  0	The change mode	1	8-bit value: 0HxxSSVV For the most significant bit, 0 indicates jumping and 1 indicates gradient.
  1	H	1	The value ranges from 0 to 360 and 360 is 9-bit. 8 bits make 1 byte, so the 1 bit is borrowed from the value of change mode as the most significant bit.
  2	S	1	The value ranges from 0 to 1,000 and 1,000 is 10-bit. 8 bits make 1 byte, so the 2 bits are borrowed from the value of change mode as the most significant bit.
  3	V	1	The value ranges from 0 to 1,000 and 1,000 is 10-bit. 8 bits make 1 byte, so the 2 bits are borrowed from the value of change mode as the most significant bit.

Commands for remote controls

The remote controls send DP commands with the function void ty_light_remote_dp_data(u8 * par, int par_len).

Directory structure

You can download the SDK and demo tuya_smesh_sdk_tlsr825x_light from GitHub. The following table provides an introduction to files included in the SDK.

Main functions

JSON file introduction

Tuya provides JSON templates for your reference.

• 1c_bt3l_pwm_V1.0.json
• 2cw_bt3l_pwm_V1.0.json
• 3rgb_bt3l_pwm_V1.0.json
• 3rgb_bt3l_sm726eb_V1.0.json
• 3rgb_bt3l_sm2135e_V1.0.json
• 4rgbc_bt3l_pwm_V1.0.json
• 4rgbc_bt3l_sm726eb_V1.0.json
• 4rgbc_bt3l_sm2135e_V1.0.json
• 5rgbcw_bt3l_pwm_V1.0.json
• 5rgbcw_bt3l_sm726eb_V1.0.json
• 5rgbcw_bt3l_sm2135e_V1.0.json

Debugging operation

Environment setup

This section uses Telink’s Bluetooth chip as an example to describe debugging environment setup on Windows.

1. Check out IDE for TLSR8 Chips and install Telink IDE on your computer.

2. Copy doc\tools\jq-win64.exe to C:\TelinkSDK\bin\.

3. Add the following four paths to the system environment variable.

   • C:\TelinkSDK\opt\Vim\vim73\
   • C:\TelinkSDK\opt\tc32\bin\
   • C:\TelinkSDK\bin\
   • C:\TelinkSDK\opt\tc32\tools\

4. Check out Burning and Debugging Tools for all Series and install the tool on your computer.

5. (Optional) Install git-for-win.

   Note: If you are a novice to Git, we recommend you use the default installation wizard. If you already have git-bash, you can run the shell script without the installation of Git.

Build

1. (Optional) If you do not have the file _build, you can run bash cmake.sh mesh_light tlsr825x_smesh in common/tools to generate the _build. Remember to name the build file.

2. You can use the run.sh script in the app/mesh_common/_build to compile and download code.

   bash run.sh build/flash [demo.json]
   

   This script can be converted to _build/base_oem_config.h based on [demo.json]. The macros are used to generate different applications using the same application code. This way, when you want to edit information such as firmware name, version number, and PID, you can edit the JSON file instead of the code.

• If editing [demo.json] can address your needs, do not modify the application code considering the risk of firmware failure.
• If editing the application code is necessary, you can copy and rename the file and edit it. Generally, modification to the application code for some simple features is not recommended. Consider improving the [demo.json] to have features refined.[]

  $ cd app/mesh_common/_build

  $ bash run.sh build 5rgbcw_bt3l_pwm_V1.0.json 

Flash

1. Connect the SWM header on the board to the SWM header on the Telink’s writer that is connected to your computer with a USB cable. Your development board is powered independently and grounded.

   

2. Open the Telink Burning and Debugging Tool (BTD), select 8258 chip, and click SWS to configure the writer.

   This enables the writer to download code to 8258 chips. Typically, SWS is executed once.

   

3. Run run.sh to write the bin file to your board.

   $ bash run.sh flash 5rgbcw_bt3l_pwm_V1.0.json 
   

   Note: run.sh supports build, flashing, flash after erasing all data, and cleaning build information.

Get the PID and license

All the devices must be authorized with the license before they can be connected to the Tuya Cloud. Contact the technical support and request the license.

Create a light product on the Tuya Developer Platform and get the PID. When you complete the steps below, the PID feature is completed. Otherwise, errors might occur.

1. Log in to the Tuya Developer Platform and create a product. For more information, see Create Products.

   For example, select the Light Source and Multicolor Light (Bluetooth) and complete the product information.

   

2. Add the functions and select a control panel.

   

3. In the Hardware Debugging, choose the network modules.

   

4. So far, the product configuration is completed.