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_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. |
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_common_uart_init
Function name | tuya_ble_common_uart_init |
Prototype | tuya_ble_status_t tuya_ble_common_uart_init(void) |
Description | Initializes the UART. |
Parameters | None. |
Responses | TUYA_BLE_SUCCESS: success. Others: failure. |
Notice | Under the following circumstances, there is no need to implement the |
tuya_ble_common_uart_send_data
Function name | tuya_ble_common_uart_send_data |
Prototype | tuya_ble_status_t tuya_ble_common_uart_send_data(const uint8_t *p_data,uint16_t len) |
Description | Sends data via UART. |
Parameters | p_data[in]: the data pointer to send. len[in]: the data size. |
Responses | TUYA_BLE_SUCCESS: success. Others: failure. |
Notice | If the functions of test and production authorization are not used, there is no need to implement the |
tuya_ble_os_task_create
Function name | tuya_ble_os_task_create |
Prototype | bool tuya_ble_os_task_create(void **pp_handle, const char *p_name, void(*p_routine)(void *),void *p_param, uint16_t stack_size, uint16_t priority) |
Description | Creates tasks. |
Parameters | pp_handle [out]: passes back a handle by which the created task can be referenced. p_name[in]: A descriptive name for the task. p_routine [in]: pointer to task routine function that must be implemented to never return. p_param[in]: pointer parameter passed to the task routine function. stack_size[in]: the size of the task stack that is specified as the number of bytes. priority[in]: the priority at which the task should run. Higher priority task has higher priority value. |
Responses | True: task was created successfully and added to task ready list. False: task was failed to create. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_os_task_delete
Function name | tuya_ble_os_task_delete |
Prototype | bool tuya_ble_os_task_delete(void *p_handle) |
Description | Removes a task from RTOS's task management. The task being deleted will be removed from RUNNING, READY, or WAITING state. |
Parameters | pp_handle [in]: the handle of the task to be deleted. |
Responses | True: task was deleted successfully False: task was failed to delete. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_os_task_suspend
Function name | tuya_ble_os_task_suspend |
Prototype | bool tuya_ble_os_task_suspend(void *p_handle) |
Description | Suspends the task. The suspended task will not be scheduled and never get any microcontroller processing time. |
Parameters | pp_handle [in]: the handle of the task to be suspend. |
Responses | True: task was suspend successfully. False: task was failed to suspend. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_os_task_resume
Function name | tuya_ble_os_task_resume |
Prototype | bool tuya_ble_os_task_resume(void *p_handle) |
Description | Resumes the suspended task. |
Parameters | pp_handle [in]: the handle of the task to be resumed. |
Responses | True: task was resumed successfully. False: task was failed to resume. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_os_msg_queue_create
Function name | tuya_ble_os_msg_queue_create |
Prototype | bool tuya_ble_os_msg_queue_create(void **pp_handle, uint32_t msg_num, uint32_tmsg_size) |
Description | Creates a message queue instance. This allocates the storage required by the new queue and passes back a handle for the queue. |
Parameters | pp_handle [out]: passes back a handle by which the message queue can be referenced. msg_num [in]: the maximum number of items that the queue can contain. msg_size [in]: the number of bytes each item in the queue will require. |
Responses | True: message queue was created successfully. False: message queue was failed to create. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_os_msg_queue_delete
Function name | tuya_ble_os_msg_queue_delete |
Prototype | bool tuya_ble_os_msg_queue_delete(void *p_handle) |
Description | Creates a message queue instance. This allocates the storage required by the new queue and passes back a handle for the queue. |
Parameters | pp_handle [in]: the handle to the message queue being deleted. |
Responses | True: message queue was deleted successfully. False: message queue was failed to delete. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_os_msg_queue_peek
Function name | tuya_ble_os_msg_queue_peek |
Prototype | bool tuya_ble_os_msg_queue_peek(void *p_handle, uint32_t *p_msg_num) |
Description | Peeks the number of items sent and resided on the message queue. |
Parameters | pp_handle [in]: the handle to the message queue being peeked. p_msg_num[out]: passes back the number of items residing on the message queue. |
Responses | True: message queue was peeked successfully. False: message queue was failed to peek. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_os_msg_queue_send
Function name | tuya_ble_os_msg_queue_send |
Prototype | bool tuya_ble_os_msg_queue_send(void *p_handle, void *p_msg, uint32_t wait_ms) |
Description | Sends an item to the back of the specified message queue. |
Parameters | pp_handle [in]: the handle to the message queue on which the item is to be sent. p_msg[in]: pointer to the item that is to be sent on the queue. wait_ms[in]: the maximum amount of time in milliseconds that the task should block waiting for the item to sent on the queue. - 0: no blocking and return immediately. - 0xFFFFFFFF: blocks infinitely until the item received. - others: the timeout value in milliseconds. |
Responses | True: message item was sent successfully. False: message item was failed to send. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_os_msg_queue_recv
Function name | tuya_ble_os_msg_queue_recv |
Prototype | bool tuya_ble_os_msg_queue_recv(void *p_handle, void *p_msg, uint32_t wait_ms) |
Description | Receives an item from the specified message queue. |
Parameters | pp_handle [in]: the handle to the message queue from which the item is to be received. p_msg[out]: pointer to the buffer into which the received item will be copied. wait_ms[in]: the maximum amount of time in milliseconds that the task should block waiting for the item to received on the queue. - 0: no blocking and return immediately. - 0xFFFFFFFF: blocks infinitely until the item received. - others: the timeout value in milliseconds. |
Responses | True: message item was received successfully. False: message item was failed to receive. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_event_queue_send_port
Function name | tuya_ble_event_queue_send_port |
Prototype | bool tuya_ble_event_queue_send_port(tuya_ble_evt_param_t *evt, uint32_t wait_ms) |
Description | If the TUYA_BLE_SELF_BUILT_TASK is undefined, Application should provide the task to sdk to process the event. The sdk will use this port to send event to the task of provided by Application. |
Parameters | evt [in]: the message data point to be send. wait_ms[in]: the maximum amount of time in milliseconds that the task should block waiting for the item to sent on the queue.
|
Responses | True: message item was sent successfully. False: message item was failed to send. |
Notice | This interface is required only in the platform that has an OS. |
tuya_ble_aes128_ecb_encrypt
Function name | tuya_ble_aes128_ecb_encrypt |
Prototype | bool tuya_ble_aes128_ecb_encrypt(uint8_t *key,uint8_t *input,uint16_tinput_len,uint8_t *output) |
Description | 128 bit AES ECB encryption on specified plaintext and keys. |
Parameters | key [in]: keys to encrypt the plaintext In_put[in]: specified plaintext to be encrypted. in_put_len[in]: byte length of the data to be encrypted, must be multiples of 16. Out_put[out]: output buffer to store encrypted data. |
Responses | True: successful. False: fail. |
tuya_ble_aes128_ecb_decrypt
Function name | tuya_ble_aes128_ecb_decrypt |
Prototype | bool tuya_ble_aes128_ecb_decrypt(uint8_t *key,uint8_t *input,uint16_tinput_len,uint8_t *output) |
Description | 128 bit AES ECB decryption on specified encrypted data and keys |
Parameters | key [in]: keys to decrypt the plaintext In_put[in]: specified encrypted data to be decypted in_put_len[in]: byte length of the data to be decrypted, must be multiples of 16. Out_put[out]: output buffer to store decrypted data. |
Responses | True: successful. False: fail. |
tuya_ble_aes128_cbc_encrypt
Function name | tuya_ble_aes128_cbc_encrypt |
Prototype | bool tuya_ble_aes128_cbc_encrypt(uint8_t *key,uint8_t *iv,uint8_t input,uint16_t input_len,uint8_toutput) |
Description | 128 bit AES CBC encryption on specified plaintext and keys. |
Parameters | key [in]: keys to encrypt the plaintext. iv[in]: initialization vector (IV) for CBC mode. In_put[in]: specified plain text to be encrypted. in_put_len[in]: byte length of the data to be encrypted, must be multiples of 16. Out_put[out]: output buffer to store encrypted data. |
Responses | True: successful. False: fail. |
tuya_ble_aes128_cbc_decrypt
Function name | tuya_ble_aes128_cbc_decrypt |
Prototype | bool tuya_ble_aes128_cbc_decrypt(uint8_t*key,uint8_t *iv,uint8_t *input,uint16_t input_len,uint8_t *output) |
Description | 128 bit AES CBC decryption on specified plaintext and keys. |
Parameters | key [in]: keys to decrypt the plaintext. Iv[in]: initialization vector (IV) for CBC mode In_put[in]: specified encrypted data to be decrypted. in_put_len[in]: byte length of the data to be decrypted, must be multiples of 16. Out_put[out]: output buffer to store decrypted data. |
Responses | True: successful. False: fail. |
tuya_ble_md5_crypt
Function name | tuya_ble_md5_crypt |
Prototype | booltuya_ble_md5_crypt(uint8_t *input,uint16_t input_len,uint8_t *output) |
Description | MD5 checksum. |
Parameters | In_put[in]: specified plain text to be encrypted. in_put_len[in]: byte length of the data to be encrypted. Out_put[out]: output buffer to store md5 result data,output data lenghth is always 16. |
Responses | True: successful. False: fail. |
tuya_ble_hmac_sha1_crypt
Function name | tuya_ble_hmac_sha1_crypt |
Prototype | bool tuya_ble_hmac_sha1_crypt(constuint8_t *key, uint32_t key_len, const uint8_t *input, uint32_t input_len,uint8_t *output) |
Description | Calculates the full generic HMAC on the input buffer with the provided key. |
Parameters | key [in]: The HMAC secret key. key_len[in]: The length of the HMAC secret key in bytes. In_put[in]: specified plain text to be encrypted. in_put_len[in]: byte length of the data to be encrypted. Out_put[out]: output buffer to store the result data. |
Responses | True: successful. False: fail. |
Notice | Not used currently, no need to implement. |
tuya_ble_hmac_sha256_crypt
Function name | tuya_ble_hmac_sha1_crypt |
Prototype | bool tuya_ble_hmac_sha256_crypt(const uint8_t *key, uint32_t key_len, const uint8_t *input, uint32_t input_len, uint8_t *output) |
Description | Calculates the full generic HMAC on the input buffer with the provided key. |
Parameters | key [in]: The HMAC secret key. key_len[in]: The length of the HMAC secret key in Bytes. In_put[in]: specified plain text to be encrypted. in_put_len[in]: byte length of the data to be encrypted. out_put[out]: output buffer to store the result data. |
Responses | True: successful. False: fail. |
Notice | Not used currently, no need to implement. |
tuya_ble_port_malloc
Function name | tuya_ble_port_malloc |
Prototype | void *tuya_ble_port_malloc( uint32_t size ) |
Description | Allocate a memory block with required size. |
Parameters | Size[in]: Required memory size. |
Responses | The address of the allocated memory block. If the address is NULL, the memory allocation failed. |
Notice | You need to implement this interface only when |
tuya_ble_port_free
Function name | tuya_ble_port_free |
Prototype | void tuya_ble_port_free(void *pv ) |
Description | Frees a memory block that had been allocated. |
Parameters | pv[in]: The address of memory block being freed. |
Responses | None. |
Notice | You need to implement this interface only when |
The items in the tuya_ble_config.h file are used to configure the tuya ble sdk for different use cases, for example, network configuration for multi-protocol devices, whether running an OS on the platform or not, device communication, whether self-manage the authorization, and so forth.
CUSTOMIZED_TUYA_BLE_CONFIG_FILE
Macro | CUSTOMIZED_TUYA_BLE_CONFIG_FILE |
Dependency | None. |
Description | Custom configuration file.
This file overwrites the default settings in the |
CUSTOMIZED_TUYA_BLE_APP_PRODUCT_TEST_HEADER_FILE
Macro | CUSTOMIZED_TUYA_BLE_APP_PRODUCT_TEST_HEADER_FILE |
Dependency | None. |
Description | The tuya ble sdk provides basic test and production authorization services.
If the Tuya testing protocol is used in your Application to perform many customized test activities, your must create a file to achieve that, and assign the header file name to |
Notice | It must be completed in the custom configuration file. |
CUSTOMIZED_TUYA_BLE_APP_UART_COMMON_HEADER_FILE
Macro | CUSTOMIZED_TUYA_BLE_APP_UART_COMMON_HEADER_FILE |
Dependency | None. |
Description | At present, it only applies to the general module protocol of Tuya Smart. |
Notice | It must be completed in the custom configuration file. |
TUYA_BLE_USE_OS
Macro | TUYA_BLE_USE_OS |
Dependency | None. |
Description | If the chip architecture is based on OS, such as FreeRTOS, set
|
TUYA_BLE_SELF_BUILT_TASK
Macro | TUYA_BLE_SELF_BUILT_TASK |
Dependency |
|
Description | For the OS architecture platform, if you use self-built tasks in the tuya ble sdk to handle messages, please set |
TUYA_BLE_TASK_PRIORITY
Macro | TUYA_BLE_TASK_PRIORITY |
Dependency |
|
Description | The priority of a task initiated by tuya ble sdk. For example, |
Notice | The priority value needs to be defined according to the OS used by the chip platform. |
TUYA_BLE_TASK_STACK_SIZE
Macro | TUYA_BLE_TASK_STACK_SIZE |
Dependency |
|
Description | The stack size of a task initiated by tuya ble sdk. For example, |
TUYA_BLE_DEVICE_COMMUNICATION_ABILITY
Macro | TUYA_BLE_DEVICE_COMMUNICATION_ABILITY |
Dependency | None. |
Description | The communication of devices. Possible setting:
|
TUYA_BLE_DEVICE_SHARED
Macro | TUYA_BLE_DEVICE_SHARED |
Dependency | None. |
Description | Determines whether a device is shared. |
Notice | If you do not understand what are shared devices, please set |
TUYA_BLE_DEVICE_UNBIND_MODE
Macro | TUYA_BLE_DEVICE_UNBIND_MODE |
Dependency | None. |
Description | Determines whether the shared devices need to perform the unbind operation. |
Notice | If you do not understand what are shared devices, please set |
TUYA_BLE_WIFI_DEVICE_REGISTER_MODE
Macro | TUYA_BLE_WIFI_DEVICE_REGISTER_MODE |
Dependency | The devices must support Wi-Fi connection. |
Description | Determines whether to send command to query the network configuration state or not when use BLE to configure network for Wi-Fi devices. If yes:
|
Notice | Currently not supported. |
TUYA_BLE_DEVICE_AUTH_SELF_MANAGEMENT
Macro | TUYA_BLE_DEVICE_AUTH_SELF_MANAGEMENT |
Dependency | None. |
Description | If you use self-built tasks in the tuya ble sdk to manage authorization, please set |
Notice | For BLE devices without Wi-Fi capability, this value is recommended to be defined as 1. |
TUYA_BLE_SECURE_CONNECTION_TYPE
Macro | TUYA_BLE_SECURE_CONNECTION_TYPE |
Dependency | None. |
Description | The communication encryption method of devices. Possible setting:
|
Notice | Currently, only |
TUYA_BLE_DEVICE_MAC_UPDATE
Macro | TUYA_BLE_DEVICE_MAC_UPDATE |
Dependency | None. |
Description | Determines whether to use the MAC address in the Tuya authorization information as the device MAC address or not. |
TUYA_BLE_DEVICE_MAC_UPDATE_RESET
Macro | TUYA_BLE_DEVICE_MAC_UPDATE_RESET |
Dependency |
|
Description | Determines whether the device needs to restart after updating the MAC address to take effect or not. If yes:
|
TUYA_BLE_USE_PLATFORM_MEMORY_HEAP
Macro | TUYA_BLE_USE_PLATFORM_MEMORY_HEAP |
Dependency | None. |
Description | Whether tuya ble sdk uses its own memory heap. If yes:
|
Notice | If it is defined as |
TUYA_BLE_GATT_SEND_DATA_QUEUE_SIZE
Macro | TUYA_BLE_GATT_SEND_DATA_QUEUE_SIZE |
Dependency | None. |
Description | The size of the GATT send queue used by tuya ble sdk. Default value: 20.
|
Notice | If you do not know much about the macro, it is recommended to keep it at 20. |
TUYA_BLE_DATA_MTU_MAX
Macro | TUYA_BLE_DATA_MTU_MAX |
Dependency | None. |
Description | The size of GATT MTU:
|
Notice | Currently, only 20 bytes GATT MTU are supported, which will be expanded and upgraded later. |
TUYA_BLE_LOG_ENABLE
Macro | TUYA_BLE_LOG_ENABLE |
Dependency | None. |
Description | Determines whether to enable log of tuya ble sdk or not.
If yes: |
Notice | Enabling the internal log consumes the code space. It is recommended to turn on it for the debug version and turn off for the release version. |
TUYA_BLE_LOG_COLORS_ENABLE
Macro | TUYA_BLE_LOG_COLORS_ENABLE |
Dependency |
|
Description | Determines whether to enable the multi-color display for logs of SDK or not.
If yes: |
Notice | Some tools do not support it, for example, RTT of J-link. |
TUYA_BLE_LOG_LEVEL
Macro | TUYA_BLE_LOG_LEVEL |
Dependency |
|
Description | Defines the display level of the log of tuya ble sdk, which is divided into the following levels:
|
TUYA_APP_LOG_ENABLE
Macro | TUYA_APP_LOG_ENABLE |
Dependency | None. |
Description | Whether to enable Application log.
If yes: |
Notice | Enabling the internal log consumes the code space. It is recommended to turn on it for the debug version and turn off for the release version. |
TUYA_APP_LOG_COLORS_ENABLE
Macro | TUYA_APP_LOG_COLORS_ENABLE |
Dependency |
|
Description | Determines whether to enable the multi-color display for logs of Application or not.
If yes: |
Notice | Some tools do not support it, for example, RTT of J-Link. |
TUYA_APP_LOG_LEVEL
Macro | TUYA_APP_LOG_LEVEL |
Dependency |
|
Description | Defines the display level of the log of tuya ble sdk, which is divided into the following levels:
|
TUYA_BLE_ADVANCED_ENCRYPTION_DEVICE
Macro | TUYA_BLE_ADVANCED_ENCRYPTION_DEVICE |
Dependency | None. |
Description | Determines whether to use advanced encryption method.
If yes: |
Notice | It is not supported currently. |
TUYA_NV_ERASE_MIN_SIZE
Macro | TUYA_NV_ERASE_MIN_SIZE |
Dependency | None. |
Description | The minimum erasure unit of NV space allocated to tuya ble sdk, for example:
|
Notice | It must be defined according to the implementation of NV interface in the port layer. |
TUYA_NV_WRITE_GRAN
Macro | TUYA_NV_WRITE_GRAN |
Dependency | None. |
Description | The maximum write granularity in the NV space. For example,
|
Notice | It must be defined according to the implementation of NV interface in the port layer. |
TUYA_NV_START_ADDR
Macro | TUYA_NV_START_ADDR |
Dependency | None. |
Description | The initial NV space address allocated to tuya ble sdk. For example:
|
TUYA_NV_AREA_SIZE
Macro | TUYA_NV_AREA_SIZE |
Dependency | None. |
Description | The NV space size allocated to tuya ble sdk. For example, |
TUYA_BLE_APP_VERSION_STRING
Macro | TUYA_BLE_APP_VERSION_STRING |
Dependency | None. |
Description | The Application version number string, for example, |
Notice | Currently, only two digit version numbers are supported. |
TUYA_BLE_APP_BUILD_FIRMNAME_STRING
Macro | TUYA_BLE_APP_BUILD_FIRMNAME_STRING |
Dependency | None. |
Description | The Application firmware name, for example, |
Notice | It is only required when you use the Tuya production testing license agreement. |
The tuya ble sdk provides packaged API for Application to achieve BLE related management, communication, and so forth. The APIs are defined in the tuya_ble_api.c and tuya_ble_api.h files, you can read the source code to understand how the APIs are implemented. The following tables describes the details of each API.
tuya_ble_main_tasks_exec
Function name | tuya_ble_main_tasks_exec |
Prototype | void tuya_ble_main_tasks_exec(void) |
Description | The tuya ble sdk event main scheduler when using the non-OS architecture chip platform. The Application can call it only in the main loop. |
Parameters | None. |
Responses | None. |
Notice | This function must be called from within the main loop. It will execute all events scheduled since the last time it was called. |
Example: the calling location under nrf52832 platform is as follows:
tuya_ble_gatt_receive_data
Function name | tuya_ble_gatt_receive_data |
Prototype | tuya_ble_status_t tuya_ble_gatt_receive_data(uint8_t*p_data,uint16_t len); |
Description | By calling this function, the GATT data received by Bluetooth is sent to tuya ble sdk. |
Parameters | p_data[in]: point to the data to be sent.
len[in]: the length of the data to be sent, cannot exceed |
Responses | TUYA_BLE_SUCCESS: send successfully. TUYA_BLE_ERR_INTERNAL: failed. |
Notice | This function must be called from where the BLE data is received. |
Example (nrf52832 example demo):
tuya_ble_common_uart_receive_data
Function name | tuya_ble_common_uart_receive_data |
Prototype | tuya_ble_status_t tuya_ble_common_uart_receive_data (uint8_t *p_data,uint16_t len) |
Description | If an Application uses the production testing authorization module provided by tuya ble sdk, you need to send UART data to tuya ble sdk by calling this function. If you do not use the production testing authorization function module provided by tuya ble sdk, you do not need to call this function. |
Parameters | p_data[in]: point to the data to be sent. len[in]: length of data to be sent. |
Responses | TUYA_BLE_SUCCESS: sent successfully. Other: failed to send. |
Notice | This function internally calls malloc to apply for memory.
If the Application configuration uses the malloc interface provided by the platform,
confirm whether the platform malloc supports interrupt calls.
If it does not support, it must not be called in UART interrupt |
tuya_ble_common_uart_send_full_instruction_received
Function name | tuya_ble_common_uart_send_full_instruction_received |
Prototype | tuya_ble_status_t. tuya_ble_common_uart_send_full_instruction_received (uint8_t *p_data,uint16_t len) |
Description | Sends the Tuya production testing protocol command (including the |
Parameters | p_data[in]: Point to the complete command data to be sent. len[in]: Command data length to be sent. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_NO_MEM: Failed to apply for memory. TUYA_BLE_ERR_BUSY: BLE SDK busy. |
Notice | This function internally calls the malloc interface. If the Application is configured to use the chip platform-provided malloc interface,
make sure that platform malloc supports interrupt calls.
If it does not, you must not call |
Explanation:
The tuya ble sdk integrates the production testing authorization function module. The production testing authorization module communicates through the UART and PC production testing authorization tools. UART communication has a complete set of command formats. For details, refer to the Bluetooth General Production Test Authorization Agreement.
The tuya ble sdk includes the UART communication instruction parsing function. The Application only needs to call the tuya_ble_common_uart_receive_data() function where UART data is received. The Application can also parse out the complete UART communication instruction, and then call tuya_ble_common_uart_send_full_instruction_received() function to send a complete command to tuya ble sdk.
tuya_ble_device_update_product_id
Function name | tuya_ble_device_update_product_id |
Prototype | tuya_ble_status_t tuya_ble_device_update_product_id. (tuya_ble_product_id_type_t type, uint8_t len, uint8_t* p_buf) |
Description | Updates product id function. |
Parameters | type [in]: id type. len[in]: id length. p_buf[in]: id data. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INTERNAL: internal error. |
Notice | In the SoC development scheme based on tuya ble sdk, it is generally not necessary to call this function, because the product ID generally does not change. |
tuya_ble_device_update_login_key
Function name | tuya_ble_device_update_login_key |
Prototype | tuya_ble_status_t tuya_ble_device_update_login_key(uint8_t* p_buf, uint8_t len) |
Description | Updates login key function. |
Parameters | len[in]: length. p_buf[in]: loginkey. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INTERNAL: internal error. |
Notice | This API is mainly used in Wi-Fi/BLE dual-protocol devices. Send network configuration information to Wi-Fi through BLE. The device registers the device with the cloud through Wi-Fi and calls. the login key after successful registration This function is sent to tuya ble sdk, but also needs to update the binding status. |
tuya_ble_device_update_bound_state
Function name | tuya_ble_device_update_bound_state |
Prototype | tuya_ble_status_t tuya_ble_device_update_bound_state(uint8_t state) |
Description | Updates registration binding status. |
Parameters | state[in]: 1-The device is registered for binding，0-The device is not registered for binding. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INTERNAL: internal error. |
Notice | This API is mainly used in Wi-Fi/BLE dual-protocol devices. (After the device registers and binds successfully through the Wi-Fi link, this function is called to update the binding status to tuya ble sdk. It also requires updating login key). |
tuya_ble_device_update_mcu_version
Function name | tuya_ble_device_update_mcu_version |
Prototype | tuya_ble_status_t tuya_ble_device_update_mcu_version(uint32_t mcu_firmware_version, uint32_t mcu_hardware_version) |
Description | Updates external mcu version number. |
Parameters | mcu_firmware_version [in]: MCU Firmware version number，For example, 0x010101 indicates v1.1.1. mcu_hardware_version [in]: MCU hardware version number (PCBA version number). |
Responses | TUYA_BLE_SUCCESS: Sent successfully. Other: failed. |
Notice | The API is mainly used to develop BLE module, SoC development program does not need to use. |
tuya_ble_sdk_init
Function name | tuya_ble_sdk_init |
Prototype | tuya_ble_status_t tuya_ble_sdk_init(tuya_ble_device_param_t * param_data) |
Description | The tuya ble sdk initialization function. |
Parameters | param_data [in]: Initialize parameter. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. |
Notice | Initialization function, the Application must call this function to initialize the SDK, otherwise the SDK will not work.
The initialization function may also be |
Parameter explanation:
The structure of tuya_ble_device_param_t is as follows:
The following items describe the variables in the preceding snippet.
device_id and auth_key: the device_uuid and the auth_key are unique identifier pairs assigned to the BLE devices by the Tuya IoT platform. They are required when you perform the production testing authorization via Tuya testing tool. After a BLE device is authorized by production testing, the tuya ble sdk takes control of and manages them automatically. Therefore, you can set the device_uuid ad the auth_key to 0 when the tuya ble sdk is initialized. If they are not 0, the tuya ble sdk uses the pre-defined device_id and auth_key. For a Wi-Fi/BLE dual-mode device, itsdevice_id and auth_key are managed by the Wi-Fi layer, therefore, the actual device_id and auth_key are needed when the tuya ble sdk is initialized.
product_id: pid for short. It is automatically generated when a new product is created on the IoT platform. In your Application, the PID needs to be saved in the form of a constant. It is required when initializing the tuya ble sdk.
device_vid: the virtual ID of a BLE device, which is generated by Tuya IoT platform after the binding of the notice volume. It can be used to find the data record of the cloud to the BLE device when the BLE device is added or removed. For BLE devices that need the authorization information of the tuya ble sdk management, the value is 0. For Wi-Fi/BLE dual mode devices, or BLE devices of which the authorization is managed by your Application, the actual device_vid is needed.
login_key and bound_flag: if the authorization of BLE devices are managed by the tuya ble sdk, set the values to 0. For Wi-Fi/BLE dual mode devices, or BLE devices of which the authorization is managed by your Application, the actual values are needed.
firmware_version and hardware_version: indicates the firmware version number and the hardware (PCBA) version number of BLE devices. They are required when initializing the tuya ble sdk. Currently, BLE devices only support two digit version numbers, for example 0x0100 represents v1.0.
The following snippet is the initialization example of tuya ble sdk for nrf52832 platform.
tuya_ble_sdk_init_async
Function name | tuya_ble_sdk_init_async |
Prototype | void tuya_ble_sdk_init_async(tuya_ble_device_param_t * param_data,tuya_ble_nv_async_callback_t callback) |
Description | The tuya ble sdk initialization function, mainly used in tuya ble sdk of asynchronous flash operation architecture. |
Parameters | param_data [in]: Initialize parameter. callback[in]: Callback， This callback will be executed automatically after the initialization is completed. |
Responses | None. |
Notice | The tuya ble sdk Asynchronous initialization function, the Application must call this function to initialize the SDK, otherwise the SDK will not work. |
Example of tuya ble sdk asynchronous initialization:
tuya_ble_dp_data_report
Function name | tuya_ble_dp_data_report |
Prototype | tuya_ble_status_t tuya_ble_dp_data_report(uint8_t *p_data,uint32_t len) |
Description | Reports dp point data to APP. |
Parameters | p_data [in]: dp point data.
len[in]: Data length，Cannot exceed |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter invalid. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection. TUYA_BLE_ERR_NO_MEM: Memory Application failed. TUYA_BLE_ERR_INVALID_LENGTH: Data length error . TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | Application reports DP data to mobile App by calling this function. |
parameter description:
Tuya IoT platform manages data in the form of dp points. The data generated by any device needs to be abstracted in the form of dp points. A complete dp point data consists of four parts (refer to the relevant introduction on the IoT platform for details):
Dp_id: 1 byte, dp_id serial number registered in the development platform.
Dp_type: 1 byte, dp point type.
#define DT_RAW 0 //raw type
#define DT_BOOL 1 //Boolean type
#define DT_VALUE 2 //Value type
#define DT_STRING 3 //String type
#define DT_ENUM 4 //Enumeration type
#define DT_BITMAP 5 // Bitmap type
Dp_len: Bluetooth currently supports only one byte, that is, the longest data of a single dp point is 255 bytes.
Dp_data: Data, dp_len bytes.
The dp point reporting function, the data pointed to by parameter p_data must be assembled and reported in the form of a table:
Dp point 1 data | ~ | Dp point n data | ||||||
1 | 2 | 3 | 4~ | ~ | n | n+1 | n+2 | n+3~ |
Dp_id | Dp_type | Dp_len | Dp_data | ~ | Dp_id | Dp_type | Dp_len | Dp_data |
When calling this function, the maximum length of parameter len is TUYA_BLE_REPORT_MAX_DP_DATA_LEN (currently 255+3).
tuya_ble_dp_data_with_time_report
Function name | tuya_ble_dp_data_with_time_report |
Prototype | tuya_ble_status_t tuya_ble_dp_data_with_time_report(uint32_t timestamp,uint8_t *p_data,uint32_t len) |
Description | Reports dp point data with time stamp. |
Parameters | timestamp[in]: 4 byte Unix timestamp.
p_data [in] :dp data.
len[in]: The data length cannot exceed |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection; TUYA_BLE_ERR_NO_MEM: Memory Application failed. TUYA_BLE_ERR_INVALID_LENGTH: Data length error. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | The Application code reports dp point data to the App with time stamp by calling this function. Generally, data that is cached offline needs to be reported with time stamp. |
tuya_ble_dp_data_with_time_ms_string_report
Function name | tuya_ble_dp_data_with_time_ms_string_report |
Prototype | tuya_ble_status_t tuya_ble_dp_data_with_time_ms_string_report(uint8_t *time_string,uint8_t *p_data,uint32_t len) |
Description | Reports dp point data with string format time. |
Parameters | time_string[in]: 13 byte ms level string format time.
p_data [in]: dp point data.
Len[in]: Data length, the maximum cannot exceed |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection. TUYA_BLE_ERR_NO_MEM: Memory Application failed. TUYA_BLE_ERR_INVALID_LENGTH: Data length error. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | The Application code reports dp point data to the App with string format time by calling this function. generally offline data only needs to be reported with time. 13 byte ms level time string, such as "0000000123456" ", less than 13 bytes before the supplementary character 0. |
tuya_ble_dp_data_with_flag_report
Function name | tuya_ble_dp_data_with_flag_report |
Prototype | tuya_ble_status_t tuya_ble_dp_data_with_flag_report(uint16_t sn,tuya_ble_report_mode_t mode,uint8_t *p_data,uint32_t len) |
Description | Reports dp point data with flag. |
Parameters | sn[in]: Application defined serial number.
mode[in]: Reporting mode.
p_data [in]: dp point data.
len[in]: dp point data length, the maximum cannot exceed |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection; TUYA_BLE_ERR_NO_MEM: Memory Application failed. TUYA_BLE_ERR_INVALID_LENGTH: Data length error. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | Application calls this function to report the marked DP point data to the App. |
parameter description:
mode:
REPORT_FOR_CLOUD_PANEL: report to the panel and the cloud at the same time.
REPORT_FOR_CLOUD: only report to the cloud.
REPORT_FOR_PANEL: only report to the panel.
REPORT_FOR_NONE: neither reported to the panel nor to the cloud.
tuya_ble_dp_data_with_flag_and_time_report
Function name | tuya_ble_dp_data_with_flag_and_time_report |
Prototype | tuya_ble_status_t tuya_ble_dp_data_with_flag_and_time_report (uint16_t sn,tuya_ble_report_mode_t mode,uint32_t timestamp,uint8_t *p_data,uint32_t len) |
Description | Reports dp point data with time stamp. |
Parameters | sn[in]: Application defined serial number.
mode[in]: reporting mode.
timestamp[in]: 4 byte Unix timestamp.
p_data [in]: dp data.
len[in]: dp point data length, the maximum cannot exceed |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection. TUYA_BLE_ERR_NO_MEM: Memory Application failed. TUYA_BLE_ERR_INVALID_LENGTH: Data length error. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | The Application code reports dp point data to the App with timestamp by calling this function. Generally, data that is cached offline needs to be reported with a time stamp. |
tuya_ble_dp_data_with_flag_and_time_ms_string_report
Function name | tuya_ble_dp_data_with_flag_and_time_ms_string_report |
Prototype | tuya_ble_status_t tuya_ble_dp_data_with_flag_and_time_ms_string_report (uint16_t sn,tuya_ble_report_mode_t mode,uint8_t *time_string,uint8_t *p_data,uint32_t len) |
Description | Reports dp point data with string formatted time with flag. |
Parameters | sn[in]: Application defined serial number.
mode[in]: reporting mode.
time_string[in]: 13-byte ms-level string format time;
p_data [in]: dp point data.
Len[in]: data length, the maximum cannot exceed |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection. TUYA_BLE_ERR_NO_MEM: Memory Application failed. TUYA_BLE_ERR_INVALID_LENGTH: Data length error. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | The Application code reports dp point data to the App with string format time by calling this function. generally offline data only needs to be reported with time. 13 byte ms level time string, such as "0000000123456" ", less than 13 bytes before the supplementary character 0. |
tuya_ble_connected_handler
Function name | tuya_ble_connected_handler |
Prototype | void tuya_ble_connected_handler(void) |
Description | Bluetooth connection callback function. |
Parameters | None. |
Responses | None. |
Notice | The Application code needs to call this function at the Bluetooth connection callback of the chip platform SDK. tuya ble sdk is based on this function to manage the internal Bluetooth connection state. |
tuya_ble_disconnected_handler
Function name | tuya_ble_disconnected_handler |
Prototype | void tuya_ble_disconnected_handler(void) |
Description | Bluetooth disconnection callback function. |
Parameters | None. |
Responses | None. |
Notice | The Application code needs to call this function at the Bluetooth disconnection callback of the chip platform SDK. The tuya ble sdk manages the internal Bluetooth connection state according to the execution of this function. |
Example of calling tuya_ble_connected_handler and tuya_ble_disconnected_handler on nrf52832 platform:
tuya_ble_adv_data_connecting_request_set
Function name | tuya_ble_adv_data_connecting_request_set |
Prototype | tuya_ble_status_t tuya_ble_adv_data_connecting_request_set(uint8_t on_off) |
Description | Triggers broadcast packet change request connection flag. |
Parameters | on_off[in]: 0 - Clear flag，1 - set flag. |
Responses | TUYA_BLE_SUCCESS: success. TUYA_BLE_ERR_INVALID_STATE: The current state is not supported, for example, it is currently connected. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_NO_EVENT: Other errors. |
tuya_ble_data_passthrough
Function name | tuya_ble_data_passthrough |
Prototype | tuya_ble_status_t tuya_ble_data_passthrough(uint8_t *p_data,uint32_t len) |
Description | Passes through the custom data of the Application. |
Parameters | p_data [in]: data pointer that needs to be transparently transmitted.
len[in]: data length, the maximum cannot exceed |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection. TUYA_BLE_ERR_INVALID_LENGTH: Data length error. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | Application transparently transmits data to App by calling this function. The transparently transmitted data format is negotiated by the device Application and the mobile App, and tuya ble sdk does not parse it. |
tuya_ble_production_test_asynchronous_response
Function name | tuya_ble_production_test_asynchronous_response |
Prototype | tuya_ble_status_t tuya_ble_production_test_asynchronous_response (uint8_t channel,uint8_t *p_data,uint32_t len) |
Description | Asynchronously respond to the production testing command. |
Parameters | Channel[in]: Transmission channel，0-uart;1-ble. p_data [in]: complete command data that needs to be responded to. len[in]: Data length. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection. TUYA_BLE_ERR_INVALID_LENGTH: Data length error. TUYA_BLE_ERR_NO_MEM: Failed to apply for memory. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | When performing production testing (production testing authorization is through UART, the whole machine test passes BLE) Some test items can not immediately respond to the results of the upper computer production testing tool, or some test items need to be processed by the Application. At this time, you need to call this function to send the test results to the upper computer production testing tool. |
tuya_ble_net_config_response
Function name | tuya_ble_net_config_response |
Prototype | tuya_ble_status_t tuya_ble_net_config_response(int16_t result_code) |
Description | Responds the Wi-Fi network configuration request. |
Parameters | Result_code[in]: status code. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | Suitable for Wi-Fi / BLE combo devices. |
tuya_ble_ubound_response
Function name | tuya_ble_ubound_response |
Prototype | tuya_ble_status_t tuya_ble_ubound_response(uint8_t result_code) |
Description | Responds to the removal requests of multi-protocol combo device. |
Parameters | Result_code[in]: status code, 0 - success，1 - fail. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection.TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | Suitable for Wi-Fi / BLE combo devices. |
tuya_ble_anomaly_ubound_response
Function name | tuya_ble_anomaly_ubound_response |
Prototype | tuya_ble_status_t tuya_ble_anomaly_ubound_response (uint8_t result_code) |
Description | Responds to the abnormal removal requests of multi-protocol combo device. |
Parameters | Result_code[in]: status code，0 - success，1 - fail. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection. TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | Suitable for Wi-Fi / BLE combo devices. |
tuya_ble_device_reset_response
Function name | tuya_ble_device_reset_response |
Prototype | tuya_ble_status_t tuya_ble_device_reset_response (uint8_t result_code) |
Description | Responds to the reset requests of multi-protocol combo device. |
Parameters | Result_code[in]: status code，0 - success，1 - fail. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_STATE: The current status does not support sending, such as Bluetooth disconnection.TUYA_BLE_ERR_NO_EVENT: Other errors. |
Notice | Suitable for Wi-Fi / BLE combo devices. |
tuya_ble_connect_status_get
Function name | tuya_ble_connect_status_get |
Prototype | tuya_ble_connect_status_t tuya_ble_connect_status_get(void) |
Description | Gets current BLE connection status |
Parameters | None. |
Responses |
|
Responses description:
tuya_ble_device_factory_reset
Function name | tuya_ble_device_factory_reset |
Prototype | tuya_ble_status_t tuya_ble_device_factory_reset(void) |
Description | Resets BLE devices. |
Parameters | None. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INTERNAL: Other errors. |
Notice | For devices that define an external key reset function, the Application needs to call this function to notify tuya ble sdk to reset related information after the key triggers a reset, such as clearing binding information. |
tuya_ble_time_req
Function name | tuya_ble_time_req |
Prototype | tuya_ble_status_t tuya_ble_time_req(uint8_t time_type) |
Description | Requests cloud time. |
Parameters | time_type[in]: 0 - Request time in 13-byte ms-level string format. 1 - Find the year, month, day, hour, minute, second, week format time. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_PARAM: parameter error. TUYA_BLE_ERR_INTERNAL: Other errors. |
Notice | 13 byte string time format: "0000000123456" means 123456 ms timestamp. normal time format: 0x13,0x04,0x1C,0x0C,0x17,0x19,0x02 means: April 28, 2019 :23:25 Tuesday. tuya ble sdk will send the corresponding instruction to the App after receiving the request, sdk will send a message to the device Application after receiving the time returned by the App. |
tuya_ble_ota_response
Function name | tuya_ble_ota_response |
Prototype | tuya_ble_status_t tuya_ble_ota_response(tuya_ble_ota_response_t *p_data) |
Description | OTA response command. |
Parameters | p_data[in]: OTA response data. |
Responses | TUYA_BLE_SUCCESS: Sent successfully. TUYA_BLE_ERR_INVALID_STATE: State error. TUYA_BLE_ERR_INVALID_LENGTH: Data length error. TUYA_BLE_ERR_NO_MEM: Memory Application fail. TUYA_BLE_ERR_INTERNAL: Other errors. |
Notice | See the OTA introduction chapter for the specific format. |
tuya_ble_custom_event_send
Function name | tuya_ble_custom_event_send |
Prototype | uint8_t tuya_ble_custom_event_send(tuya_ble_custom_evt_t evt) |
Description | Sends Application custom message and callback to tuya ble sdk. |
Parameters | evt[in]: Custom event. |
Responses | 0: Sent successfully. 1: fail. |
Notice | typedef struct{ void *data; void (*custom_event_handler)(void*data); } tuya_ble_custom_evt_t; |
Description: This function is mainly used when the Application wants to use the internal message scheduler of tuya ble sdk to process the Application's message events.
tuya_ble_custom_event_sendApplication examples:
tuya_ble_callback_queue_register
Function name | tuya_ble_callback_queue_register |
Prototype | prototype 1: tuya_ble_status_t tuya_ble_callback_queue_register(void *cb_queue). prototype 2: tuya_ble_status_t tuya_ble_callback_queue_register(tuya_ble_callback_t cb). |
Description | To register the message queue for receiving tuya ble sdk messages under the OS platform architecture, use prototype 1. To register callback function for receiving tuya ble sdk messages under OS-less platform architecture, use prototype 2. |
Parameters | cb_queue [in]: message queue. cb[in]: callback Function address. |
Responses | TUYA_BLE_ERR_RESOURCES: Register fail. TUYA_BLE_SUCCESS: Register success. |
Application examples for OS platform:
Application example without OS platform:
tuya_ble_event_response
Function name | tuya_ble_event_response |
Prototype | tuya_ble_status_t tuya_ble_event_response(tuya_ble_cb_evt_param_t *param) |
Description | Responds to tuya ble sdk messages under the OS platform architecture. |
Parameters | param [in]: message pointer. |
Responses | TUYA_BLE_SUCCESS: success. other: fail. |
Notice | Under the OS platform architecture, after the Application code processes the message sent by tuya ble sdk， Must call this function to give feedback to tuya ble sdk. |
Application examples:
tuya_ble_scheduler_queue_size_get
Function name | tuya_ble_scheduler_queue_size_get |
Prototype | uint16_t tuya_ble_scheduler_queue_size_get(void) |
Description | Gets the total size of tuya ble sdk scheduler queue in platforms that have no OS. |
Parameters | None. |
Responses | Total size of the scheduler queue. |
tuya_ble_scheduler_queue_space_get
Function name | tuya_ble_scheduler_queue_space_get |
Prototype | uint16_t tuya_ble_scheduler_queue_space_get(void) |
Description | Gets the idle number of tuya ble sdk scheduler queue in platforms that have no OS. |
Parameters | None. |
Responses | Scheduler queue idle. |
tuya_ble_scheduler_queue_events_get
Function name | tuya_ble_scheduler_queue_events_get |
Prototype | uint16_t tuya_ble_scheduler_queue_events_get(void) |
Description | Gets the number of unprocessed events in the tuya ble sdk scheduler queue in platforms that have no OS. |
Parameters | None. |
Responses | The number of unprocessed events in the scheduler queue. |
The tuya ble sdk sends message of status, data, and other information to Application through message (for OS architecture platform) or callback function registered by Application (for non-OS architecture platform). According to the previous section, the example of tuya_ble_event_response describes how the Application in the OS architecture platform handle the messages sent by tuya ble sdk. The chip platform without an OS can use the similar code to process messages, however it is not necessary to call the tuya_ble_event_response() to respond to tuya ble sdk after the messages is handled by the callback function. As the following snippet shows an example for callback registration in the platform without an OS.
TUYA_BLE_CB_EVT_CONNECTE_STATUS
Event | TUYA_BLE_CB_EVT_CONNECTE_STATUS |
Description | Every time the state changes, tuya ble sdk will send the event to the device Application |
Corresponding data structure:
TUYA_BLE_CB_EVT_DP_WRITE
Event | TUYA_BLE_CB_EVT_DP_WRITE |
Description | The tuya ble sdk received dp point data sent by mobile App. |
Notice | See format |
Corresponding data structure:
TUYA_BLE_CB_EVT_DP_QUERY
Event | TUYA_BLE_CB_EVT_DP_QUERY |
Description | The dp point to be checked, which is sent from the mobile App. |
Notice | data_len=0 means to query all dp points, otherwise each byte pointed to by p_data represents a dp point to be queried, for example, data_len=3, p_data{0x01,0x02,0x03}, means to query dp_id=1, dp_id=2 , dp_id=3 data of 3 dp points. |
Corresponding data structure:
TUYA_BLE_CB_EVT_OTA_DATA
Event | TUYA_BLE_CB_EVT_OTA_DATA |
Description | tuya ble sdk received the OTA data sent by the mobile App. |
Notice | See the OTA section for details. |
Corresponding data structure:
TUYA_BLE_CB_EVT_NETWORK_INFO
Event | TUYA_BLE_CB_EVT_NETWORK_INFO |
Description | The tuya ble sdk received Wi-Fi distribution information sent by the mobile app, for example:
|
Notice | Only applicable to Wi-Fi / BLE dual protocol combo devices. |
Corresponding data structure:
TUYA_BLE_CB_EVT_WIFI_SSID
Event | TUYA_BLE_CB_EVT_WIFI_SSID |
Description | tuya ble sdk received Wi-Fi distribution information sent by the mobile app, for example: "{"wifi_ssid":"tuya","password":"12345678"}". |
Notice | Only applicable to Wi-Fi / BLE dual protocol combo devices，Compared with |
Corresponding data structure:
TUYA_BLE_CB_EVT_TIME_STAMP
Event | TUYA_BLE_CB_EVT_TIME_STAMP |
Description | The tuya ble sdk received the timestamp in the format of a string sent by the mobile phone app, for example, |
Notice | time_zone The time zone is 100 times the actual time zone, for example, -8 zone is -800. |
Corresponding data structure:
TUYA_BLE_CB_EVT_TIME_NORMAL
Event | TUYA_BLE_CB_EVT_TIME_NORMAL |
Description | tuya ble sdk received the time in the conventional format sent by the mobile app, for example: UTC +8, Tuesday, April 28, 2019 12:23:25. corresponding data: 0x13, 0x04, 0x1C, 0x0C, 0x17, 0x19, 0x02 (week), 0x0320 (time zone time_zone). |
Corresponding data structure:
TUYA_BLE_CB_EVT_DATA_PASSTHROUGH
Event | TUYA_BLE_CB_EVT_DATA_PASSTHROUGH |
Description | The tuya ble sdk received the transparent transmission data sent by the mobile app. |
Notice | The tuya ble sdk does not parse transparently transmitted data, and the data format is negotiated and defined by the device Application and mobile App. |
Corresponding data structure:
TUYA_BLE_CB_EVT_DP_DATA_REPORT_RESPONSE
Event | TUYA_BLE_CB_EVT_DP_DATA_REPORT_RESPONSE |
Description | After the Device Application calls the |
Corresponding data structure:
TUYA_BLE_CB_EVT_DP_DATA_WTTH_TIME_REPORT_RESPONSE
Event | TUYA_BLE_CB_EVT_DP_DATA_WTTH_TIME_REPORT_RESPONSE |
Description | Device Application calls |
Corresponding data structure:
TUYA_BLE_CB_EVT_DP_DATA_WITH_FLAG_REPORT_RESPONSE
Event | TUYA_BLE_CB_EVT_DP_DATA_WITH_FLAG_REPORT_RESPONSE |
Description | After the Application calls the |
Notice | Device Application can determine which response point of dp point data is sent according to the serial number. |
Corresponding data structure:
TUYA_BLE_CB_EVT_DP_DATA_WITH_FLAG_AND_TIME_REPORT_RESPONSE
Event | TUYA_BLE_CB_EVT_DP_DATA_WITH_FLAG_AND_TIME_REPORT_RESPONSE |
Description | Device Application calls |
Notice | Device Application can determine which response point of dp point data is sent according to the serial number. |
Corresponding data structure:
TUYA_BLE_CB_EVT_UNBOUND
Event | TUYA_BLE_CB_EVT_UNBOUND |
Description | Receiving the Event means that the mobile phone App sends an instruction to learn the binding. The data field is a reserved field and is not used for the time being. |
Corresponding data structure:
TUYA_BLE_CB_EVT_ANOMALY_UNBOUND
Event | TUYA_BLE_CB_EVT_ANOMALY_UNBOUND |
Description | Receiving the Event indicates that the mobile App sent an abnormal unbinding instruction, in which the data field is a reserved field and is not used for the time being. |
Corresponding data structure:
TUYA_BLE_CB_EVT_DEVICE_RESET
Event | TUYA_BLE_CB_EVT_DEVICE_RESET |
Description | Receiving the Event indicates that the mobile App has sent a reset command, where the data field is a reserved field and is not used for the time being. |
Notice | After the device Application receives the reset event, it needs to perform some operations defined by the reset function. |
Corresponding data structure:
TUYA_BLE_CB_EVT_UPDATE_LOGIN_KEY_VID
Event | TUYA_BLE_CB_EVT_UPDATE_LOGIN_KEY_VID |
Description | After the Notification book is bound to success, the mobile App will send the login key and device virtual ID to the device. |
Notice | The BLE device does not need to process this information. |
Corresponding data structure:
This section takes nrf52832 as an example to describe the porting steps for the OS-free architecture platforms. You can contact your account manager in Tuya for the detailed procedure of nrf52832 and the demo of other platforms.
Download the original SDK of nrf52832 chip, for example, nRF5_SDK_15.2.0_9412b96, and prepare a nrf52832 development board.
Unzip the SDK to a custom directory, as shown in the following picture.
Open the examples > ble_peripheral directories. In this directory, you can see tutorials of ble peripheral.
Create a project with ble_app_uart as the template, and copy the ble_app_uart folder and rename it (for example, tuya_ble_standard_nordic).
Enter the PCA10040 > S123 directories, open the project and compile it. You must confirm that it can be compiled and run correctly on the development board.
Create a file with the ble_nus.c in the nRF_BLE_Services directory as the template and tuya_ble_service.c as the name, modify your code to cater for the tuya ble service, modify the code in the main.c file and broadcast the changes according the broadcasting content specified in the previous introduction.
Compile and download to your development board and run, use Bluetooth scanning tool in your mobile phone (for example, LightBlue for iOS) to scan devices. Make sure that your scanning result meet the requirement of broadcasting and service.
Download the tuya ble sdk to the directory of a new project, add the source files to the project and compile for once.
Your project must have the same directories as the following pictures. Note that select correct library files.
Create a custom_tuya_ble_config.h file, and save to the directories of your project, for example, tuya_ble_app.
You must configure the items in the custom_tuya_ble_config.h according to your actual demand and environment. The tuya ble sdk provides references for some chip platforms. The reference configuration files are stored in each platform directory under the port directory in the tuya ble sdk folder.
Assign the name of custom_tuya_ble_config.h to the CUSTOMIZED_TUYA_BLE_CONFIG_FILE file, and add to the macro of your project.
Create port files, and the name can be tuya_ble_port_nrf52832.h and tuya_ble_port_nrf52832.c, or replace the nrf52832 with other platforms.
In the port file, implement the interfaces listed in the tuya_ble_port.h file according to your configurations. Not all of the listed interfaces need to be implemented, for example, this porting tutorial does not involve OS, therefore, the OS-specific APIs are not needed. This tutorial is configured to use the internal memory management module of tuya ble sdk, therefore the memory allocation and release APIs are not needed. Under the port file of the tuya ble sdk, every platform is provided with porting reference file with the platform as the file name.
After the port file is completed, define the port file in the custom_tuya_ble_config.h.
Compile. If the compiling fails, examine your code first.
In this tutorial, a specific file is created to handle the initialization of the tuya ble sdk, call back function registration, and callback message handling. As the following picture shows.
Register the product in the Tuya IoT console and copy the product ID to your project code. The macro name APP_PRODUCT_ID, APP_BUILD_FIRMNAME, TY_APP_VER_NUM, TY_APP_VER_STR, TY_HARD_VER_NUM, and TY_HARD_VER_STR cannot be changed. Replace the xxxxxxxx as the product ID. If you use the test and production tooling authorization, contact your Tuya account manager to create a project for you, and replace the tuya_ble_sdk_app_demo_nrf52832 as the project name.
Call the tuya_ble_app_init(), tuya_ble_main_tasks_exec(), tuya_ble_gatt_receive_data(), tuya_ble_common_uart_receive_data(), tuya_ble_disconnected_handler(), and tuya_ble_connected_handler() respectively in your code, as the following picture shows.
During the development and debug stage, contact your Tuya account manager to obtain the auth_key_test and device_id_test.
Compile your code, download the code to the development board, download Tuya Smart App, and scan to add devices.
The firmware upgrade and the chip platform architecture are related, therefore the tuya ble sdk only provides a firmware upgrade interface, and your Application only needs to be implemented according to the OTA protocol described below through the OTA communication interface provided by tuya ble sdk.
The Application receives OTA data through the registered callback function (if the chip platform does not have OS) or registered queue (if the chip platform has an OS), the EVENT ID is TUYA_BLE_CB_EVT_OTA_DATA.
For the data format, see the upgrade protocol section. And the OTA response data is sent through the tuya_ble_ota_response(tuya_ble_ota_response_t *p_data) function.
The following picture illustrates the process of OTA upgrade.
OTA data types
OTA upgrade request (TUYA_BLE_OTA_REQ)
From App to BLE devices
data_len=1 | |
Length: | 1 byte |
Data: | fixed 0 |
From BLE devices to App
data_len=9 | |||||
Length: | 1 byte | 1 byte | 1 byte | 4 byte | 2 byte |
Data: | Flag | OTA_Version | 0 | Version | Maximum packet length. |
Flag: 0x00 indicates upgrade confirmation, 0x01 indicates upgrade denial.
OTA_Version: OTA Protocol version, for example 0x03 indicates the protocol version of 3.X.
Version: the current firmware version number in the big-endian format. For example, 0x00 01 00 02 indicates the version number is V1.0.2.
Maximum packet length: the maximum length of a single packet allowed by the device, unit: byte. The current version cannot exceed 512 bytes.
OTA upgrade file information (TUYA_BLE_OTA_FILE_INFO)
From App to BLE devices
data_len=37 | ||||||
Length: | 1 byte | 8 byte | 4 byte | 16 byte | 4 byte | 4 byte |
Data: | 0 | product id | file version | file MD5 | file length | CRC32 |
product id: the PID.
file version: for example, 0x00010002 indicates the version is V1.0.2.
From BLE devices to App
data_len=26 | |||||
Length: | 1 byte | 1 byte | 4 byte | 4 byte | 16 byte |
Data: | 0 | STATE | Saved data length | Saved data CRC32 | saved data MD5 (Not used currently) |
STATE:
0x00: upgrade success
0x01: PID different
0x02: the file version is lower than or equal to the current version
0x03: file size is out of range.
Other: a reserved field.
File information has been saved: to support the resuming of the breakpoint, the file information that are stored in the device will be returned. After receiving the infomration, the App first calculates the CRC32 of the corresponding length of the new file according to the length of the stored file returned by the device, and then compares it with the CRC32 returned by the device. If the both are consistent, then in the following file start transmission request, the start transmission offset is changed to the length value. Otherwise, the file start transmission offset is changed to 0, indicating that the transmission starts from the beginning.
OTA upgrade file offset (TUYA_BLE_OTA_FILE_OFFSET_REQ)
From App to BLE devices
data_len=5 | ||
Length: | 1 byte | 4 byte |
Data: | 0 | Offset |
offset: upgrade file offset.
From BLE devices to App
data_len=5 | ||
Length: | 1 byte | 4 byte |
Data: | 0 | Offset |
offset: the starting file offset required by the device. The offset address of the actual file transfer should be based on the device requirements, and the address required by the device will be less or equal to the offset given by the App.
OTA Upgrade data (TUYA_BLE_OTA_DATA)
From App to BLE devices
data_len=7+n | |||||
Length: | 1 byte | 2 byte | 2 byte | 2 byte | n byte |
Data: | 0 | Package number | Current package data length n | Current package data CRC16 | Current package data |
The packet number starts from 0, and the high byte is at the beginning of the packet.
From BLE devices to App
data_len=2 | ||
Length: | 1 byte | 1 byte |
Data: | 0 | STATE |
STATE:
0x00: success
0x01: the package number is abnormal
0x02: the length is inconsistent
0x03: CRC check fails
0x04: others
OTA upgrade is over (TUYA_BLE_OTA_END)
From App to BLE devices
data_len=1 | |
Length: | 1 byte |
Data: | 0 |
From BLE devices to App
data_len=2 | ||
Length: | 1 byte | 1 byte |
Data: | 0 | STATE |
STATE:
0x00: success
0x01: the total data length is wrong
0x02: the total CRC of data check fails
0x03: others
If you need to restart after verifying the success of the ble device OTA file, you can call the API tuya_ble_ota_response(tuya_ble_ota_response_t *p_data) to respond to the App result at least no delay and restart after 2 seconds.
The Application receives OTA data through the registered callback function (without RTOS environment) or registered queue (in the RTOS environment), the EVENT ID is TUYA_BLE_CB_EVT_OTA_DATA. And the OTA response data is sent through tuya_ble_ota_response(tuya_ble_ota_response_t *p_data) function.
As the following picture shows, the Application calls the custom OTA processing function.
An example of OTA processing function:
Before BLE devices are connected to Tuya IoT development platform, they must be burned with license information (one set of licenses for one device), which is usually burned in factory production. You can also use Tuya production testing tools to burn license and test. Alternatively, you can purchase licenses in batches, and use custom protocol and interface to manage them.
If you use custom protocol, you must set the auth_key and device_id when you initialize the tuya ble sdk. As the following sample shows.
If you use the authorization tool of Tuya production testing to burn the license and you use the tuya ble sdk to manage authorization, then the auth_key and device_id are not needed when you initialize the tuya ble sdk. As the following sample shows.
If you use the authorization tool of Tuya production testing to burn the license, make sure that the TUYA_BLE_DEVICE_AUTH_SELF_MANAGEMENT is enabled by setting #define TUYA_BLE_DEVICE_AUTH_SELF_MANAGEMENT 1.
The production testing consists of the general authorization testing and the general device testing, and the general machine testing is subordinate to the general authorization testing. The general authorization testing includes authorization burning, GPIO testing and RSSI testing. The general device testing provides additional testing for tailored products, you can see the Bluetooth General Authorization Protocol of Production Testing or Bluetooth General Device Testing Protocol of Production Testing for more information.
The tuya ble sdk has achieved the protocol of general authorization testing, however, testing such as RSSI testing, GPIO testing and additional testing for tailored products provided by general device testing must be implemented according to the product configuration. The source file tuya_ble_app_production_test.c in the tuya ble sdk has prepared APIs for the preceding testings, and they are defined in the form of __TUYA_BLE_WEAK weak implement. Your Application can redefine those APIs in other source files, for example, creating a custom_app_product_test.c file, and referring to it in your custom configuration file. As the following pictures show.
