Application Development

This topic describes the commonly-used functions that can help you develop applications easily with Tuya Bluetooth SDK.

Sync data

The device application reports data to the mobile app or the Tuya Bluetooth gateway over Bluetooth. Call tuya_ble_dp_data_send to report data point (DP) data and sync device status.

Sample code

static uint32_t test_sn = 0;
uint8_t dpvalue[128]={0x0A, 0x01,0x00,0x01,0x00};
tuya_ble_dp_data_send(test_sn++, 0, 0, 0, dpvalue, 5);
// The device proactively reports data `false` of DP10. DP 10 is a Boolean type, with a data length of one byte.

Sync data with timestamp

To report cache data stored when the device is offline, call tuya_ble_dp_data_with_time_send to report data with a timestamp. This function is similar to the data reporting function.

Sample code

static uint32_t test_sn = 0;
uint8_t dpvalue[128]={0x0A, 0x01,0x00,0x01,0x00};
uint8_t time[128]="1628648755000"   //2021-08-11 10:25:55
tuya_ble_dp_data_with_time_send (test_sn++, 0, 0, &time[0], dpvalue, 5);
// The device proactively reports data `false` of DP10 with a timestamp. DP 10 is a Boolean type, with a data length of one byte.

Receive data

After receiving DP data from the mobile app, Tuya Bluetooth SDK will send TUYA_BLE_CB_EVT_DP_DATA_RECEIVED event to the device application.

Generally, the device executes the specified command according to the received DP data and then reports the current status to the mobile app for display.

Sample code

typedef struct {
  uint32_t sn;        // `sn` indicates the serial number of data sending events from the mobile app, which is incremented by one for each event.
  uint8_t *p_data;    // `p_data` format. For more information, see the API documentation.
  uint16_t data_len;  // The length of data.
} tuya_ble_dp_data_received_data_t;

You can complete the required service logic in the callback TUYA_BLE_CB_EVT_DP_DATA_RECEIVED.

Sample code

static void tuya_ble_sdk_callback(tuya_ble_cb_evt_param_t* event)
{
	switch(event->evt)
	{
		case TUYA_BLE_CB_EVT_DP_DATA_RECEIVED: {
		 // Execute the specified command, such as turning the switch on or off.
		tuya_ble_dp_data_send(event->dp_received_data.sn, 0, 0, 0, event->dp_received_data.p_data, event->dp_received_data.data_len);   // Report current status.
		TUYA_APP_LOG_INFO("TUYA_BLE_CB_EVT_DP_DATA_RECEIVED");
		} break;
	}
}

Notify the change of Bluetooth connection status

Tuya Bluetooth SDK sends TUYA_BLE_CB_EVT_CONNECTE_STATUS event to the device application when Bluetooth connection status changes. The following sample code shows all the types of Bluetooth connection status.

typedef enum {
  UNBONDING_UNCONN = 0, // The device is unbound and not connected.
  UNBONDING_CONN,    // The device is unbound, connected, and authorized.
  BONDING_UNCONN,    // The device is bound and not connected.
  BONDING_CONN,     // The device is bound, connected, and authorized.
  BONDING_UNAUTH_CONN,  // The device is bound, connected, and unauthorized.
  UNBONDING_UNAUTH_CONN, // The device is unbound, connected, and unauthorized.
  UNKNOW_STATUS           // Unknown
} tuya_ble_connect_status_t;

You can implement specified service logic on the change of Bluetooth connection status in the callback TUYA_BLE_CB_EVT_CONNECTE_STATUS.

Sample code

static tuya_ble_connect_status_t current_connect_status = UNKNOW_STATUS;
static tuya_ble_connect_status_t last_connect_status = UNKNOW_STATUS;
static void tuya_cb_handler(tuya_ble_cb_evt_param_t* event)
{
  int16_t result = 0;
  tuya_ble_status_t err_code;
  switch (event->evt)
 {
  case TUYA_BLE_CB_EVT_CONNECTE_STATUS:
    TUYA_APP_LOG_INFO("received tuya ble conncet status update event,currentconnect status = %d",event->connect_status);
    if((event->connect_status == BONDING_CONN)&&(last_connect_status!=BONDING_CONN))
	{
		// To trigger the status change-dependent feature, the application should compare the difference between the current and previous status. For example, the change of LED flickering.
	}
	last_connect_status = event->connect_status;
    break;
  default:
    break;
 }
}

Query DPs

After Bluetooth is connected for the first time or the device is bound, the mobile app will send a query for the initial DP values for status sync. Tuya Bluetooth SDK will send TUYA_BLE_CB_EVT_DP_QUERY event to the device application. You can complete the required service logic in the callback TUYA_BLE_CB_EVT_DP_QUERY.

