Bluetooth Roaming

This topic describes how roaming works on Bluetooth devices.

Overview

Concepts

The communication between the Bluetooth device and the Tuya-enabled mobile app is typically based on DP data.

However, when multiple sub-devices, under the same account but located in different places, need to report data to the cloud, Bluetooth roaming can be used instead.

This feature caters to situations where data is collected from mobile objects through unidirectional communication. For example, monitor the blood pressure and heart rate of the elderly in nursing homes and hospitals, or collect counts during jump rope competitions at schools.

Features

Bluetooth roaming allows Bluetooth sub-devices to upload data to the cloud through any Bluetooth gateway in the same home. The sub-device and the gateway do not need to be associated with each other. As long as they belong to the same home, roaming can be achieved without any further configuration. Roaming is one-way, only allowing the device to send data to the cloud and not vice-versa.

Roaming-supported Bluetooth sub-devices feature:

• They can only be paired via the app and cannot be paired or connected through the gateway.
• They and gateways are peers. A roaming-supported sub-device can appear in the roaming list of multiple gateways, enabling gateways to report data simultaneously while filtering the data in the cloud.
• They can only report data through advertising, limiting their use to being conditions for scene linkage.
• They must work on Bluetooth 5.0 or later to use roaming.

Bluetooth sub-devices that do not support roaming:

Regular Bluetooth sub-devices do not support Bluetooth roaming. To communicate with a gateway, they need to be connected to the gateway as a sub-device.

Components

Bluetooth roaming is based on the Bluetooth beacon feature, so the component tal_ble_beacon is required.

The data link for roaming-supported sub-devices differs from that of regular Bluetooth sub-devices. Therefore, a separate demo is used to showcase the Bluetooth roaming feature. The demo is named tuyaos_demo_roaming.

Data structure

TAL_BLE_BEACON_CB

The callback is invoked upon completion of beacon data transmission. Beacon data will be sent after each call to tal_ble_beacon_dp_data_send.

typedef void (* TAL_BLE_BEACON_CB)(void *arg);

arg: The default parameter. Its value is currently empty.

roaming_param_t

You can use the structure in the demo as necessary.

typedef struct {
    UINT32_T adv_interval;
    UINT32_T adv_duration;
} roaming_param_t;

• adv_interval: The advertising interval, in milliseconds.
• adv_duration: The advertising duration, in milliseconds.

API description

Configure Bluetooth beacon macro

#define TAL_BLE_BEACON_INCLUDE_DP_DATA         1
#define TAL_BLE_BEACON_ROAMING_FLAG            1
#define TUYA_BLE_BEACON_KEY_ENABLE             1

Parameter description

Parameter	Description
TAL_BLE_BEACON_INCLUDE_DP_DATA	Specifies whether to allow DP data to be included in the advertising packet.
TAL_BLE_BEACON_ROAMING_FLAG	Specifies whether to enable roaming.
TUYA_BLE_BEACON_KEY_ENABLE	Specifies whether to enable obtaining the beacon key.

Initialize Bluetooth beacon

API description

Bluetooth roaming is based on the Bluetooth beacon feature, so initializing the Bluetooth beacon means Bluetooth roaming initialization.

void tal_ble_beacon_init(uint16_t default_adv_interval, TAL_BLE_BEACON_CB cb);

Parameter description

Parameter	Description
default_adv_interval	The default advertising interval. When reporting data through roaming, the advertising interval will be adjusted. This parameter is used to restore the default advertising interval.
cb	Its value can be empty. See TAL_BLE_BEACON_CB for details.

Report Bluetooth beacon data

Bluetooth roaming is based on the Bluetooth beacon feature, so reporting Bluetooth beacon data means reporting roaming data.

API description

uint32_t tal_ble_beacon_dp_data_send(uint32_t sn, uint8_t encrypt_mode, uint16_t adv_interval, uint16_t adv_duration, uint8_t *p_dp_data, uint32_t dp_data_len);

Parameter description

Parameter	Description
sn	4-byte packet sequence number. Once the device is reset and paired, the sn will be reset to 0. Each time roaming data is sent, the sn is incremented by 1. The sn is stored once every 256 times. After the device restarts, it reads the stored sn and adds 256 to it as the new sn.
encrypt_mode	0: No encryption. 1: Login key encrypted (for Bluetooth roaming). 2: Beacon key encrypted (for ordinary Beacon communication)
adv_interval	The Bluetooth advertising interval, in milliseconds.
adv_duration	The Bluetooth advertising duration, in milliseconds.
p_dp_data	Bluetooth beacon data. See DP Data Communication for details.
dp_data_len	The length of Bluetooth beacon data.

How to use

Communication process

Code development

Enable Bluetooth roaming in app_config.h.

#define TAL_BLE_BEACON_INCLUDE_DP_DATA         1
#define TAL_BLE_BEACON_ROAMING_FLAG            1
#define TUYA_BLE_BEACON_KEY_ENABLE             1

Add the following snippet in tuya_sdk_callback.c to implement the basic functionality. You can call tal_ble_beacon_dp_data_send to report roaming data. See the demo tuyaos_demo_roaming.

VOID_T tal_ble_beacon_cb(VOID_T *arg)
{
    switch (g_dp_report_count) {
        …………

        default: {
        } break;
    }
}

OPERATE_RET tuya_init_last(VOID_T)
{
    …………

    app_roaming_init();
    tal_ble_beacon_init(TY_ADV_INTERVAL, tal_ble_beacon_cb);

    return OPRT_OK;
}

Functional testing

Test cases

TEST_CID_ROAMING_DP_REPORT

Prerequisites

• You have installed the Tuya app on your phone.
• Your device has been paired.
• You have a roaming-supported gateway added to the home.

Procedure

After pairing, you can turn off the Bluetooth on your phone. This is to prevent the phone from accidentally connecting to devices and interfering with reporting roaming data. At this time, the device is expected to emit Beacon signals.

Communicate with the Bluetooth gateway using a host that simulates a real device.

1. Roaming data can be reported either unencrypted or encrypted. You can adjust the advertising duration, which determines how long roaming data is continuously transmitted with a 20-ms interval. You can edit the content of the roaming data (in DP format, multiple DPs allowed). For example, change 09 to 08 as shown in the red rectangle below or report other DPs.
   0x67 represents dp_id = 0x67 = 103. The upper 4 bits of 0x24 represent dp_type = 2. The lower 4 bits of 0x24 represent dp_len = 4. 0x00000009 represents dp_value = 9.

   

2. Report roaming data when the device is not connected to a phone or gateway.

   If you have any problems with host usage, see Logic Host User Guide.

Support and help

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