Device Management

This topic describes the APIs used to implement the functionality of device management.

Structs

TY_IOT_DEV_CBS_S

typedef struct {
    GW_PERMIT_ADD_DEV_CB            dev_add;
    GW_DEV_DEL_CB                   dev_del;
    GW_DEV_GRP_INFM_CB              dev_grp;
    GW_DEV_SCENE_INFM_CB            dev_sce;
    GW_BIND_DEV_INFORM_CB           dev_bind_ifm;
    GW_DEV_HB_SEND_CB               dev_hb;
    GW_DEV_UPGRADE_CB               dev_upgrade;
    GW_DEV_RESET_CB                 dev_reset;
    GW_DEV_WAKEUP_CB                dev_wakeup;
    #if defined(ENABLE_SIGMESH) && (ENABLE_SIGMESH==1)
    GW_DEV_SIGMESH_TOPO_UPDAET_CB   bt_topo_update;
    GW_DEV_SIGMESH_DEV_CACHE_DEL_CB bt_cache_del;
    GW_DEV_SIGMESH_CONN_CB          bt_conn;
    GW_BIND_BLE_MESH_DEV_INFORM_CB  bt_bind_ifm;
    #endif
} TY_IOT_DEV_CBS_S;

Functional specification

The sub-device management callbacks.

Member description

Parameter name	Description
dev_add	The callback to invoke when a request for adding a sub-device is processed. For more information, see GW_PERMIT_ADD_DEV_CB.
dev_del	The callback to invoke when a sub-device is removed. For more information, see GW_DEV_DEL_CB.
dev_grp	The callback to invoke when a sub-device group is operated. For more information, see GW_DEV_GRP_INFM_CB.
dev_sce	The callback to invoke when a sub-device scene is operated. For more information, see GW_DEV_SCENE_INFM_CB.
dev_bind_ifm	The callback notifies the gateway of the result of sub-device binding. For more information, see GW_BIND_DEV_INFORM_CB.
dev_hb	The callback notifies the gateway that heartbeat timeout occurs on sub-devices. For more information, see GW_DEV_HB_SEND_CB.
dev_upgrade	The callback notifies the gateway of the sub-device update. For more information, see GW_DEV_UPGRADE_CB.
dev_reset	The callback to invoke when a sub-device is reset. For more information, see GW_DEV_RESET_CB.
dev_wakeup	The callback to invoke when a sub-device wakes up. For more information, see GW_DEV_WAKEUP_CB.
bt_topo_update	The callback to invoke when a Bluetooth sub-device is added to a gateway by drag and drop. For more information, see GW_DEV_SIGMESH_TOPO_UPDAET_CB.
bt_cache_del	The callback to invoke when a Bluetooth sub-device is removed from a gateway by drag and drop. For more information, see GW_DEV_SIGMESH_DEV_CACHE_DEL_CB.
bt_conn	The callback allows the gateway to connect to Bluetooth sub-devices on demand. For more information, see GW_DEV_SIGMESH_CONN_CB.
bt_bind_ifm	The callback notifies the gateway of the result of Bluetooth sub-device binding. For more information, see GW_BIND_BLE_MESH_DEV_INFORM_CB.

API reference

tuya_iot_reg_gw_mgr_cb

OPERATE_RET tuya_iot_reg_gw_mgr_cb(IN GW_PERMIT_DEV_TP_T tp,
                                   IN TY_IOT_DEV_CBS_S *cbs)

Functional description

Registers the callbacks for sub-device management.

Parameter description

Parameter name	Description
tp	The types of the sub-device: If the value is less than 10, this parameter is reserved for internal use. If the value is greater than or equal to 10, this parameter can be user-defined.
cbs	The sub-device management callbacks.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

tuya_iot_gw_bind_dev

OPERATE_RET tuya_iot_gw_bind_dev(IN CONST GW_PERMIT_DEV_TP_T tp,
                                 IN CONST USER_DEV_DTL_DEF_T uddd,
                                 IN CONST CHAR_T *id,
                                 IN CONST CHAR_T *pk,
                                 IN CONST CHAR_T *ver)

Functional description

Binds a sub-device.

Parameter description

Parameter name	Description
tp	The types of the sub-device: If the value is less than 10, this parameter is reserved for internal use. If the value is greater than or equal to 10, this parameter can be user-defined.
uddd	A custom parameter used to store information by bit such as device type.
id	The device ID of the sub-device. Its length cannot exceed 25 bytes.
pk	The product ID (PID) of the sub-device. Its length cannot exceed 16 bytes.
ver	The firmware version number of the sub-device. Its length cannot exceed 10 bytes.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

