Bluetooth Remotes

This topic describes how Wi-Fi and Bluetooth combo devices are controlled through physical Bluetooth remotes.

Features

• Bind or unbind a Tuya-enabled Bluetooth remote.
• Receive control commands from a Tuya-enabled Bluetooth remote.
• Synchronize the bound Tuya-enabled Bluetooth remote with the cloud.
• Pass through the custom remote data.

How it works

Prerequisites for enabling Bluetooth scan

• Before device initialization, the application has registered the callback for handling Bluetooth remote data.

• The framework turns on Bluetooth scan after device initialization.

• The device is either not in pairing mode or has already obtained the Wi-Fi SSID and password during the pairing process.

  Enabling Bluetooth scan can compromise the success rate of pairing a combo device.

Binding process

Timing to turn on the binding window

• The Bluetooth scan is on.

• When an unpaired and inactivated device is powered on and enters low power mode, the framework will automatically turn on the binding window.

• After the device obtains Wi-Fi SSID and password in pairing mode, the framework will automatically turn on the binding window.

• After an activated device is powered on, the framework will automatically turn on the binding window during device initialization.

• The application calls the binding window API to turn it on.

Unbinding process

Development guide

Runtime environment

Open tuya_iot_config.h and check if the following macro is defined.

#define ENABLE_BT_REMOTE_CTRL 1

Reference the header

• tuya_bt.h

How to use

• Register the callback tuya_ble_reg_app_scan_adv_cb for receiving data from the Tuya-enabled Bluetooth remote.
• For a custom Bluetooth remote, you also need to register the callback tuya_ble_reg_raw_scan_adv_cb for receiving custom data.
• Call the device initialization API.
• After the framework receives the data, it notifies the application to process and handle the data accordingly.

API description

Register the callback for receiving data from Tuya-enabled Bluetooth remotes

This callback returns the command received from the Tuya-enabled Bluetooth remote.

//Callback function for advertisement scanning data processing
//type: 0xFF old remote
//       0x16 new remote
typedef VOID (*TUYA_BLE_APP_SCAN_HANDLE)(UCHAR_T *data, UCHAR_T len, UCHAR_T type, UCHAR_T* mac);

/**
 * @brief Register callback function for advertisement scanning data processing
 *
 * @param[in] cb: callback function
 *
 * @note This API is used for registering callback function for advertisement scanning data processing
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ble_reg_app_scan_adv_cb(TUYA_BLE_APP_SCAN_HANDLE cb);

Register the callback for binding/unbinding notification

This callback notifies the result of binding or unbinding a Tuya-enabled Bluetooth remote.

//Callback function for validity check for bind or unbind operation
typedef OPERATE_RET(*BLE_SCAN_ADV_BIND_CHECK_CB)(TUYA_BLE_BIND_TYPE type, UCHAR_T *data, UCHAR_T len);
//Callback function for result notify for bind or unbind operation
typedef VOID_T(*BLE_SCAN_ADV_BIND_RSLT_NOTIFY_CB)(TUYA_BLE_BIND_TYPE type, int rslt);

typedef struct {
    BLE_SCAN_ADV_BIND_CHECK_CB       bind_check;
    BLE_SCAN_ADV_BIND_RSLT_NOTIFY_CB bind_notify;
} TUYA_BLE_SCAN_ADV_HANDLE_CBS;

/**
 * @brief Register callback function for advertisement scanning data processing
 *
 * @param[in] cbs: callback function
 *
 * @note This API is used for registering callback function for inform binding/unbinding state
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ble_reg_app_scan_adv_handle_cbs(TUYA_BLE_SCAN_ADV_HANDLE_CBS* cbs);

Set the binding window duration

If the duration is less than 30 seconds, it will be treated as 30 seconds. If you set the duration to 0, the device will stay in binding mode forever.

/**
 * @brief Set timeout window for binding remote controller
 *
 * @param[in] time_out: time out in second, 0: no window
 *
 * @note This API is used for setting timeout window for binding remote controller
 *
 * @return VOID
 */
VOID_T tuya_ble_set_bind_window(UINT_T time_out);

Turn on the binding window

The framework will automatically turn on the binding window at the specified time mentioned above. The application can call this API to turn on the binding window when needed.

/**
 * @brief Open window for binding remote controller
 *
 * @param[in] VOID
 *
 * @note This API is used for opening window for binding remote controller
 *
 * @return VOID
 */
VOID_T tuya_ble_open_bind_window(VOID_T);

Register the callback for receiving custom data

The framework will pass the advertising data it receives to the application using a callback. See the previous section for the prerequisites to enable the Bluetooth scan.

/**
 * @brief Register callback function for advertisement scanning raw data processing
 *
 * @param[in] cb: callback function
 *
 * @note This API is used for registering callback function for advertisement scanning raw data processing
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ble_reg_raw_scan_adv_cb(TUYA_BLE_RAW_SCAN_HANDLE cb);

Example

service_ble_remote in TuyaOS example collection contains the complete example code.

FAQs

Why is data not being received even though the callback for receiving data has been registered?

Review the prerequisites to enable the Bluetooth scan.

Why is the device unable to receive data from a custom remote?

• Verify if you have registered the callback for receiving data from Tuya-enabled Bluetooth remotes.
• Verify if you have registered the callback for receiving data from custom Bluetooth remotes.
• Verify if the prerequisites for enabling Bluetooth scan have been met.
• Currently, only ADV_IND, SCAN_RSP, and NONCONN_IND advertising packets are supported.