Note: This repository will be deprecated soon, please refer to the new repository in the Tuya Github Organization: https://github.com/tuya/tuya-ble-sdk.

注意：当前仓库将会废弃，新的涂鸦 Github 仓库地址参见： https://github.com/tuya/tuya-ble-sdk.

tuya ble sdk

The tuya ble sdk encapsulates the communication protocol with Tuya Smart mobile App and implements a event scheduling abilities. The device using tuya ble sdk does not need to care about the specific communication protocol implementation details. It can be interconnected with Tuya Smart App by calling the API and call back provided by the tuya ble sdk.

This topic gives details of the components, porting instruction, SDK configuration, API description, and usage of tuya ble sdk.

Overview of tuya ble sdk

Framework

The following figure shows the Application framework based on tuya ble sdk:

• platform: the chip platform. The chip and protocol stack are maintained by the chip company.

• Port: the abstract interfaces needed by the tuya ble sdk. You must implement them according to the chip-specific platform.

• tuya ble sdk: encapsulates the communication protocol of Tuya BLE and provides the service interface to develop Tuya BLE devices.

• Application: your application, built by using tuya ble sdk.

• Tuya sdk API: to implement BLE related management, communication, and so forth. The calls of API are based on asynchronous messages, and the result of API will be notified to the Application of device by message or call back.

• sdk config: by setting the macro in the configuration file, you can configure tuya ble sdk to different modes, for example, the general network configuration mode applicable to multi-protocol devices, Bluetooth singlepoint devices mode, ECDH key based encryption method, whether to use OS, and so forth.

• Main process function: as the engine of tuya ble sdk, to which the Application will call all the time. If the platform architecture has an OS, The tuya ble sdk will automatically create a task to run the main process based on the OS related interface provided by the port layer. If the platform does not have an OS, the device Application needs to be called circularly.

• Message or Call back: SDK sends the data of status, data, and others to device Application through call back function registered by device Application or messages.

OS compatibility

The tuya ble sdk can run on OS based chip platform other than Linux. If an OS is used, the API requests are based on asynchronous messages. When tuya ble sdk is initialized, the SDK automatically creates a task based on 'tuya_ble_config.h file to process the message events of the SDK, and creates a message queue to receive the responses of the Application API. The results of the API are notified to the Application of the device in the form of message, so your Application needs to create a message queue and call tuya_ble_callback_queue_register() after calling tuya_ble_sdk_init() or tuya_ble_sdk_init_async() to register the message queue to the SDK.

In the chip platform that has an OS, you can also configure the tuya ble sdk to process messages using the task provided by Application instead of tasks within the tuya ble sdk. By doing so, the Application must implement the outbound message interface at the port layer.

Event queue

The earlier event takes precedence to leave (FIFO). Event queue caches the messages sent by the Application and platform layer, the event can be API calls, data response from BLE devices, and so forth. The main process function module circularly queries the message queue and takes it out for processing.

Directories

The concepts of tuya ble service

The tuya ble sdk does not provide the interfaces for initializing service. Your Application needs to implement the service characteristics defined in the following table before you initializing the SDK. Other than the services required by the tuya ble sdk, you can also define other services if needed. The initial format of broadcast data must be implemented according to the following table, otherwise the tuya ble sdk cannot work.

The MTU

For a better compatibility, the ATT MTU used by tuya ble sdk is 23, and the GATT MTU (ATT DATA MAX) is 20.

Broadcast data format

The following picture illustrates the broadcast packet format of BLE.

The following table describes what are contained in the broadcast packet.

Example of 8 byte PID: 02 01 05 03 02 01 A2 0C 16 01 A2 00 00 00 00 00 00 00 00 00

The following table describes what are contained in the scan response data.

Example of an unassociated devices: 03 09 54 59 19 FF D0 07 00 0300 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

How to port and configure tuya ble sdk

As the following picture shows, the interfaces defined in the file tuya_ble_port.h and tuya_ble_port_peripheral.h must be ported and implemented according to the chip-specific platform. Note that if the platform used in the Application does not have an OS, the OS related interfaces do not need to be implemented. The tuya_ble_port.c and tuya_ble_port_peripheral.c are the weak implementation of the interfaces defined for the tuya_ble_port.h and tuya_ble_port_peripheral.h.

You cannot implement platform-specific interfaces in the preceding .c files, please create a new one, for example tuya_ble_port_nrf52832.c. If the file name contains the keyword tuya, it is the platform implementation file that Tuya Smart has adapted and transplanted, you can refer to it if needed.