tuya_iot_gw_unbind_dev

OPERATE_RET tuya_iot_gw_unbind_dev(IN CONST CHAR_T *id)

Functional specification

Unbinds a sub-device.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

tuya_iot_gw_dev_hb_init

OPERATE_RET tuya_iot_gw_dev_hb_init(VOID)

Functional description

Initializes the heartbeat application of the sub-device.

Parameter description

Parameter name	Description
VOID	/

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

tuya_iot_set_dev_hb_timeout

OPERATE_RET tuya_iot_set_dev_hb_timeout(IN CONST CHAR_T *dev_id,
                                        IN CONST TIME_S hb_timeout_time);

Functional description

Specifies the heartbeat timeout period for the sub-device. If the gateway does not receive a heartbeat refresh message from the sub-device within the specified period, it will declare this sub-device is offline.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.
hb_timeout_time	The specified heartbeat timeout, in seconds. If you set this parameter to 0xffffffff, it indicates the sub-device is online all the time.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

tuya_iot_fresh_dev_hb

OPERATE_RET tuya_iot_fresh_dev_hb(IN CONST CHAR_T *dev_id)

Functional description

Refreshes the heartbeat status of the sub-device, used for keepalive purposes.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

tuya_iot_dev_traversal

DEV_DESC_IF_S *tuya_iot_dev_traversal(INOUT VOID **iterator)

Functional description

Traverses all the sub-devices connected to the gateway. This API is called in the loop body. The information about a single sub-device is returned on each loop. The return value of NULL means the traversal is finished.

Parameter description

Parameter name	Description
iterator	A pointer to an iterator.

Return value

Return value	Description
DEV_DESC_IF_S	The sub-device information.
NULL	Traversal is finished.

tuya_iot_dev_online_stat_update

OPERATE_RET tuya_iot_dev_online_stat_update(IN CONST CHAR_T *dev_id,
                                            IN CONST BOOL_T online)

Functional description

Forces updating the connection status of the sub-device.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.
online	TRUE: Online. FALSE: Offline.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

Callback functions

GW_PERMIT_ADD_DEV_CB

typedef BOOL_T (*GW_PERMIT_ADD_DEV_CB)(IN CONST GW_PERMIT_DEV_TP_T tp,
                                       IN CONST BOOL_T permit,
                                       IN CONST UINT_T timeout)

Functional description

The callback to invoke when a request for adding a sub-device is processed.

Parameter description

Parameter name	Description
tp	The type of the sub-device. If you set this parameter to 0xFF, it indicates the device type is not specified.
permit	Specifies whether to allow the gateway to add the sub-device. TRUE: Allow. FALSE: Not allow.
timeout	The specified pairing timeout period, in seconds.

Return value

Return value	Description
TRUE	Operation succeeded.
FALSE	Failure

GW_DEV_DEL_CB

typedef VOID (*GW_DEV_DEL_CB)(IN CONST CHAR_T *dev_id,
                              IN CONST GW_DELDEV_TYPE type)

Functional description

The callback to invoke when a sub-device is removed.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.
type	The types of sub-device removal: GWDEV_DELTYPE_MQTT: Remove a sub-device over MQTT in real time. GWDEV_DELTYPE_SYNC: Remove a sub-device and sync with the device list on the mobile app.

Return value

Return value	Description
VOID	/

GW_BIND_DEV_INFORM_CB

typedef VOID (*GW_BIND_DEV_INFORM_CB)(IN CONST CHAR_T *dev_id,
                                      IN CONST OPERATE_RET op_ret)

Functional description

The callback notifies the gateway of the result of sub-device binding.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.
op_ret	The result of device binding. 0: Success. Other values: Failure.

Return value

Return value	Description
VOID	/

GW_DEV_UPGRADE_CB

typedef VOID (*GW_DEV_UPGRADE_CB)(IN CONST CHAR_T *dev_id,
                                  IN CONST FW_UG_S *fw)

Functional description

The callback notifies the gateway of the sub-device update.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.
fw	The firmware information. For more information, see FW_UG_S.

Return value

Return value	Description
VOID	/

GW_DEV_HB_SEND_CB

typedef VOID (*GW_DEV_HB_SEND_CB)(IN CONST CHAR_T *dev_id)

Functional description

