Bluetooth Software

This topic describes the TuyaOS Bluetooth LE (LE) development kit in terms of its architecture, run process, directory, and common APIs.

Software architecture

TuyaOS is designed with a modular approach, with capabilities covering basic services, security, networking middleware, and various IoT services. Built on top of TuyaOS capabilities, TuyaOS Bluetooth Development Framework is a set of SDKs used to build Bluetooth products for different specifications and scenarios.

Unified APIs and a variety of components allow you to focus on building applications with a consistent development experience, without taking care of specific implementations.

The diagram above shows that the TuyaOS Bluetooth LE development kit is divided into four layers. We will now review each layer, starting from the bottom.

• The Tuya Kernel Layer (TKL) consists of Tuya-specific standard TKL APIs and chip vendor SDKs. The TKL provides unified APIs for the upper layer and adapts to different chip platforms. The adaptation development can be carried out by Tuya or chip vendors.

• The Tuya Abstraction Layer (TAL) and Service Layer, the core parts of the development kit, consist of various components. The basic services include pairing, data communication, and system management. The advanced services include weather service, human interface device (HID), time service, device sharing, power management, device management, and networking.

• The Application Layer covers various fields including electrical products, lights, home appliances, sensors, wearables, and door locks. Besides the standard product routines, you can also build with the standard demo projects without altering the code and leverage the cross-platform capability for improved efficiency. For more information, see Bluetooth Basics Demo.

Run process

For more information, see Device Initialization.

Development kit directory

Demo

This basic demo project allows you to test almost all the Bluetooth LE development kit features and develop any product accordingly.

• app_dp_parser: DP parsing routine, including DP reception and transmission functions, between which you can add business logic.

• app_key: Keypress routine. A press activates low power mode, while a press and hold resets a device.

• app_led: LED routine.

• tuya_ble_protocol_callback: Handles event callbacks for Tuya’s Bluetooth communication protocol.

• tuya_sdk_callback: Handles TuyaOS SDK event callbacks, initialization, and main loop.

Components (including libraries)

TuyaOS adopts a modular design approach, breaking down code implementations into components to manage different features.

• tal_ble_bulkdata: Bulk data transfer.

• tal_ble_ota: OTA updates.

• tal_ble_product_test: Authorization and testing.

• tal_ble_protocol: Tuya’s Bluetooth LE pairing protocol. You can implement the pairing protocol using APIs without taking care of the complex details.

• tal_ble_uart_common: Serial communication, used to interface with an external device.

• tal_ble_weather: Weather service.

• tal_bluetooth: Bluetooth API.

• tal_driver: Driver API.

• tal_key: Keypress.

• tal_oled: OLED driver.

• tal_sdk_test: Functional testing.

• tal_system: System service API.

• tal_utc: UTC API.

• tal_util: Common tools.

• tal_ble_mbedtls: Encryption (such as AES and MD5) API.

• tal_ble_secure: Security API for Tuya’s Bluetooth LE pairing protocol.

Vendor

The vendor directory stores the development environment, including chip vendor SDKs, adaptation layers, and common header files. It is maintained by Tuya and chip vendors.

Chip vendor SDK

The chip vendor SDK is developed by Tuya based on the open routines or adapted by chip vendors.

Adaptation layers

APIs for accessing Bluetooth, peripheral drivers (such as GPIO, PWM, ADC, I2C, and SPI), system drivers (such as memory, OTA, and sleep), and common tools.

Common header files

To enable a single codebase above the TKL to run across different platforms, platform-specific code such as flash address and peripheral pins is stored in board.h as macro definitions.

Header files

• tuya_error_code.h: Definitions for error codes.

• tuya_cloud_types.h: Definitions for data types, enumerations, macros, and structs.

• tuya_iot_config: Definitions for system configuration and component enablement or configuration.

Common APIs

Initialization

• tuya_init_first(): Initializes basic peripherals, configurations, and memory.

• tuya_init_second(): Initializes logging, software timer, and Bluetooth.

• tuya_init_third(): Initializes complex peripherals and peripheral components.

