Skip to content

Telink Script Tool

Tool Introduction

Telink script tool

In order to quickly prototype the product, we developed a script system. In the system, Telink script tool, as a windows tool, can realize script editing, file interaction, UART sending and receiving, breakpoint control and other functions through UART interface and with the target board supporting the same interaction protocol (protocol is open source and easy to port). The system block diagram is as follows:

Quick Experience

Rocket board fast experience

The quick experience firmware only applies to Telink B91 series chips. If using the [Rocket Board] kit, you only need to use type-C cable to connect the base board and the computer. If using a non-[Rocket Board], you only need to connect the UART0_TX_PB2, UART0_RX_PB3 to the computer side through the USB to UART converter.

  1. Use Telink's downloader to download the quick experience firmware to the chip. Firmware burning can be done with the tool BDT or Web BDT .

  2. Download the tool telink_script_tool, the tool comes with a sample script, its main function: every 1 second to print the captured data and flip the LED, every 5 seconds the timer generates an interrupt, press the thumbwheel switch to control the color light display on the board.

  3. The USB to UART signal chip used on the Rocket board is CH340E, please install the CH340E driver beforehand. Connect the USB_UART port of the Rocket board to the computer with a Type-C cable, click the Port button at the main interface of the tool, select the corresponding port number and click Set, then click the Connect button.

  4. Click the Download All button and wait for the prompt that all downloads are complete (the download process takes about five seconds), if you get stuck in the middle, click the Download All button again.

  5. Observe whether the Rocket board phenomenon is as expected, you can click the terminal button to view the data printed by the serial port.

Use of Tools

Windows APP

The main interface of the tool is shown in the figure below. Area 1 buttons are used for system settings, area 2 buttons are used to interact with the development board, area 3 is the file list area, area 4 is the file editing area, and area 5 is the log display window.

System Operation

Clicking on a file in the send area, the file editing area will load the contents of the file, and we can edit the script in the editing area, and right-click to add or rename the file.

The functions of the buttons in the area 1 are summarized as follows:
Port: pop-up box to configure the port and baud rate, click the set button in the pop-up box to complete the setup.
Connect: Connect/disconnect with the set UART port.
Refresh: Refresh the file list.
Save: Save the file in the editing area (it will be saved automatically when switching the file selection).
Clear: clear the contents of the log window below.
Documentation: Open a browser to access the online documentation。
About: tool is built by Qt, it displays Qt-related licenses。
Settings: some of the function settings are disabled in default mode. Setting the state of the option is saved after reboot, use the default mode normally. Among them, the log level option is used to set the print level of the log display window, the file option is used to match the file list and file editing area syntax highlighting.

In the project folder of the tool, send is the folder of the sending area, receive is the folder of the receiving area, stytle.qss is the user-defined skin stylesheet, config.ini is the system configuration file, change the mode value to root in the configuration file, and then reboot the app to unlock more setting permissions. At this time you can set the gray zone option, need to modify the code at the corresponding chip to match.

Operate board

The Area 2 buttons are used to interact with the development board and can only be operated after the UART is successfully connected. Its functions are summarized as follows:
⬆️ Read: Read the script file and the breakpoint description file in the development board to the project/receive directory, click the file list in the receive area to view the file content in the edit area of the tool.

⤵️ Download: Click the file in the sending list and then click download, the file will be downloaded to the development board.
⤵️ Download All: Download all script files and breakpoint description files in the project/send directory to the development board.
❌ Delete: Click the file list to delete the corresponding files on the computer. If you check the option "Delete with board files" in the system settings, it will also try to delete the files with the same name when deleting the files in the receive list.
🐞 Breakpoints: Download all the breakpoint description files in the project/send directory to the board. Breakpoints are described in the section "Using Breakpoints" below.
🚫 Clear: Clear the breakpoint description file on the computer and delete the breakpoint description file on the board.
🔁 Reset: pull down the RST signal of the UART for 100 milliseconds and then pull it up again, the Rocket connects CH340E_RST to the chip reset pin, and this signal triggers a hardware reset of the chip.
Terminal: A pop-up window will appear when clicked. When the script is running, it interacts with the development board via UART. The interface of the pop-up window is as follows: area 1 is the UART data receiving area, area 2 is the function button, and area 3 has three sub-areas within it.

Single Send: Enter data in the input box and click the Send Data button in the area 2 to send the data to the development board.

Breakpoint control: except for rts reset, the rest of the functions can only take effect when the breakpoint stays.

Button Name Button Description
Continue running Skip breakpoints at stops and continue running.
Run at full speed Cancel all breakpoints and run at full speed.
Print breakpoints Print all breakpoints
Cancel breakpoints Cancel breakpoints at halts
Kernel status Program reads CSR register and PC values and prints them out.
Execute script Execute the script in the input box under the button.
rts reset Pull the UART's RST signal low for 100 milliseconds and then pulls it high again.