static void tuya_ble_sdk_callback(tuya_ble_cb_evt_param_t* event)
{
	switch(event->evt)
	{
		case TUYA_BLE_CB_EVT_DP_QUERY: {
		 // Report the initial DP values.
		TUYA_APP_LOG_INFO("TUYA_BLE_CB_EVT_DP_QUERY");
		} break;
	}
}

Unbind devices on the mobile app

When users initiate a command on the mobile app to unbind an online device, the Bluetooth connection status of this device becomes unbound on a successful unbinding. Tuya Bluetooth SDK will send TUYA_BLE_CB_EVT_UNBOUND event to the device application.

You can complete the required service logic in the callback TUYA_BLE_CB_EVT_UNBOUND.

static void tuya_ble_sdk_callback(tuya_ble_cb_evt_param_t* event)
{
	switch(event->evt)
	{
		case TUYA_BLE_CB_EVT_UNBOUND: {
		// Implement the required processing function.
		TUYA_APP_LOG_INFO("TUYA_BLE_CB_EVT_UNBOUND");
		} break;
	}
}

Reset devices on the mobile app

When users initiate a command on the mobile app to remove an online device and clear data, the historical data associated with the virtual ID of this device will be cleared from the server.

Tuya Bluetooth SDK will clear its virtual ID on receiving this command. The Bluetooth connection status of this device becomes unbound and disconnected.

Tuya Bluetooth SDK will send TUYA_BLE_CB_EVT_DEVICE_RESET event to the device application on receiving this command. You can complete the required processing logic in the callback.

static void tuya_ble_sdk_callback(tuya_ble_cb_evt_param_t* event)
{
	switch(event->evt)
	{
		case TUYA_BLE_CB_EVT_DEVICE_RESET: {
		 // Complete the required processing logic, such as restore defaults.
		TUYA_APP_LOG_INFO("TUYA_BLE_CB_EVT_DEVICE_RESET");
		} break;
	}
}

Unbind offline devices

Offline removing indicates users initiate a command on the mobile app to unbind an offline device and clear data. If successful, this operation will be synced to the cloud. However, since the offline device cannot be notified of this unbinding event, it is still in the binding status.

When this device is advertising, if a mobile app connects to it, the app will send an offline removing command and the device will execute the specified operation on receiving the event. Note that the process of device handling offline unbinding will not be reflected on the mobile app.

TUYA_BLE_CB_EVT_ANOMALY_UNBOUND event is used. You can complete the required service logic in the callback TUYA_BLE_CB_EVT_ANOMALY_UNBOUND.

static void tuya_ble_sdk_callback(tuya_ble_cb_evt_param_t* event)
{
	switch(event->evt)
	{
		case TUYA_BLE_CB_EVT_ANOMALY_UNBOUND: {
		// Implement the required processing function.
		TUYA_APP_LOG_INFO("TUYA_BLE_CB_EVT_ANOMALY_UNBOUND");
		} break;
	}
}

Unbind devices

The device application calls tuya_ble_device_unbind() to unbind a device through local control. The unbinding feature corresponds to the remove operation on the mobile app.

We recommend you implement this feature. If a device is bound with an unintended account, you can unbind this device through local control.

When local unbinding is triggered by an action such as pressing a physical button, the device application will call tuya_ble_device_unbind() to notify Tuya Bluetooth SDK to perform the unbinding operation. This function will not clear the virtual ID of the device.

Reset devices

Call tuya_ble_device_factory_reset() to reset a device. The resting operation corresponds to the remove device and clear data feature on the mobile app.

When local unbinding is triggered by an action such as pressing a physical button, the device application will call tuya_ble_device_factory_reset() to notify Tuya Bluetooth SDK to perform the unbinding and data clearing operation. This function will clear the virtual ID of the device.

Query time

The device application calls tuya_ble_time_req() to query the network time on the mobile app and sync time data to the local time on the device.

The mobile app returns a timestamp string to the SDK on receiving this query. Then, the SDK will send TUYA_BLE_CB_EVT_TIME_STAMP to the device application. You can complete the required processing logic in the callback.

Data format

typedef struct{
	uint8_t timestamp_string[14];
	int16_t  time_zone;   // Actual time zone multiplied by 100.
}tuya_ble_timestamp_data_t;

Sample code

static void tuya_ble_sdk_callback(tuya_ble_cb_evt_param_t* event)
{
	switch(event->evt)
	{
		case TUYA_BLE_CB_EVT_TIME_STAMP: {
		// Implement the required processing function.
		TUYA_APP_LOG_INFO("TUYA_BLE_CB_EVT_TIME_STAMP");
		} break;
	}
}

Query Bluetooth connection status

To get the current Bluetooth connection status, the application can call tuya_ble_connect_status_get().

Other functions

For more information, see API.