• tuya_init_last(): Initializes the Bluetooth pairing protocol and the test code, and enables Bluetooth adverting. After this API is executed, the main loop will be run.

• tuya_ble_protocol_init: Initializes the Bluetooth pairing protocol.

Main loop

tuya_main_loop(): A callback within the main loop, allowing you to inject custom operations into it.

Note:

• Do not modify the return value of this API unless necessary, as it can impact the low power mode.

• This API is intended for debugging and validation purposes. Use it with caution. Excessive time slices used by this API can compromise the stability of the entire framework.

Event callback

• tuya_ble_evt_callback: Bluetooth event callbacks. The events include Bluetooth stack initialization completion, Bluetooth connection and disconnection, connection parameter update, and data reception.

• tuya_ble_protocol_callback: Bluetooth pairing event callbacks. The events include device pairing, timestamp update, application data reception, device unbinding, and OTA data reception.

Data reception and transmission

• TUYA_BLE_CB_EVT_DP_DATA_RECEIVED: Callback for receiving application data. The received data is in DP format.

• tuya_ble_dp_data_send: Function for sending application data.

• tuya_ble_dp_data_with_time_send: Function for sending application data with a timestamp.

• TAL_BLE_EVT_WRITE_REQ: Callback for receiving Bluetooth data.

• tal_ble_server_common_send: Function for sending Bluetooth data.

Status query

tuya_ble_connect_status_get()

typedef enum {
    UNBONDING_UNCONN = 0,  // The device is unbound and not connected.
    UNBONDING_CONN,        // The device is unbound, connected, and authorized.
    BONDING_UNCONN,        // The device is bound and not connected.
    BONDING_CONN,          // The device is bound, connected, and authorized.
    BONDING_UNAUTH_CONN,   // The device is bound, connected, and unauthorized.
    UNBONDING_UNAUTH_CONN, // The device is unbound, connected, and unauthorized.
    UNKNOW_STATUS
} tuya_ble_connect_status_t;

The following diagram shows the state transition.

Common features

Bluetooth data stream

The following diagram shows how the Bluetooth LE data flows in the SDK. Other processes are similar.

Mobile phone sends	Mobile phone receives
TKL: callback for chip vendor Bluetooth LE data reception + tkl_ble_gatt_evt_func	tkl_ble_gatts_value_notify + function for chip vendor Bluetooth LE data transmission
TAL: TKL_BLE_GATT_EVT_WRITE_REQ + tal_ble_event_callback	tal_ble_server_common_send
TUYA: TAL_BLE_EVT_WRITE_REQ + tuya_ble_gatt_receive_data	tuya_ble_gatt_send_data
Receive a packet: TUYA_BLE_EVT_MTU_DATA_RECEIVE + tuya_ble_handle_ble_data_evt	tuya_ble_gatt_send_data_enqueue + tuya_ble_gatt_send_data_handle
tuya_ble_commonData_rx_proc, packet reassembly, decryption	tuya_ble_commData_send, packet reassembly, encryption
Receive a command: TUYA_BLE_EVT_BLE_CMD + tuya_ble_handle_ble_cmd_evt	TUYA_BLE_EVT_DP_DATA_SEND - tuya_ble_handle_dp_data_send_evt
tuya_ble_evt_process, distribute command	tuya_ble_dp_data_send
FRM_DP_DATA_WRITE_REQ + tuya_ble_handle_dp_data_write_req	app_dp_report
TUYA_BLE_CB_EVT_DP_DATA_RECEIVED + app_dp_parser	↑
→	→

Test code

To turn the testing code on, set TUYA_SDK_TEST to 1.

To turn the testing code off, set TUYA_SDK_TEST to 0.

You can test pairing, communication, and peripherals using the test code and Tuya’s host software. Make sure to disable the testing feature on production firmware.

Log management

Log output

tuya_log_output_cb

Dynamic memory

The size of the dynamic memory: BOARD_HEAP_SIZE

Drivers

The TKL provides a set of standard driver APIs required to run a minimum viable TuyaOS product. Note that not all drivers have the TKL API.

If the driver you need in the TKL is not implemented or not available, you can directly use the API provided by the chip vendor.