Bluetooth Pairing

This topic describes TuyaOS Bluetooth Low Energy (LE) peripherals. For more information about the Bluetooth pairing process and API reference, see Bluetooth Pairing.

Overview

Tuya offers a range of cross-platform Bluetooth APIs to facilitate quick integration with the TuyaOS Bluetooth service. Implementing these APIs enables you to register specific Tuya services and securely exchange encrypted data. Using the Bluetooth LE peripheral API in the TuyaOS Kernel Layer (TKL), you can register necessary services, advertise information properly, and enable encrypted data exchange through read/write functions and callbacks.

Bluetooth LE peripheral API

//(Required) Register the GAP callback. When using peripherals, report the event, such as TKL_BLE_EVT_STACK_INIT, TKL_BLE_GAP_EVT_CONNECT, TKL_BLE_GAP_EVT_DISCONNECT, and TKL_BLE_GAP_EVT_CONN_PARAM_UPDATE accordingly. See TKL_BLE_GAP_EVT_TYPE_E in tkl_bluetooth_def.h for the event description.
OPERATE_RET tkl_ble_gap_callback_register(CONST TKL_BLE_GAP_EVT_FUNC_CB gap_evt);

//(Required) Register the GATT callback. When using peripherals, report the event, such as TKL_BLE_GATT_EVT_MTU_RSP and TKL_BLE_GATT_EVT_WRITE_REQ accordingly. See TKL_BLE_GATT_EVT_TYPE_E in tkl_bluetooth_def.h for the event description.
OPERATE_RET tkl_ble_gatt_callback_register(CONST TKL_BLE_GATT_EVT_FUNC_CB gatt_evt);

//(Required) Initialize the Bluetooth protocol stack. Implement it for your platform.
OPERATE_RET tkl_ble_stack_init(UCHAR_T role);

//(Required) See the `tal_ble_bt_init` function in `tal_bluetooth.c` for the service rule list. For Tuya-specific services, implement them as per services, characteristics, and descriptor rules.
OPERATE_RET tkl_ble_gatts_service_add(TKL_BLE_GATTS_PARAMS_T *p_service);

//(Required) The advertising function. When using peripherals, implement the following advertising functions, which are used to broadcast sub-device information to make it discoverable by the end devices for connection.
OPERATE_RET tkl_ble_gap_adv_stop(VOID);
OPERATE_RET tkl_ble_gap_adv_start(TKL_BLE_GAP_ADV_PARAMS_T CONST *p_adv_params);
OPERATE_RET tkl_ble_gap_adv_rsp_data_set(TKL_BLE_DATA_T CONST *p_adv, TKL_BLE_DATA_T CONST *p_scan_rsp);
// Note: Whether advertising is enabled for the update function depends on the last state. If your chip platform has this function, you can integrate it directly. Otherwise, record the advertising enablement status.
// Except for special products, after the Bluetooth connection is established, the update function is used to update data only, without advertising being enabled.
OPERATE_RET tkl_ble_gap_adv_rsp_data_update(TKL_BLE_DATA_T CONST *p_adv, TKL_BLE_DATA_T CONST *p_scan_rsp);

//(Required) The maximum transmission unit (MTU). When using peripherals, two parties will negotiate the MTU. Use the following function to request the MTU and the negotiated MTU will be sent to the service end through TAL_BLE_EVT_MTU_RSP.
OPERATE_RET tkl_ble_gattc_exchange_mtu_request(USHORT_T conn_handle, USHORT_T client_rx_mtu);

//(Required) Data exchange. When using peripherals, report sub-device data via notification through the following function.
OPERATE_RET tkl_ble_gatts_value_notify(USHORT_T conn_handle, USHORT_T char_handle, UCHAR_T *p_data, USHORT_T length);

//(Optional) Data exchange. When using peripherals, update the read characteristics through the value set function.
// If you only need the pairing feature, this function is optional.
OPERATE_RET tkl_ble_gatts_value_set(USHORT_T conn_handle, USHORT_T char_handle, UCHAR_T *p_data, USHORT_T length);

//(Optional) Update the connection parameters. When using peripherals, update the connection parameters to meet the power consumption requirements. When dealing with large data exchanges like OTA, shortening the connection intervals can improve throughput.
// If you only need the pairing feature, this function is optional.
OPERATE_RET tkl_ble_gap_conn_param_update(USHORT_T conn_handle, TKL_BLE_GAP_CONN_PARAMS_T CONST *p_conn_params);

//(Optional) The scan functions. If you Tuya production testing solution or Bluetooth LE beacon solution, you need to implement the scan function, corresponding to the event TKL_BLE_GAP_EVT_ADV_REPORT.
// If you only need the pairing feature, this function is optional.
OPERATE_RET tkl_ble_gap_scan_start(TKL_BLE_GAP_SCAN_PARAMS_T CONST *p_scan_params);
OPERATE_RET tkl_ble_gap_scan_stop(VOID);

Implementation

Implement the Bluetooth LE peripheral API from the previous section for Linux, FreeRTOS, or no-OS.

• To implement on the MCU and FreeRTOS, refer to the Nordic Bluetooth LE in the open SDK.
• For Linux, refer to BlueZ’s btgatt-server or adopt dbus-bluetoothd to implement a peripheral.

If you have any issues with importing a platform, contact the chip vendor or post your questions on our forum.

Implement a simple peripheral

Implement a simple peripheral based on the TuyaOS Bluetooth LE API. See tuyaos_tkl_ble_peripheral_test.c.

Verify peripheral

How-to

This section uses Nordic’s nRF Connect for Mobile for verification.

It is recommended to use this app on Android, as the iOS app is limited by security rules and cannot show all necessary information.

(Required) Verify advertising and scan response packets

Verify if the advertising and scan response packets received by nRF Connect for Mobile match those that were sent, especially the packet length. Check if a scan response packet is sent. You can tap RAW to show the raw data and details.

(Required) Verify service registration

(Required) Verify data exchange

Next step

After the peripheral channel is verified, incorporate tkl_bluetooth.c into the IPC development framework, and then set the connection mode to Bluetooth to complete the Bluetooth pairing development.

    TUYA_IPC_LINK_TYPE_E link_type = TUYA_IPC_LINK_BT;
    ipc_sdk_run_var.net_info.link_type = link_type;