Read/write data: This operation can be done only when the breakpoint stays. First select the object to be read: Core/Flash/Analog, then enter the address and length, and finally click the Read/Write button.

Script Writing

Take lua script as an example, users need to write main.lua script and refer to the example script to realize setup and loop functions. If you want to realize the interrupt function, you need to write irq.lua script and implement the irq_entry function, the call logic of these three functions in the program is as follows.

// Interrupt handler function
void xxx_irq_handler(void){ 
    // clear interrupt flag bit
    clear_irq_state;
    // call the function irq_entry in the lua script and pass that interrupt number to the function
    call_lua_one_par("irq_entry",IRQ_NUMBER); 
}

void main() {
    // system initialization
    sys_init(); 
    // call the initialization function in lua script
    call_lua_function("setup"); 
    while (1) {
        // call the loop function in lua script
        call_lua_function("loop");
    }
}

Users can download lua scripts with other names into the chip and introduce these files in main.lua and use the functionality in them (as reflected in the sample code).

Using Breakpoints

In order to facilitate debugging, the system implements a simple breakpoint function. It should be noted that in the interrupt function breakpoints will not take effect. The specific steps are as follows:
1. Check/cancel breakpoints: click on the right side of the code line number to check this breakpoint, click again to cancel this breakpoint. There will be a breakpoint tip in the log window, and the system will synchronize the breakpoint information into the breakpoint configuration file on the computer.

  1. Click the "Breakpoint"/"Download All" button in the main interface to download the breakpoint configuration file from the computer into the development board. Click the "Clear" button to clear the breakpoint configuration file on the computer and delete the breakpoint configuration file on the development board. Every time the board is powered on, it will read and parse the breakpoint configuration file first and run according to the configuration.

  2. Click the "Terminal" button in the main interface, you can perform a series of operations at the breakpoint stay. The operations here will not affect the breakpoint configuration file on the board.

List of Interfaces

In the sample project, the interfaces are at my_lua_reg.c. These interfaces can be called in the script file, and the descriptions of the interfaces are as follows.
1. Rocket board related:

Interface prototype Interface function Calling demonstration
rocket_init() Initialize the components on the board. rocket_init()
rocket_oled_cls() Clear OLED screen rocket_oled_cls()
rocket_oled_cls_y(Y) OLED screen has six rows, clear rows Y and Y+1. rocket_oled_cls_y(0)
rocket_oled_show_str(x,y,string) Display a string on the screen with a string line height of 2, x∈[0,127] y∈[0,6] rocket_oled_show_str(0,0,"hello world")
rocket_sht30_read() Read temperature and humidity data and return two floats. temp,humi = rocket_sht30_read()
lua_rocket_adc_read() Read the voltage value captured by the ADC and the calculated resistance value of R13, the return value is two int. vol,r13 = rocket_adc_read()
rocket_lis2dh_read() Read the triaxial accelerometer data and return three int. x,y,z = rocket_lis2dh_read()
rocket_button_read() Read the key data, return an int, return 0 for no key pressed, return 1, 2, 3 for left, center, right key pressed respectively. button_value = rocket_button_read()
rocket_ws2812b_set(color) Set the light color, color for int type, data format for GRB, such as 0xff0000 for Green color. rocket_ws2812b_set(0xff0000)

  1. Read/Write related:
    Interface prototype Interface function Calling demonstration
    analog_write_reg8(addr,data) Write one byte of data to the analog register address. analog_write_reg8(0x12,0x34)
    analog_write_reg16(addr,data) Write half a word of data to the analog register address. analog_write_reg16(0x12,0x3456)
    analog_write_reg32(addr,data) Write one word of data to the analog register address. analog_write_reg32(0x12,0x12345678)
    analog_write_reg8_buff(addr,buff,len) Write a set of byte data buff to the analog register address, len is the length of the write, can not be greater than 1024. buff = {}
    buff[1] = 0x12 buff[2] = 0x34
    buff[3] = 0x56 buff[4] = 0x78
    analog_write_reg8_buff(0x12,buff,4)
    analog_read_reg8(addr) Read one byte of data from the analog register address. data_8 = analog_read_reg8(0x12)
    analog_read_reg16(addr) Read half a word of data from the analog register address. data_16 = analog_read_reg16(0x12)
    analog_read_reg32(addr) Read one word of data from the analog register address. data_32 = analog_read_reg32(0x12)
    analog_read_reg8_buff(addr,len) Read a set of byte data buff from the analog register address, len is the length of the read, which can not be greater than 1024. buff={}
    buff,read_len = analog_read_reg8_buff(0x12,20)

