Bluetooth + X

This topic describes the Bluetooth + X capability.

Overview

A typical Tuya-enabled Bluetooth device communicates with the cloud solely through the Bluetooth channel.

With the Bluetooth + X capability enabled, where X is an extension module like Wi-Fi, Cat.1, or NB-IoT, the device continues to use Bluetooth for pairing and control when not connected to an X module. When connected to an X module, the device can communicate with the cloud either over Bluetooth or through the X channel once it activates the X module via Bluetooth.

Data structure

tuya_ble_ext_module_active_data_t

typedef struct{
    uint8_t *p_data;    /**< ext module active data. */
    uint16_t data_len;  /**< active data length. */
} tuya_ble_ext_module_active_data_t;

• p_data: The pointer to the information used to activate the extension module.
• data_len: The length of the information used to activate the extension module.

API description

Macro configuration

Report extension module information

Callback for querying extension module information

Format for extension module information:

• inc_em_info: Specify whether extension module information is included. 0x01: Included. 0x00: Not included.

• emt_type: The type of the extension module.

  • 0x01: NB-IoT module
  • 0x02: Wi-Fi module
  • 0x03: Cat.1 module
  • 0x04: Zigbee module

• N_TLD: The number of TLD data units.

• TLD: The data unit.

  • Type (1 byte): The type.
  • Length (2 bytes): The length of the data.
  • Data: The payload. See the following table.

• TLD 0x01 for extension module information

  Type	Length	Data
  0x01	…	When emt_type is NB-IoT module, the device information in JSON format is { “pv”:“3.0”, “bv”:“3.0”, “sv”:“1.0.0”, “i”:“866242050005256”, “opt”:1, “h”:28800 } pv: The protocol version, in string. bv: The baseline version, in string. sv: The firmware version, in string. i: The IMEI of the device, in string. h: The heartbeat time, in integer. Unit: seconds. opt: The APN, in integer. opt is used to map the carrier. 0: China Telecom. 0: China Unicom. 1: China Mobile. 2: Directly connected to the Tuya Cloud. When emt_type is Wi-Fi module, there is no need to include device information because the module will report it upon activation. When emt_type is Cat.1 module, there is no need to include device information because the module will report it upon activation.

• TLD 0x02 for the presence status of the extension module

  Type	Length	Data
  0x02	0x01	0x00: The extension module is ejected. 0x01: The extension module is installed.

• TLD 0x03 for channel priority

  Type	Length	Data
  0x03	…	A priority is represented by one byte, with the order indicating priority from high to low. For example, if the priority is defined as Bluetooth Low Energy > MQTT, the data will be 0x03, 0x01. 0x00: LAN 0x01: MQTT 0x02: HTTP 0x03: Bluetooth Low Energy 0x04: Bluetooth mesh 0x05: Tuya proprietary mesh 0x06: Beacon

• TLD 0x04 for OTA priority (not used)

• TLD 0x05 for the binding status of the extension module

  Type	Length	Data
  0x05	0x01	0x00: The extension module is not bound. 0x01: The extension module is bound.

• TLD 0x06 for OTA channel and version (not used)

• TLD 0x07 for the flag of passive/proactive data reporting

  Type	Length	Data
  0x07	0x01	0x00: The device reports data passively in response to a status query. 0x01: The device proactively reports data. The mobile app does not acknowledge the receipt of proactive reporting.

When the extension module is Wi-Fi or Cat.1, its information will be reported upon activation. The Bluetooth device synchronizes with the mobile app regarding the presence of the extension module, binding status, and channel priority.

See tal_feature_ext_module and tal_ble_x_demo.c for examples of the extension module information returned.

Callback for receiving activation information

The data format for the activation information:

• emt_type: The type of the extension module.

  • 0x01: NB-IoT module
  • 0x02: Wi-Fi module
  • 0x03: Cat.1 module
  • 0x04: Zigbee module

• TLD: The data unit.

  • Type (1 byte): The type.
  • Length (2 bytes): The length of the data.
  • Data: The payload. See the following table.

• When emt_type is NB-IoT module, the TLD definition is:

  Type	Length	Data
  0x01	…	A JSON string, including devID and secKey: { “s”:“nYqC0z6yuqJzrggALzatsB42K0PCz***”, “d”:“6c7294fd20d1a5b39cn***” }

• When emt_type is Wi-Fi or Cat.1 module, the TLD definition is:

  Type	Length	Data
  0x01	…	A JSON string, including devID, secKey, and localKey, which matches the one stored in the cloud and is passed in raw format through the mobile app and Bluetooth: { “devId”:“6cba0dda87e9ae35f8c***”, “secKey”:“fd0ed4e6beff2***”, “region”:“AY”, “env”:“pr_0”, “localKey”:“a427f948b8451***” }

• When emt_type is Zigbee module, the TLD definition is:

  Type	Length	Data
  0x01	…	PAN: 2 bytes. exPAN: 8 bytes. Channel: 1 byte. net key: 16 bytes.

How to use

Sequence diagram

Callback event processing

STATIC VOID_T tuya_ble_protocol_callback(tuya_ble_cb_evt_param_t* event)
{
    switch(event->evt)
    {
        //...
#if defined(TUYA_BLE_FEATURE_EXT_MODULE_ENABLE) && (TUYA_BLE_FEATURE_EXT_MODULE_ENABLE != 0)
        case TUYA_BLE_CB_EVT_QUERY_EXT_MODULE_DEV_INFO: {
            //...
        } break;
        case TUYA_BLE_CB_EVT_EXT_MODULE_ACTIVE_INFO_RECEIVED: {
            //...
        } break;
#endif
        //...
    }
}

Code files

tal_feature_ext_module
├── include
│   ├── tal_ble_x_demo.h
│   └── tal_feature_ext_module.h
└── src
    ├── tal_ble_x_demo.c
    └── tal_feature_ext_module.c

Things to note

• To support the full Bluetooth + X feature, you need to implement the required capabilities on both the Bluetooth device and the X module. Before using the full Bluetooth + X feature, verify with the product manager or developer if the X module is compatible.
• The Bluetooth + X capability allows for activating the X module via Bluetooth. This covers neither the activation process between the Bluetooth and X modules nor data exchange for DP or OTA through the X channel. To implement these features, you need to add the code for Bluetooth and X module interaction in your project.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.