Telink B80 2.4G Lighting SDK Development Guide
SDK overview
This SDK provides users with remote control lights based on B80 series chips, including remote-light, remote-RGB light, and remote-beacon. Users can develop application layer code and adapt pcb boards based on these demo codes.
SDK file structure
The current SDK file structure is shown as below.
chip
The chip mainly contains the driver and boot code of the B80 chip, where the boot code contains three modes, the boot folder contains cstartup_flash.S, cstartup_otp.S, cstartup_sram.S, which correspond to the macros MCU_STARTUP_FLASH, MCU_ STARTUP_OTP, MCU_STARTUP_SRAM. You can control different modes by configuring the corresponding macros in the IDE.
cstartup_flash.S: flash mode, the burning program runs in flash, you can choose this mode when the development board equips with external flash.
cstartup_otp.S: otp mode, the burning program runs in otp, as B80 eventually uses built-in otp, the otp option will be used for the final mass production products.
cstartup_sram.S: sram mode, you can use this mode for debugging when there is no external flash, and you need to do simple debugging to avoid the otp can't be changed after it is written.
Inside the Driver folder corresponds to the driver file for B80 and the library for rf and pm.
common
The div_mod.s defines some generic interfaces, such as assembly interfaces for multiplying large numbers. The rest of the functions are generic type definitions and interfaces like memcpy, memcmp and so on.
demo
Inside the demo folder is the defined code for the user layer.
The common folder contains the folder options that are common to all compilation options. The rest of the folders correspond to different compilation branches.
project
The project folder is the folder for this project, where the .cproject and .project file are the corresponding project files, .boot and .link are the link files, which are not recommended to be modified by the customer, the proj_lib is the path where the library is placed, and the folders in it are the files generated by the compilation, for example, LIGHT.bin and LIGHT.lst will be generated inside the LIGHT folder.
Other folders
The doc folder corresponds to the release version information, and the tool folder corresponds to some packing tools.
Demo project
The B80 remote light SDK is a compilation branch for customer development, which allows users to observe the visual effects through demo operations and also to modify on the demo code to complete the development of their own applications.
SDK sending and receiving packets and handling of pairing
The following description of the pairing and sending/receiving packet process is currently based on the remote-light mode.
SDK pairing process introduction
Parameters of Tx transmission.
Transmit channels: 2401MHz, 2424MHz, 2451MHz, 2476MHz, 4 signals.
Transmit accesscode: {0x71,0x76,0x51,0x39,0x95}
Transmit power: 11.46dbm
SDK pairing principle:
Within 5s of power up, short press the on light key of a group once, the pairing will be completed. The LED flashes 3 times after pairing success.
Within 5s of power up, short press the on light key of a group for consecutive 5 times (interval less than 500ms), it will finish clearing the pairing information. The LED flashes 5 times after clear pairing information successfully.
Within 5s of power up, if a non-light-on key command is received, it will exit pairing mode and enter the normal state.
Flowchart of SDK pairing is as below.
Introduction to the flow of SDK sending and receiving packets
Take the remote project as an example. The description of the function for sending packet is as below.
void package_data_init_func(void)
Sending packet data initialization. Configure VID information, reassign a specific otp address or PID of the remote, and get the saved information from the analog register.
void package_data_set_newcmd(unsigned char key_value,unsigned char* para)
Configure the new command. Update the rf_seq_no, control_code and control_code parameters.
void package_data_send_func(void)
Call the rf module to send the command out. (remote send TTL=5) (The command is normally repeated 15 times unless it is updated to a new command halfway through.)
void package_data_store_func(void)
Store the group&rf_seq_no information of the command code to the analog register. Prevents loss of information at a wake-up after deep sleep.
The logic flow chart for the sending packet is as below.
Take the light project as an example. The function that forwards the command is described as below.
Light forwards the received remote control commands to other light devices.
void rfc_send_relay_pkt(void)
Forward incoming remote commands, ttl minus 1, to prevent infinite forwarding.
The logic flow chart for the sending packet is as below.
Interface description for packet receiving.
void sys_status_process(void)
The interrupt function "void light_irq_handler(void) determines that the data received is a new command from the paired remote. The corresponding control command is then processed in the function "void sys_status_process(void)".
The logic flow chart for packet receiving is as below.
remote matrix key scan
Configuration of the number of rows and columns of the key matrix:
#define KB_COL_NUM 5
#define KB_ROW_NUM 3
Pin configuration of key rows and columns.
gpio_column[KB_COL_NUM]={GPIO_PB0,GPIO_PB1,GPIO_PB4,GPIO_PB5,GPIO_PB6};//Column IO for the matrix
gpio_row[KB_ROW_NUM] ={GPIO_PD3,GPIO_PD6,GPIO_PA0};//Row IO for the matrix
Key configuration:
key_table[KB_ROW_NUM][KB_COL_NUM] //Key table
Key scan principle：When a key is connected to an IO port at both ends, one IO port is set high and the other is set low, when the key is pressed the high IO port level is pulled low, the other end is still low, at this time the detection IO port value is two low levels.
EEPROM
The EEPROM is currently built into the B80 chip internally to store information about paired pids and groups, and is 256bytes in size.
void e2prom_init()；
Configure the initialization of the EEPROM, and the initialization of the internal EEPROM's pins.
void e2prom_write (u8 adr, u8 *p, int len);
The adr is the internal address of the EEPROM, p is the header pointer to the write buffer, and len is the length of the write to the EEPROM.
void e2prom_read (u8 adr, u8 *p, int len);
The adr is the internal address of the EEPROM, p is the header pointer to the read buffer, and len is the length of the read to the EEPROM.
LED
The principle of luminance increase and decrease keys and chroma increase and decrease keys tuning the LED change is as below.
The light is currently preset to 10 levels of variation, each parameter is stored in the arrays led_luminance_value and led_chroma_value. After receiving the luminance or chroma change command, the next parameter is jumped to as the target value of the LED. After the LED gradually change to the target value, it will no longer change.
LED color gradual change process is as below.
Check every 5ms, when there is a difference between the set target luminance or chroma and the current value, adjust the current parameter in a single step (luminance single step change to 10, chroma single step change to 1, not enough to align the target value), until the adjustment to the target value. The process of color gradient is completed.
SDK debugging instructions
Tdebug
Debug by looking at the corresponding variables through the wtcdb tool.
Serial print debugging instructions
#define DEBUG_MODE 1
The print function is turned on and off via DEBUG_MODE.
#define PRINT_BAUD_RATE 115200 //1M baud rate,should NOT be bigger than 1Mb/s
#define DEBUG_INFO_TX_PIN GPIO_PD3
Configure the baud rate of the serial port via PRINT_BAUD_RATE and the interface for printing via DEBUG_INFO_TX_PIN. The printf is used as the interface for standard printing and printhex prints arrays.
DEBUG_MODE =0 turns off the print mode, and during the compilation process, no related functions are programmed and printed. The customer can turn it on during the debugging phase, and it is recommended to turn it off to save ram and code in the mass production program.
SDK code description
The three modes, remote-light, remote-rgb light, and remote-beacon, are introduced in detail in this chapter. The initialization interface and the processing inside the main loop are introduced using the light project as an example.
REMOTE
Introduction of initialization function interface for REMOTE
led_gpio_init(LED1)
Initialize the LED pins. Only 1 pin can be initialized at a time.
keyscan_gpio_init();
Initialize key matrix pins.
package_data_init_func()
Initialize the sending packet data, includes the solidified VID, the PID read from the OTP, and the group&rf_seq_no recovered from the analog register.
rfc_init_func()
Initialize the RF module. Configure the RF module as tx_mode for sending commands.
Loop interface introduction for REMOTE
unsigned char keyscan_scan_func(void)
It scans the key matrix and returns key values. Send control commands by key press. (Lift OFF command key to start sending, long press OFF to send night light mode command, color temperature and luminance change support long press more than 320ms to send new command continuously, press other command keys to send commands.)
LIGHT
Introduction of initialization function interface for LIGHT
rfc_init_func()
Initialize the RF module. Configure the RF module to Rx_mode for receiving remote commands.
led_pwm_init_func()
Configure the LED pin to PWM function. Subsequently, change the LED luminance and chromaticity as well as the on and off state by changing the PWM waveform.
led_init_func()
Restore the lighted state of light according to the previously saved parameters.
sys_status_init()
Initializes the system state. By default network state is set.
Loop interface introduction for LIGHT
void sys_status_process(void)
Process the control commands received by the RF module and trigger the corresponding operations.
led_task_process_func()
Process LED blinking. Every 500ms, the luminance changes from 500 to 0 and then from 0 to 500. It flashes cyclically.
Process LED luminance and chromaticity gradients. Every 5ms, single step changes the current luminance and chromaticity parameters of the LED, gradually approaching the target luminance and chromaticity and reaching the target to save the LED parameters.
Change the LED local mode information. If the non-local mode is powered up for more than 500ms, the status "Next power up does not require switching to local mode" is saved. It will not enter local mode in the next power-up.
time_event_process_func()
Switch RF's receiving channel timely. (By default every 20ms switch once, 4-channel cyclic switching)
sys_status_check_func()
Check system status. If the pairing mode exceeds 6s, switch to normal mode. if the interval between CMD_ON commands exceeds 500ms, exit the clear code state.
LIGHT_BEACON
Same as section Light.
REMOTE_BEACON
Same as section Light_becon.
LIGHT_RGB
rf_packget_pro_func()
Process the control commands received by the RF module and trigger the corresponding operations.
void led_task_process_func(void)
Process LED blinking. Every 500ms, the luminance changes from 500 to 0 and then from 0 to 500. It flashes cyclically.
Process LED luminance and chromaticity gradients. Every 5ms, single step changes the current luminance and chromaticity parameters of the LED, gradually approaching the target luminance and chromaticity and reaching the target to save the LED parameters.
RGB color gradient for LEDs, includes flowing light function and RGB display.
REMOTE_RGB
Same as section Light_becon.
SDK configuration file description
Configuration of RF parameters and frequencies
Accesscode: by modifying RF_ACCESS_CODE_USE
Frequency: LIGHT&REMOTE and LIGHT RGB/REMOTE RGB use frequency {1,24,51,76} by default, change the variable rf_channel[4] to change the frequency. LIGHT BEACON&REMOTE BEACON use fixed frequency: {37,38,39}
Transmit Power:
#define RF_POWER RF_POWER_P11p46dBm
Mode selection for transmitting:
#define RF_MODE RF_PRIVATE_2M
Configuration of IO ports
#define LED_R GPIO_PB3//read
#define LED_G GPIO_PB4//green
#define LED_B GPIO_PB5//blue
#define LED_Y GPIO_PB6//yellow
#define LED_W GPIO_PD4//white
Modify the configuration of different LEDs by modifying the definition of their GPIO.
Modify main frequency
You can modify the main frequency by modifying the macro definition CLOCK_SYS_CLOCK_HZ in the app_config.h file, the macro definition options are 12M, 16M, 24M, 32M, and 48M.
Configure the product VID
#define REMOTE_VID 0x5453
Configure the OTP address of the REMOTE PID
#define PID_ADDR 0x3fe0
Configure the number of times the command sending
#define TTL_MAX 5 //forwardable times of remote command
#define NUM_SENDING_CMD_CTR 15//minimum number of times a single control command is sent, unless a new command is switched midway
#define NUM_SENDING_CMD_NONE 5//null command retransmission count
Operation introduction
Key functions of REMOTE& LIGHT and REMOTE_BEACON& LIGHT_BEACON
All On:
Short or long press to send out an All On command to turn on all nearby lights paired with the remote.
All Off:
Press "<" for 1.5s, the key lifts and sends the All Off command to turn off all nearby lights paired with the remote.
Press the key ">" for 1.5s to send the all into night light mode command to put all nearby lights paired with the remote into night light mode.
Group 1 On:
Short or long press to send out a Group 1 On command to turn on all nearby lights that are paired with Group 1.
Group 1 Off:
Press "<" for 1.5s, the key lifts and sends the Group 1 Off command, turning off all nearby lights paired with Group 1.
Press the key ">" for 1.5s to send the group 1 into night light mode command to put all nearby lights paired with group 1 into night light mode.
Group 2 on / group 3 on / group 4 on：Ditto for "Group 1 On".
Group 2 off / group 3 off / group 4 off：Ditto for "Group 1 Off".
Luminance increase / Luminance decrease：
Select the group (press the group on/off key, e.g. "Group 1 On" or "Group 1 Off") and press the Lumi_inc / Lumi_dec key.
Short press of the key sends a single command in a single pass. The luminance changes once.
Long press of the key for about 320ms each, to send a continuous command and the luminance changes continuously.
Chromaticity increase / chromaticity decrease：
Select the group (press the group on/off key, e.g. "Group 1 On" or "Group 1 Off") and press the Chroma_inc / Chroma_dec key.
Short press of the key sends a single command in a single pass. The chroma changes once.
Long press of the key for about 320ms each, and the command is sent continuously and the chroma changes continuously.
Key functions of REMOTE_RGB&LIGHT_RGB
Color temperature light on:
Short or long press to send out a light on command to turn on all the nearby color temperature lights paired with the remote.
Color temperature light off:
Short or long press to send out a light off command to turn off all nearby color temperature lights paired with the remote.
Luminance increase / Luminance decrease / chromaticity increase /chromaticity decrease：
Short press the key to send a single command, light led changes once.
Long press the key, 320ms timed update command, light led changes continuously.
RGB breathing light mode does not respond to color temperature and luminance adjustment commands.
Night light mode：
Short or long press to send out a night light mode command to put all nearby color temperature lights paired with the remote into night light mode.
RGB breathing light mode：
Short or long press to send out a night light mode command to put all the nearby color temperature lights paired with the remote into RGB breathing light mode.
Pair code：
light powers up < 6s, short press or long press the remote to send out pairing command, light receives command, retains pairing information and flashes light 3 times.
light power on > 6s, short press or long press the remote to send out pairing command, no action on the light.
Clear Code：
light powers up < 6s, short press or long press the remote to send out a clear code command, light receives the command, clears the pairing information and flashes 5 times.
light power on > 6s, short or long press the remote to send clear code command, no action on the light.
RGB settings：
Short or long press to send out the RGB setting command to turn on all RGB lights of nearby color temperature lights paired with the remote by 50%.