Bluetooth Sub-Device Connectivity

Last Updated on : 2023-10-16 09:43:26download

Bluetooth sub-device connectivity aims to lower the barrier to developing a Bluetooth gateway. Tuya’s hardware and software-integrated solution provides Bluetooth module and software implementation, allowing you to build a Bluetooth gateway with no code and connect to Bluetooth Low Energy (LE) and Bluetooth mesh sub-devices in the Tuya ecosystem.

This topic describes how to use the Bluetooth features with TuyaOS Gateway Development Framework.


Tuya’s hardware and software-integrated solution makes complicated gateway development simple. Even if you do not have any Bluetooth knowledge, you can build a Bluetooth gateway cost-effectively.

Connect your hardware to Tuya’s Bluetooth module through the serial port and enable Bluetooth features in the software. Then, your product becomes Bluetooth-capable and can connect to Tuya-enabled sub-devices.

Development guide

This section describes how to enable Bluetooth features with TuyaOS Gateway Development Framework by making API calls.

Two interfaces are used to enable Bluetooth features: Bluetooth initialization and Bluetooth startup. They have the same parameters in JSON, but differ in configurations.

Configuration description

Fields in the JSON data:

Field Description
dev_name Specifies the serial port number.
enable_hb Specifies whether to enable heartbeat management.
  • 1: Enable
  • 0: Disable
With heartbeat management enabled, the gateway regularly reads the attribute of the sub-device. It refreshes the heartbeat on receiving data reported from the sub-device.
scan_timeout The scan timeout in Bluetooth LE mode, in seconds.
mode Sets the Bluetooth operation mode. TAL_BLE_ROLE_E defines the operation modes. You can set the coexistence of multiple modes using the bitwise AND operation.
Note: Use this mode field for v3.7.0 and later. For versions earlier than v3.7.0, use subdev_type instead.
subdev_type Sets the supported types of sub-devices. You can set multiple types using the bitwise AND operation.
Definitions of the sub-device types:


// ...
#include "tuya_bt_api.h"
#include "tal_bluetooth_def.h"

int main(int argc, char **argv)
	ty_cJSON *app_cfg = ty_cJSON_CreateObject();
    if (app_cfg == NULL) {
        return OPRT_CJSON_GET_ERR;
    ty_cJSON_AddStringToObject(app_cfg, "storage_path", "./");
    ty_cJSON_AddStringToObject(app_cfg, "cache_path", "/tmp/");

    // Set storage path.

    ty_cJSON *bt_cfg = ty_cJSON_CreateObject();
    if (bt_cfg == NULL) {
        return OPRT_CJSON_GET_ERR;
    ty_cJSON_AddStringToObject(bt_cfg, "dev_name", "/dev/ttyS2");
    ty_cJSON_AddNumberToObject(bt_cfg, "enable_hb", 1);
    ty_cJSON_AddNumberToObject(bt_cfg, "scan_timeout", 60);
    // Set the Bluetooth operation mode for legacy versions.
    ty_cJSON_AddNumberToObject(bt_cfg, "mode", (TAL_BLE_ROLE_CENTRAL | TAL_MESH_ROLE_ADV_PROVISIONER));
    // Set the supported types of sub-devices for new versions.
    // ty_cJSON_AddNumberToObject(bt_cfg, "subdev_type", (0x0001 | 0x0002)); // Bluetooth LE & Bluetooth Mesh

    // Initialize Bluetooth service.

	// Start Bluetooth service.

    // ...

    return 0;