Similar read and write interfaces are as follows, from the name, they operate on SRAM and registers.

  write_sram8, write_sram16、write_sram32
  write_sram8_buff, write_sram16_buff, write_sram32_buff
  read_sram8, read_sram16, read_sram32
  read_sram8_buff, read_sram16_buff, read_sram32_buff
  write_reg8, write_reg16, write_reg32
  read_reg8, read_reg16, read_reg32

  1. GPIO related:

    Interface prototype Interface function Calling demonstration
    gpio_function_en(PAD_NUM) Set pin PAD_NUM to GPIO function, PAD number to string type gpio_function_en('PB6')
    gpio_function_dis(PAD_NUM) Disable GPIO function on pin PAD_NUM gpio_function_dis('PB6')
    gpio_output_en(PAD_NUM) Enable the output function of PAD_NUM. gpio_output_en('PB6')
    gpio_output_dis(PAD_NUM) Disable the output function of PAD_NUM. gpio_output_dis('PB6')
    gpio_input_en(PAD_NUM) Enable the input function of PAD_NUM. gpio_input_en('PB6')
    gpio_input_dis(PAD_NUM) Disable the input function of PAD_NUM. gpio_input_dis('PB6')
    gpio_high(PAD_NUM) Set PAD_NUM output high. gpio_high('PB6')
    gpio_low(PAD_NUM) Set PAD_NUM output low. gpio_low('PB6')
    gpio_toggle(PAD_NUM) Toggle the output of PAD_NUM. gpio_toggle('PB6')
    gpio_set_up_down_res(PAD_NUM,mode) Set PAD_NUM to simulate pull-up and pull-down, mode takes value 0-3, 0: float, 1: pull-up 1M ohm, 2: pull-down 100K ohm 3: pull-up 10K ohm. gpio_set_up_down_res('PB6',1)
    gpio_set_irq(PAD_NUM,IQR_TYPE) Set GPIO_IRQ interrupt, IQR_TYPE is the trigger mode, the value is 0-3, 0: rising edge, 1: falling edge, 2: high level 3: low level. gpio_set_irq('PD1',1)
    gpio_set_gpio2risc0_irq(PAD_NUM,IQR_TYPE) Set IRQ_RISC0 interrupt, IQR_TYPE is the trigger mode, the value is 0-3, 0: rising edge, 1: falling edge, 2: high level 3: low level. gpio_set_gpio2risc0_irq('PD2',1)
    gpio_set_gpio2risc1_irq(PAD_NUM,IQR_TYPE) Set IRQ_RISC1 interrupt, IQR_TYPE is the trigger mode, the value is 0-3, 0: rising edge, 1: falling edge, 2: high level 3: low level. gpio_set_gpio2risc1_irq('PD3',1)

  2. Others:

    Interface prototype Interface function Calling demonstration范
    SYS_DEBUG_EN() Enable the breakpoint function. SYS_DEBUG_EN()
    print_riscv_reg() Print the CSR register and PC values read by the program. print_riscv_reg()
    core_interrupt_enable() Enable the global master interrupt. mstatus = core_interrupt_enable()
    core_interrupt_disable() Disable the global master interrupt. core_interrupt_disable()
    core_restore_interrupt(mstatus) Restore global interrupt from incoming value. core_restore_interrupt(mstatus)
    get_mem_perused() Get dynamic memory usage. value = get_mem_perused()
    set_timer0_cycle(ms) Set the timing period of Timer 0 (milliseconds). set_timer0_cycle(1000)
    set_timer1_cycle(ms) Set the timing period of Timer 1 (milliseconds). set_timer1_cycle(1000)
    delay_us(us) Function of delay (us) core_restore_interrupt(10)
    delay_ms(ms) Function of delay (ms) delay_ms(10)

Firmware Build

Firmware Build

The interfaces in the firmware used in the quick experience are fixed and limited. Users can download the source code and develop it by themselves.

Users can add their own interfaces in my_lua_reg.c under source code, or directly port the source code to other platforms.

For Telink's B91 series chips, we provide a reference script for generating lib libraries in the project directory, so that you can load the generated lib libraries into your own project for compiling and generating firmware. Add tlua_lib.a and the math library into the Telink IoT Studio settings, and add the relevant header files in the folder lua_interface and telink_lua_lib into the project, and call the two interfaces in the lib library in the initialization and main loop. 

    #include "lua_interface/my_lua_reg.h"
    #include "lua_interface/my_lua_interface.h"
    #include "telink_lua_lib/lua/lua_extend.h"

    void user_init()
    {
        telink_lua_lib_init(lua_lib,&lua_interface);
    }

    void main_loop(void)
    {
        while(1){
            telink_lua_main_loop();
        }
    }

An example of calling Lua's irq_entry function at an interrupt function is as follows: 

_attribute_ram_code_sec_noinline_ void gpio_irq_handler(void)
{
    gpio_clr_irq_status(FLD_GPIO_IRQ_CLR);
    c_call_lua_one_par("irq_entry",IRQ25_GPIO);
}