The callback notifies the gateway that heartbeat timeout occurs on sub-devices.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.

Return value

Return value	Description
VOID	/

GW_DEV_GRP_INFM_CB

typedef OPERATE_RET (*GW_DEV_GRP_INFM_CB)(IN CONST GRP_ACTION_E action,
                                          IN CONST CHAR_T *dev_id,
                                          IN CONST CHAR_T *grp_id)

Functional description

The callback to invoke when a sub-device group is operated.

Parameter description

Parameter name	Description
action	The operations on a sub-device group: GRP_ADD: Add a group. GRP_DEL: Delete a group.
dev_id	The device ID of the sub-device.
grp_id	The group ID.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

GW_DEV_SCENE_INFM_CB

typedef OPERATE_RET (*GW_DEV_SCENE_INFM_CB)(IN CONST SCE_ACTION_E action,
                                            IN CONST CHAR_T *dev_id,
                                            IN CONST CHAR_T *grp_id,
                                            IN CONST CHAR_T *sce_id)

Functional description

The callback to invoke when a sub-device scene is operated.

Parameter description

Parameter name	Description
action	The operations on a scene: SCE_ADD: Add a scene. SCE_DEL: Delete a scene. SCE_EXEC: Run a scene.
dev_id	The device ID of the sub-device.
grp_id	The group ID.
sce_id	The scene ID.

Return value

Return value	Description
OPRT_OK	Operation succeeded.
Error code	For more information about the error code, see tuya_error_code.h.

GW_DEV_RESET_CB

typedef VOID (*GW_DEV_RESET_CB)(IN CONST CHAR_T *dev_id,
                                IN CONST DEV_RESET_TYPE_E type)

Functional description

The callback to invoke when a sub-device is reset.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.
type	The types of device reset. DEV_REMOTE_RESET_FACTORY: A device is removed from the mobile app. DEV_RESET_DATA_FACTORY: The data of the sub-device is erased on activation.

Return value

Return value	Description
VOID	/

GW_DEV_WAKEUP_CB

typedef VOID (*GW_DEV_WAKEUP_CB)(IN CONST CHAR_T *dev_id,
                                 IN UINT_T duration)

Functional description

The callback to invoke when a sub-device wakes up.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.
duration	The wake-up time.

Return value

Return value	Description
VOID	/

GW_DEV_SIGMESH_TOPO_UPDAET_CB

typedef VOID (*GW_DEV_SIGMESH_TOPO_UPDAET_CB)(IN CONST CHAR_T *dev_id)

Functional description

The callback to invoke when a Bluetooth sub-device is added to a gateway by drag and drop.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.

Return value

Return value	Description
VOID	/

GW_DEV_SIGMESH_DEV_CACHE_DEL_CB

typedef VOID (*GW_DEV_SIGMESH_DEV_CACHE_DEL_CB)(IN CONST CHAR_T *dev_id)

Functional description

The callback to invoke when a Bluetooth sub-device is removed from a gateway by drag and drop.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.

Return value

Return value	Description
VOID	/

GW_DEV_SIGMESH_CONN_CB

typedef VOID (*GW_DEV_SIGMESH_CONN_CB)(OUT CHAR_T *sigmesh_dev_conn_inf_json)

Functional description

The callback allows the gateway to connect to Bluetooth sub-devices on demand.

Parameter description

Parameter name	Description
sigmesh_dev_conn_inf_json	JSON data.

Data definition in JSON:

Connect:
{
   "code": 100,
   "data": {
		"type":"CONNECT",
		"nodeId":[ node1, node2, ..., nodeN ]
	}
}

Disconnect:
{
   "code": 100,
   "data": {
		"type":"DISCONNECT",
		"nodeId":[ node1, node2, ..., nodeN ]
	}
}

Heartbeat:
{
	"code": 100,
	"data": {
    	"type":"HEARTBEAT"
 	}
}

Return value

Return value	Description
VOID	/

GW_BIND_BLE_MESH_DEV_INFORM_CB

typedef VOID (*GW_BIND_BLE_MESH_DEV_INFORM_CB)(IN CONST CHAR_T *dev_id,
                                               IN CONST CHAR_T *virt_id,
                                               IN CONST OPERATE_RET op_ret)

Functional description

The callback notifies the gateway of the result of Bluetooth sub-device binding.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device.
virt_id	The virtual ID.
op_ret	The result of device binding. 0: Success. Other values: Failure.

Return value

Return value	Description
VOID	/