TUYA BLE SDK User Guide
Last updated
Last updated
The tuya ble sdk encapsulates the communication protocol with Tuya Smart mobile App and implements 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 callback 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.
https://github.com/TuyaInc/tuya_ble_sdk.git
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: implements 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: 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.
The tuya ble sdk can run on OS based chip platform besides 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.
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.
Directory
Description
app
Stores Applications that managed by the tuya ble sdk, such as Tuya test and production module, general connection modules and so forth.
doc
Help file.
extern_components
External components, for example, the extension for security-specific algorithm.
port
The abstract interfaces which must be implemented by Applications.
sdk
The core code of the tuya ble sdk.
tuya_ble_config.h
The configuration file for tuya ble sdk. However, your Application needs to create another configuration files on demand.
tuya_ble_sdk_version.h
The version file.
README.md
A brief introduction of the tuya ble sdk.
tuya_ble_sdk_version.txt
Explains what are updated for each version in Chinese.
CHANGELOG.md
Explains what are updated for each version in English.
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.
Service UUID
Characteristic UUID
Properties
Security Permissions
1910
2b10
Notify
None.
2b11
Write,write without response.
None.
For a better compatibility, the ATT MTU used by tuya ble sdk is 23, and the GATT MTU (ATT DATA MAX) is 20.
The following picture illustrates the broadcast packet format of BLE.
The following table describes what are contained in the broadcast packet.
Broadcast data segment
Type
Description
Physical connection identifier of BLE device
0x01
Length: 0x02;Type: 0X01; Data: 0x16
Service UUID
0x02
Length: 0x03; Type: 0x02; Data: 0xA201
Service Data
0x16
Length: 0x0C or 0x14 Type: 0x16 Data: 0x01, 0xA2, type (0-pid,1-product_key)PID, or product_key (in 8 or 16 byte)
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.
Response data segment
Type
Description
Complete Local Name
0x09
Length: 0x03; Type: 0x09; Date: 0x54 or 0x59
Custom data defined by manufacturer
0xff
Length: 0x19 Type: 0xff Date: COMPANY ID:0x07D0 FLAG: 0x00 Protocol version: 0x03 Encryption method: 0x00 Communication capacity: 0x0000 Reserved field: 0x00
ID field: 6 or 16 bytes
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
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.
TUYA_BLE_LOG
Function name
TUYA_BLE_LOG
Prototype
void TUYA_BLE_LOG(const char *format,…)
Description
Formatted output.
Parameters
format[in]: format controller. …[in]: variable parameters.
Responses
TUYA_BLE_ERR_INVALID_PARAM: invalid parameters
TUYA_BLE_HEXDUMP
Function name
TUYA_BLE_HEXDUMP
Prototype
void TUYA_BLE_HEXDUMP(uint8_t *p_data , uint16_t len)
Description
Print in hex values.
Parameters
p_data[in]: the data pointer to be printed. len[in]: data length.
Responses
TUYA_BLE_ERR_INVALID_PARAM: invalid parameters
tuya_ble_gap_advertising_adv_data_update
Function name
tuya_ble_gap_advertising_adv_data_update
Prototype
tuya_ble_status_t tuya_ble_gap_advertising_adv_data_update(uint8_t const * p_ad_data, uint8_t ad_len)
Description
Updates the BLE broadcast packets.
Parameters
p_ad_data[in]: new broadcast data. ad_len[in]: data length.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
tuya_ble_gap_advertising_scan_rsp_data_update
Function name
tuya_ble_gap_advertising_scan_rsp_data_update
Prototype
tuya_ble_status_t tuya_ble_gap_advertising_scan_rsp_data_update(uint8_t const *p_sr_data, uint8_t sr_len)
Description
Updates the scan response data.
Parameters
p_sr_data[in]: new scan response data. sr_len[in]: data length.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
tuya_ble_gap_disconnect
Function name
tuya_ble_gap_disconnect
Prototype
tuya_ble_status_t tuya_ble_gap_disconnect(void)
Description
Break the BLE connection.
Parameters
None.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
tuya_ble_gatt_send_data
Function name
tuya_ble_gatt_send_data
Prototype
tuya_ble_status_t tuya_ble_gatt_send_data(const uint8_t *p_data,uint16_t len)
Description
Sends data via BLE GATT.
Parameters
p_data[in]: the data pointer to send. len[in]: the data length, less than 20 bytes.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
Notice
It must be done in the notification method.
tuya_ble_timer_create
Function name
tuya_ble_timer_create
Prototype
tuya_ble_status_t tuya_ble_timer_create(void** p_timer_id,uint32_t timeout_value_ms, tuya_ble_timer_mode mode,tuya_ble_timer_handler_t timeout_handler)
Description
create a timer.
Parameters
p_timer_id[out]: the timer pointer. timeout_value_ms[in]: the timing, unit: ms. mode[in]: - TUYA_BLE_TIMER_SINGLE_SHOT: one-time mode. - TUYA_BLE_TIMER_REPEATED: recurring mode. - timeout_handler [in]: the timer callback.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
tuya_ble_timer_delete
Function name
tuya_ble_timer_delete
Prototype
tuya_ble_status_t tuya_ble_timer_delete(void* timer_id)
Description
Deletes a timer.
Parameters
timer_id [in]: the timer ID.
Responses
TUYA_BLE_SUCCESS: success. TUYA_BLE_ERR_INVALID_PARAM: invalid parameters. Others: failure.
tuya_ble_timer_start
Function name
tuya_ble_timer_start
Prototype
tuya_ble_status_t tuya_ble_timer_start(void* timer_id)
Description
Starts a timer.
Parameters
timer_id [in]: the timer ID.
Responses
TUYA_BLE_SUCCESS: success. TUYA_BLE_ERR_INVALID_PARAM: invalid parameters. Others: failure.
Notice
If a timer has been started, a tuya_ble_timer_start request will start the timer again.
tuya_ble_timer_restart
Function name
tuya_ble_timer_restart
Prototype
tuya_ble_status_t tuya_ble_timer_restart(void* timer_id,uint32_t timeout_value_ms)
Description
Restarts a timer with a new time.
Parameters
timer_id [in]: the timer ID. timeout_value_ms[in]: the timing, unit: ms.
Responses
TUYA_BLE_SUCCESS: success. TUYA_BLE_ERR_INVALID_PARAM: invalid parameters. Others: failure.
tuya_ble_timer_stop
Function name
tuya_ble_timer_stop
Prototype
tuya_ble_status_t tuya_ble_timer_stop(void* timer_id)
Description
Stops a timer.
Parameters
timer_id [in]: the timer ID.
Responses
TUYA_BLE_SUCCESS: success. TUYA_BLE_ERR_INVALID_PARAM: invalid parameters. Others: failure.
tuya_ble_device_delay_ms
Function name
tuya_ble_device_delay_ms
Prototype
void tuya_ble_device_delay_ms(uint32_t ms)
Description
Delays an activity at the millisecond level.
Parameters
ms [in]: the delay time, unit: ms.
Responses
None.
Notice
If the platform has an OS, it must be non-blocking delay. This method only applies to specific cases, for example, SDK initialization or device restart.
tuya_ble_device_delay_us
Function name
tuya_ble_device_delay_us
Prototype
void tuya_ble_device_delay_us(uint32_t us)
Description
Delays an activity at the microsecond level.
Parameters
us [in]: the delay time, unit: us.
Responses
None.
Notice
If the platform has an OS, it must be non-blocking delay. This method only applies to specific cases, for example, SDK initialization or device restart.
tuya_ble_device_reset
Function name
tuya_ble_device_reset
Prototype
tuya_ble_status_t tuya_ble_device_reset(void)
Description
Restarts devices.
Parameters
None.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
tuya_ble_gap_addr_get
Function name
tuya_ble_gap_addr_get
Prototype
tuya_ble_status_t tuya_ble_gap_addr_get(tuya_ble_gap_addr_t *p_addr);
Description
Obtains the MAC address of devices.
Parameters
p_addr [out]: the MAC address pointer.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
The following sample illustrates how to use the tuya_ble_gap_addr_get method.
tuya_ble_gap_addr_set
Function name
tuya_ble_gap_addr_set
Prototype
tuya_ble_status_t tuya_ble_gap_addr_set(tuya_ble_gap_addr_t *p_addr);
Description
Updates the MAC address of the device.
Parameters
p_addr [in]: the MAC address pointer.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
tuya_ble_device_enter_critical
Function name
tuya_ble_device_enter_critical
Prototype
voidtuya_ble_device_enter_critical(void)
Description
Enters the critical zone.
Parameters
None.
Responses
None.
tuya_ble_device_exit_critical
Function name
tuya_ble_device_exit_critical
Prototype
void tuya_ble_device_exit_critical(void)
Description
Quits the critial zone.
Parameters
None.
Responses
None.
tuya_ble_rand_generator
Function name
tuya_ble_rand_generator
Prototype
tuya_ble_status_t tuya_ble_rand_generator(uint8_t* p_buf, uint8_t len)
Description
Generates a random digit.
Parameters
p_buf [out]: the array of random digit pointer. len[in]: the byte number of the random value.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
tuya_ble_rtc_get_timestamp
Function name
tuya_ble_rtc_get_timestamp
Prototype
tuya_ble_status_t tuya_ble_rtc_get_timestamp(uint32_t *timestamp,int32_t *timezone);
Description
Obtains the Unix timestamp.
Parameters
timestamp [out]: the timestamp. timezone [out]: the time zone, data type: signed integer, the value must be 100 times of the real time.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
Notice
The data comes from the RTC (real-time clock) maintained by the Application itself. If the Application does not have an RTC, it is not necessary to use this interface.
tuya_ble_rtc_set_timestamp
Function name
tuya_ble_rtc_set_timestamp
Prototype
tuya_ble_status_t tuya_ble_rtc_set_timestamp(uint32_t timestamp,int32_t timezone)
Description
Updates the Unix timestamp.
Parameters
timestamp [in]: Unix timestamp. timezone [in]: the time zone, data type: signed integer, the value must be 100 times of the real time.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
Notice
The tuya ble sdk uses this API to update the RTC clock for the Application. If the Application does not have an RTC, it is not necessary to use this interface.
tuya_ble_nv_init
Function name
tuya_ble_nv_init
Prototype
tuya_ble_status_t tuya_ble_nv_init(void)
Description
Initializes the NV.
Parameters
None.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
Notice
It is used together with the NV space address that is defined in the configuration file. The tuya ble sdk calls NV related functions to store and manage authorization and other details.
tuya_ble_nv_erase
Function name
tuya_ble_nv_erase
Prototype
tuya_ble_status_t tuya_ble_nv_erase(uint32_t addr,uint32_t size)
Description
Erases the NV.
Parameters
addr[in]: the initial address of NV space to be erased. size[in]: the space length to be erased, unit: byte.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
Notice
It is used together with the NV space address that is defined in the configuration file. The tuya ble sdk calls NV related functions to store and manage authorization and other details.
tuya_ble_nv_write
Function name
tuya_ble_nv_write
Prototype
tuya_ble_status_t tuya_ble_nv_write(uint32_t addr,const uint8_t * p_data, uint32_t size)
Description
Writes data to NV.
Parameters
addr[in]: the initial address of NV space to write data. p_data[in]: the initial address of NV space to write data. size[in]: the data size, unit: byte.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
Notice
It is used together with the NV space address that is defined in the configuration file. The tuya ble sdk calls NV related functions to store and manage authorization and other details.
tuya_ble_nv_read
Function name
tuya_ble_nv_read
Prototype
tuya_ble_status_t tuya_ble_nv_read(uint32_t addr,uint8_t * p_data, uint32_t size)
Description
Reads data from NV.
Parameters
addr[in]: the initial address of NV space to read data. p_data[out]: the initial address of NV space to write data. size[in]: the data size, unit: byte.
Responses
TUYA_BLE_SUCCESS: success. Others: failure.
Notice
It is used together with the NV space address that is defined in the configuration file. The tuya ble sdk calls NV related functions to store and manage authorization and other details.
tuya_ble_nv_erase_async
Function name
tuya_ble_nv_erase_async
Prototype
void tuya_ble_nv_erase_async(uint32_t addr,uint32_t size,void *p_context,tuya_ble_nv_async_callback_t callback)
Description
Erases data from NV asynchronously.
Parameters
addr[in]: the initial address of NV space to erase data. size[in]: the data size, unit: byte. p_context[in]: user custom data. callback[in]: returns the API results.
Responses
None.
Notice
It is used together with the NV space address that is defined in the configuration file. The tuya ble sdk calls NV related functions to store and manage authorization and other details. The interface is used in the asynchronous flash based platform.
tuya_ble_nv_write_async
Function name
tuya_ble_nv_write_async
Prototype
void tuya_ble_nv_write_async(uint32_t addr,const uint8_t * p_src, uint32_t size,void *p_context,tuya_ble_nv_async_callback_t callback)
Description
Writes data to NV asynchronously.
Parameters
addr[in]: the initial address of NV space to write data. p_src[in]: the address to write date. size[in]: the data size, unit: byte. p_context[in]: user custom data. callback[in]: returns the API results.
Responses
None.
Notice
It is used together with the NV space address that is defined in the configuration file. The tuya ble sdk calls NV related functions to store and manage authorization and other details. The interface is used in the asynchronous flash based platform.
tuya_ble_nv_read_async
Function name
tuya_ble_nv_read_async
Prototype
void tuya_ble_nv_read_async(uint32_t addr, uint8_t * p_dest, uint32_t size,void *p_context,tuya_ble_nv_async_callback_t callback)
Description
Reads data from NV asynchronously.
Parameters
addr[in]: the initial address of NV space to read data. p_dest[out]: the address to read data. size[in]: the data size, unit: byte. p_context[in]: user custom data. callback[in]: returns the API results.
Responses
None.