#### How the upgrade begins
After the device firmware is uploaded to the cloud, the device will not immediately receive the upgrade message. Currently TUYA supports the following methods:
* APP reminder upgrade: When users open the device panel for the first time, they will receive an upgrade reminder pop-up box, they can choose to upgrade or not to upgrade.
* APP silent upgrade: That is, the device is silently upgraded. After the device is restarted, it will request the cloud to check whether there is a silent upgrade task, and if so, directly upgrade; if the user opens the device panel, a progress box will be displayed at this time. The device is inoperable at this time.
* APP forced upgrade: When the user opens the device panel for the first time, he will receive an upgrade reminder pop-up box. Only the confirmation is optional, and the responsible device cannot be operated.
* APP detection upgrade: APP users actively click on the panel of the corresponding device, then click on the upper right corner to enter the device information interface, detect the device firmware version, and actively update.
#### Data interaction diagram
* Explanation：The upgrade progress reported in the following figure is reported by tuya\_SDK, and can also be configured to be reported by the application layer through tuya\_iot\_upgrade\_gw\_notify.
#### Relevant interface and callback description
**FW\_UG\_S**
```
typedef struct {
DEV_TYPE_T tp;
UPGRADE_TYPE_T type;
CHAR_T fw_url[FW_URL_LEN+1];
CHAR_T sw_ver[SW_VER_LEN+1];
UINT_T file_size;
CHAR_T fw_hmac[FW_HMAC_LEN+1];
} FW_UG_S;
```
**FeaturesExplanation(Summary)**
Upgraded firmware information.
**Member Explanation**
| Member name | Explanation |
| ----------- | ----------------------------------------------------------------------------------------- |
| tp | Firmware type |
| type | UPGRADE\_TYPE\_NORMAL : Ordinary upgrade
UPGRADE\_TYPE\_SILENT : Forced upgrade
|
| fw\_url | URL of firmware download |
| sw\_ver | Firmware version number |
| file\_size | Firmware size |
| fw\_hmac | Firmware HMAC check code |
**gw\_ug\_cb**
```
VOID gw_ug_cb(IN CONST FW_UG_S *fw)
```
**FeaturesExplanation( Summary )**
The user registers the callback function gw\_ug\_cb in \[TY\_IoT\_CBS\_S] (# TY\_IoT\_CBS\_S). The gateway has a new firmware notification callback.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fw | Firmware information.Reference [FW\_UG\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#FW_UG_S) |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| VOID | |
**tuya\_iot\_upgrade\_gw**
```
OPERATE_RET tuya_iot_upgrade_gw_notify(IN CONST FW_UG_S *fw,
IN CONST GET_FILE_DATA_CB get_file_cb,
IN CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb,
IN CONST PVOID_T pri_data,
BOOL_T notify,
UINT_T download_buf_size);
```
**FeaturesExplanation( Summary )**
Networking module firmware upgrade processing interface.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| ------------------- | ----------------------------------------------------------------- |
| fw | Firmware information |
| get\_file\_cb | Callback function for download content storage |
| upgrd\_nofity\_cb | Callback function to notify the upgrade status of the application |
| pri\_data | Parameters passed to get\_file\_cb and upgrd\_nofity\_cb |
| notify | Choose whether to report upgrade progress by SDK |
| download\_buf\_size | Download the maximum cache, in bytes |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Success |
| Error Code | Fail return Error Code |
#### The application layer reports the progress of the upgrade
When the progress of the application layer control upgrade is reported, please use [tuya\_iot\_upgrade\_gw\_notify](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#tuya_iot_upgrade_gw_notify) to close the tuya\_SDK and report the upgrade progress.
**tuya\_iot\_dev\_upgd\_progress\_rept**
```
OPERATE_RET tuya_iot_dev_upgd_progress_rept(IN CONST UINT_T percent,
IN CONST CHAR_T *devid,
IN CONST DEV_TYPE_T tp);
```
**FeaturesExplanation( Summary )**
Report the upgrade progress.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| percent | Upgrade progress value. 0 \~ 99 |
| devid | When it is a child device, the ID of the child device is passed in;
When it is a gateway, NULL
|
| tp | Equipment type |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Success |
| Error Code | Fail return Error Code |
**tuya\_iot\_dev\_upgd\_result\_report**
```
OPERATE_RET tuya_iot_dev_upgd_result_report(IN CONST CHAR_T *dev_id,
IN CONST DEV_TYPE_T type,
IN CONST INT_T result);
```
**FeaturesExplanation( Summary )**
Report device upgrade results.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| devid | When it is a child device, the ID of the child device is passed in;
When it is a gateway, NULL
|
| tp | Equipment type |
| result | Upgrade result |
TI\_UPGRD\_STAT\_S definition:
```
#define TUS_RD 1 //Upgrade is ready
#define TUS_UPGRDING 2 // upgrading
#define TUS_UPGRD_FINI 3 // update completed
#define TUS_UPGRD_EXEC 4 // Leave after upgrade
```
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Success |
| Error Code | Fail return Error Code |
**tuya\_iot\_refuse\_upgrade**
```
OPERATE_RET tuya_iot_refuse_upgrade(IN CONST FW_UG_S *fw, IN CONST CHAR_T *dev_id);
```
**FeaturesExplanation( Summary )**
Stop the upgrade during the upgrade process.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fw | Firmware information.Reference [FW\_UG\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#FW_UG_S) |
| devid | When it is a child device, the ID of the child device is passed in;
When it is a gateway, NULL
|
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Success |
| Error Code | Fail return Error Code |
**tuya\_iot\_gw\_version\_update**
```
OPERATE_RET tuya_iot_gw_version_update(IN GW_PERMIT_DEV_TP_T type, IN CONST CHAR_T *ver);
```
**FeaturesExplanation( Summary )**
After the upgrade is complete, update the gateway or gateway adapter firmware version number.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ----------------------- |
| type | Gateway type |
| ver | Firmware version number |
GW\_PERMIT\_DEV\_TP\_T definition:
```
#define GP_DEV_ZB DEV_ZB_SNGL // zigbee
#define GP_DEV_OTHER DEV_OTHER_SNGL // other
#define GP_DEV_BLE DEV_BLE_SNGL // Bluetooth
#define GP_DEV_INFRARED DEV_INFRARED_SNGL //Infrared
#define GP_DEV_MCU DEV_NM_NOT_ATH_SNGL // MCU
```
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ----------------------- |
| OPRT\_OK | Success |
| Error Code | Fail return 的Error Code |
### Device function points (dp point)
Tuya provides an MQTT-based network application protocol to implement device control and status reporting. MQTT Yes is a lightweight publish-subscribe mode message transmission protocol, specifically designed for IoT applications in low-bandwidth and unstable network environments.
tuya\_SDK encapsulates the implementation of the MQTT protocol layer and is presented in the form of function points (hereinafter referred to as dp points). It supports numeric, Boolean, enumerated, String, fault, and RAW data, as simple as defining C variables.
Developers need to create corresponding function points on Tuya Developer Platform according to the device functions, and create a new dp point Description:
**Features**
1.Currently supports the creation of a maximum of 35 dp per product. Please use RAW data to implement complex functions; 2.Obj type: bool type, value type, string type, enum type, fault type (bitmap), tuya\_SDK will filter the continuously reported values, the same will not be allowed Upload.
#### DP Structure
**TY\_RECV\_OBJ\_DP\_S**
```
typedef struct {
DP_CMD_TYPE_E cmd_tp;
DP_TRANS_TYPE_T dtt_tp;
CHAR_T *cid;
CHAR_T *mb_id;
UINT_T dps_cnt;
TY_OBJ_DP_S dps[0];
} TY_RECV_OBJ_DP_S;
```
**FeaturesExplanation(Summary)**
OBJ function point information command callback.
**Member Explanation**
| Member name | Explanation |
| ----------- | --------------------------------------------------------------------------------------------- |
| cmd\_tp | Command type, how the command is generated |
| dtt\_tp | Type of transmission |
| cid | CID is NULL, expressed as a gateway device
is not empty, expressed as a sub-device.
|
| mb\_id | When dtt\_tp is multicast, mb\_id is the group ID |
| dps\_cnt | Number of function point structure arrays |
| dps\_cnt | Function point structure array |
**TY\_RECV\_RAW\_DP\_S**
```
typedef struct {
DP_CMD_TYPE_E cmd_tp;
DP_TRANS_TYPE_T dtt_tp;
CHAR_T *cid;
BYTE_T dpid;
CHAR_T *mb_id;
UINT_T len;
BYTE_T data[0];
} TY_RECV_RAW_DP_S;
```
**FeaturesExplanation(Summary)**
DP point data structure of RAW type.
**Member Explanation**
| Parameter Name | Explanation |
| -------------- | --------------------------------------------------------------------------------------------- |
| cmd\_tp | Command type, how the command is generated |
| dtt\_tp | Type of transmission |
| cid | CID is NULL, expressed as a gateway device
is not empty, expressed as a sub-device.
|
| dpid | DP point ID 。 |
| mb\_id | When dtt\_tp is multicast, mb\_id is the group ID |
| len | Transparent transmission data length |
| data | Transparent data cache |
**TY\_DP\_QUERY\_S**
```
typedef struct {
CHAR_T *cid;
UINT_T cnt;
BYTE_T dpid[0];
} TY_DP_QUERY_S;
```
**FeaturesExplanation(Summary)**
Query DP point information.
**Member Explanation**
| Parameter Name | Explanation |
| -------------- | --------------------------------------------------------------------------------------------- |
| cid | CID is NULL, expressed as a gateway device
is not empty, expressed as a sub-device.
|
| cnt | The number of dp points. If it is equal to 0, it means all DP points. |
| dpid | The ID of the DP point to be queried. |
#### Device command to issue callback
**dev\_obj\_dp\_cb**
```
VOID dev_obj_dp_cb(IN CONST TY_RECV_OBJ_DP_S *dp);
```
**FeaturesExplanation( Summary )**
The user registers the callback function dev\_obj\_dp\_cb in \[TY\_IoT\_CBS\_S] (# TY\_IoT\_CBS\_S) . OBJ function point callback.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dp | The SDK calls back the user's OBJ type function point data. Reference [TY\_RECV\_OBJ\_DP\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_RECV_OBJ_DP_S) |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| | |
**dev\_raw\_dp\_cb**
```
VOID dev_raw_dp_cb(IN CONST TY_RECV_RAW_DP_S *dp);
```
**FeaturesExplanation( Summary )**
The user registers the callback function dev\_raw\_dp\_cb in [TY\_IoT\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_CBS_S) .Callback for transparent function points.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dp | The SDK calls back the user's RAW function point data.Reference [TY\_RECV\_RAW\_DP\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_RECV_RAW_DP_S) |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| | |
**dev\_dp\_query\_cb**
```
VOID dev_dp_query_cb(IN CONST TY_DP_QUERY_S *dp_qry);
```
**FeaturesExplanation( Summary )**
The user registers the callback function dev\_dp\_query\_cb in [TY\_IoT\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_CBS_S) .Device specific data query entry callback.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| dp\_qry | Reference [TY\_DP\_QUERY\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_DP_QUERY_S) |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| | |
#### Device status report
**dev\_report\_dp\_json\_async**
```
OPERATE_RET dev_report_dp_json_async(IN CONST CHAR_T *dev_id,
IN CONST TY_OBJ_DP_S *dp_data,
IN CONST UINT_T cnt);
```
**FeaturesExplanation( Summary )**
Asynchronous way, report function point information.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ----------------------------------- |
| dev\_id | Device ID |
| dp\_data | Function point data structure |
| cnt | Number of dp\_data structure arrays |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
**dev\_report\_dp\_raw\_sync**
```
OPERATE_RET dev_report_dp_raw_sync (IN CONST CHAR_T *dev_id,
IN CONST BYTE_T dpid,
IN CONST BYTE_T *data,
IN CONST UINT_T len,
IN CONST UINT_T timeout);
```
**FeaturesExplanation( Summary )**
The device transparently transmits data to the reporting interface synchronously. The caller guarantees the reliability of data reporting.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------- |
| dev\_id | Device ID |
| dpid | Function point ID |
| data | Transparent data |
| len | Transparent data length |
| timeout | Function blocking timeout |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
**dev\_report\_dp\_stat\_sync**
```
#define dev_report_dp_stat_sync(dev_id, dp_data, cnt, timeout) \
dev_report_dp_stat_sync_extend(dev_id, dp_data, cnt, timeout, TRUE)
OPERATE_RET dev_report_dp_stat_sync_extend(IN CONST CHAR_T *dev_id,
IN CONST TY_OBJ_DP_S *dp_data,
IN CONST UINT_T cnt,
IN CONST UINT_T timeout,
IN CONST BOOL_T enable_auto_retrans);
```
**FeaturesExplanation( Summary )**
Device structured data synchronous reporting interface. The caller guarantees the reliability of data reporting. It is usually used for reporting statistical data.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dev\_id | Device ID |
| dp\_data | Function point information structure array.[TY\_OBJ\_DP\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_OBJ_DP_S) |
| cnt | The length of the DP status array |
| timeout | Function blocking timeout |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
### Sub-device management
#### Sub-device distribution network
**Data interaction diagram**
* This picture is to add a sub-device from the APP side of the mobile phone.
* The gateway can also call [tuya\_iot\_gw\_bind\_dev](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#tuya_iot_gw_bind_dev) to bind directly.
* The communication protocol between the sub-device and the gateway is implemented by the user.
**Interface & callback description**
**TY\_IoT\_GW\_CBS\_S**
```
typedef struct {
GW_PERMIT_ADD_DEV_CB gw_add_dev_cb;
GW_DEV_DEL_CB gw_del_cb;
GW_DEV_GRP_INFM_CB gw_dev_grp_cb;
GW_DEV_SCENE_INFM_CB gw_dev_scene_cb;
GW_BIND_DEV_INFORM_CB gw_ifm_cb;
} TY_IoT_GW_CBS_S;
```
**FeaturesExplanation(Summary)**
The gateway enables the addition of sub-devices. This callback function is used to notify the scene, group and sub-device binding of deleting the sub-device.
**Member Explanation**
| Member name | Explanation |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| gw\_add\_dev\_cb | reference [gw\_add\_dev\_cb](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#gw_add_dev_cb) |
| gw\_del\_cb | reference [gw\_del\_cb](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#gw_del_cb) |
| gw\_dev\_grp\_cb | reference [gw\_dev\_grp\_cb](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#gw_dev_grp_cb) |
| gw\_dev\_scene\_cb | reference [gw\_dev\_scene\_cb](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#gw_dev_scene_cb) |
| gw\_ifm\_cb | reference [gw\_ifm\_cb](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#gw_ifm_cb) |
**gw\_add\_dev\_cb**
```
BOOL_T gw_add_dev_cb(IN CONST GW_PERMIT_DEV_TP_T tp,
IN CONST BOOL_T permit,
IN CONST UINT_T timeout);
```
**FeaturesExplanation( Summary )**
The user registers the callback function gw\_add\_dev\_cb in [TY\_IoT\_GW\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_GW_CBS_S) . When adding a sub-device, the function of enabling device access to the network is implemented in this callback.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------------- |
| tp | Sub-device type |
| permit | Whether to add sub-devices.**TRUE true is allowed；FALSE is forbidden.** |
| timeout | The timeout period of the distribution network. \*\* Unit in seconds \*\* |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | -------------------- |
| TRUE | Successful operation |
| FALSE | failure |
**gw\_del\_cb**
```
VOID gw_del_cb(IN CONST CHAR_T *dev_id);
```
**FeaturesExplanation( Summary )**
The user registers the callback function gw\_del\_cb in [TY\_IoT\_GW\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_GW_CBS_S) .When the sub-device is deleted, the user is notified via this callback.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------ |
| dev\_id | The ID of the sub-device that was deleted. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| | |
**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);
```
**FeaturesExplanation( Summary )**
Sub-device interface bound to the gateway. When TUYA APP enables the gateway to add sub-devices, call this interface to bind the discovered sub-devices.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | --------------------------------------------------------------------------------------- |
| tp | Sub-device type. |
| uddd | The device type is defined by the user, which distinguishes different types of devices. |
| id | Sub-device id. The length cannot exceed 25 bytes. |
| pk | Sub-device product key。The length cannot exceed 16 bytes. |
| ver | Sub-device firmware version。The length cannot exceed 10 bytes. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
**gw\_bind\_ifm\_cb**
```
VOID gw_bind_ifm_cb(IN CONST CHAR_T *dev_id, IN CONST OPERATE_RET op_ret);
```
**FeaturesExplanation( Summary )**
The user registers the callback function gw\_bind\_ifm\_cb in [TY\_IoT\_GW\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_GW_CBS_S). When the sub-device is bound, the user is notified of the binding result through this callback.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | --------------------------------------------------------------------------------------------- |
| dev\_id | The ID of the bound child device. |
| op\_ret | Binding results.
OPRT\_OK means to bind Success.
Other means the binding failed.
|
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| | |
#### Unbind the subdevice
**Interface & callback description**
**tuya\_iot\_gw\_unbind\_dev**
```
OPERATE_RET tuya_iot_gw_unbind_dev(IN CONST CHAR_T *id);
```
**FeaturesExplanation(Summary)**
Unbind the subdevice
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------- |
| dev\_id | The ID of the sub-device that needs to be unbound from the gateway. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| | |
#### Sub-device firmware upgrade (OTA)
**Data interaction diagram**
* The communication between the sub-device and the gateway device layer is implemented by the customer. Here only briefly.
* The upgrade progress report can be controlled by the user. Only when the gateway sends the firmware package to the sub-device, it will update the report progress.
* TUYA Smart APP has a 60s timeout mechanism for firmware upgrade:It will update the message and retime. When receiving the progress of a package of the device each time; the application layer can report the upgrade progress by controlling the upgrade progress to prolong the APP timeout.
**Interface & callback description**
**dev\_ug\_inform\_cb**
```
VOID dev_ug_cb(IN CONST CHAR_T *dev_id, IN CONST FW_UG_S *fw)
```
**FeaturesExplanation( Summary )**
The user registers the callback function dev\_ug\_cb in [TY\_IoT\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_CBS_S) . Notification of OTA firmware upgrade of the child device. It indicates that there is an updateable sub-device firmware.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dev\_id | Sub-device ID with new firmware that can be updated. |
| fw | [FW\_UG\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#FW_UG_S) |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| | |
**tuya\_iot\_upgrade\_dev**
```
OPERATE_RET tuya_iot_upgrade_dev_notify(IN CONST CHAR_T *devid,
IN CONST FW_UG_S *fw,
IN CONST GET_FILE_DATA_CB get_file_cb,
IN CONST UPGRADE_NOTIFY_CB upgrd_nofity_cb,
IN CONST PVOID_T pri_data)
```
**FeaturesExplanation( Summary )**
Device firmware upgrade interface. It contains the upgrade of the main control device on the gateway and the sub-devices of each terminal.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| devid | Device id string |
| fw | Upgraded firmware information.Reference [FW\_UG\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#FW_UG_S) |
| get\_file\_cb | Implemented in this callback, download content storage |
| upgrd\_nofity\_cb | Notification function that is called back when the download is complete. In this callback, the upgrade function of the device needs to be called. |
| pri\_data | Parameters passed to get\_file\_cb and upgrd\_nofity\_cb. For example, download the upgrade file handle. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Success |
| Error Code | Fail return Error Code |
**tuya\_iot\_gw\_subdevice\_update**
```
OPERATE_RET tuya_iot_gw_subdevice_update (IN CONST CHAR_T *id, IN CONST CHAR_T *ver);
```
**FeaturesExplanation( Summary )**
Update the firmware version number of the sub-device.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| dev\_id | Sub-device ID. \*\* Cannot exceed 25 bytes. \*\* |
| ver | Subdevice firmware version number. \*\* Refer to the TUYA definition of version number format in the article. \*\* |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
#### Sub-device online management
* Enable tuya\_SDK's heartbeat detection mechanismZ.
As shown below, this is a diagram of the interface call when the SDK's heartbeat keep-alive mechanism is turned on.
**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);
```
**FeaturesExplanation( Summary )**
The gateway updates the online / offline status of the child device.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------- |
| dev\_id | Sub-device ID. |
| online | online status.
TRUE is online,
FALSE is offline.
|
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
**tuya\_iot\_sys\_mag\_hb\_init**
```
OPERATE_RET tuya_iot_sys_mag_hb_init(IN CONST DEV_HEARTBEAT_SEND_CB hb_send_cb);
```
**FeaturesExplanation( Summary )**
Enable heartbeat management capabilities of sub-devices.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| hb\_send\_cb | The gateway checks all sub-devices every 3 seconds. If the sub-device is within the heartbeat packet timeout and the sub-device does not send a heartbeat to the gateway, the gateway will set the sub-device offline. Notify users at least three times via hb\_send\_cb. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
**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);
```
**FeaturesExplanation( Summary )**
Set the heartbeat timeout time of the sub-device. If the gateway does not receive the heartbeat of the sub-device within the set time, the gateway will set the sub-device offline.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| dev\_id | Sub-device ID. |
| hb\_timeout\_time | Heartbeat timeout time, in seconds. If set to 0xffffffff, the sub-device will be skipped for heartbeat check and will always be online. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
**tuya\_iot\_fresh\_dev\_hb**
```
OPERATE_RET tuya_iot_fresh_dev_hb(IN CONST CHAR_T *dev_id)
```
**FeaturesExplanation( Summary )**
When the gateway receives the heartbeat information of the sub-device, it calls this function to refresh the heartbeat state of the sub-device.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------- |
| dev\_id | sub-device ID |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
#### Get sub-device information
**tuya\_iot\_dev\_traversal**
```
DEV_DESC_IF_S *tuya_iot_dev_traversal(INOUT VOID **iterator);
```
**FeaturesExplanation( Summary )**
Sub-device traversal. Through this interface, all sub-devices under the gateway can be traversed.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------------------- |
| iterator | Temporarily save the linked list. The user only needs to define a null pointer. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------------------------------------------------------------------------------------- |
| DEV\_DESC\_IF\_S | Pointer to the structure of device information. The user can read device information from it. |
| NULL | The device information has been read. |
#### Sub-device group control
**gw\_dev\_grp\_cb**
```
OPERATE_RET gw_dev_grp_cb(IN CONST GRP_ACTION_E action, IN CONST CHAR_T *dev_id, IN CONST CHAR_T *grp_id);
```
**FeaturesExplanation( Summary )**
The user registers the callback function gw\_dev\_grp\_cb in [TY\_IoT\_GW\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_GW_CBS_S) . In this callback, the group operation processing command is realized.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | --------------------------------------------------------------------- |
| action | The type of operation for the group. Add and delete group operations. |
| dev\_id | The ID of the sub-device that joined the group grp\_id. |
| grp\_id | Group ID . |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
#### Sub-device scene features
**gw\_dev\_scene\_cb**
```
OPERATE_RET gw_dev_scene_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);
```
**FeaturesExplanation( Summary )**
The user registers the callback function gw\_dev\_scene\_cb in [TY\_IoT\_GW\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_GW_CBS_S) .The scene processing command feature is implemented in this callback.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------------------------------------ |
| action | The operation type of the scene. Add and delete, and perform scene operations. |
| dev\_id | Sub-device ID. |
| grp\_id | Group ID . |
| sce\_id | Scene ID. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | ---------------------- |
| OPRT\_OK | Successful operation |
| Error Code | Fail return Error Code |
#### Sub-device reset callback
**dev\_reset\_cb**
```
VOID dev_reset_cb(IN CONST CHAR_T *dev_id, IN DEV_RESET_TYPE_E type)
```
**FeaturesExplanation( Summary )**
The user registers the callback function dev\_reset\_cb in [TY\_IoT\_CBS\_S](https://docs.tuya.com/en/iot/smart-product-solution/product-solutiongateway/gateway-link-sdk-access-solution/tuya-gateway-link-sdk-development-manual?id=K9ducoah42rl2#TY_IoT_CBS_S) .In this callback, reset processing of the sub-device needs to be handled.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ------------------------------------------------ |
| dev\_id | The ID of the sub-device that needs to be reset. |
| type | Reset type. |
```
typedef enum {
DEV_REMOTE_RESET_FACTORY, //Remove device
DEV_RESET_DATA_FACTORY, //Clear local data and remove the device.
} DEV_RESET_TYPE_E;
```
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| VOID | |
### Log management
**tuya\_iot\_app\_cbs\_init**
```
VOID tuya_iot_app_cbs_init(IN CONST TY_IoT_APP_CBS_S *app_cbs);
```
**FeaturesExplanation( Summary )**
Initialize the application callback. Currently only supports users to register local log to get callback.
**parameter Explanation( Parameters )**
| Parameter Name | Explanation |
| -------------- | ---------------------------- |
| app\_cbs | Get local log callback name. |
**Return Value(Return Values)**
| **Return Value** | **Explanation** |
| ---------------- | --------------- |
| VOID | |
**Notes (Notes)**
Log management is essential for equipment maintenance and troubleshooting.It is recommended to leave about 5M \~ 10M space on the device side to save the device operation log.When the device fails, you can pull the device log on the developer platform through the gateway device ID information.\*\* For the convenience of equipment problem analysis, this function must be implemented. \*\*
**Fake code**
```
STATIC VOID app_log_path_cb(OUT CHAR_T *path, IN CONST INT_T len);
int main(void)
{
tuya_iot_init(CFG_STORAGE_PATH);
......
TY_IoT_APP_CBS_S iot_app_cbs = {
app_log_path_cb,
};
tuya_iot_app_cbs_init(&iot_app_cbs);
......
while(1){
sleep(10);
}
}
/*****************************************************************
* @Function: app_log_path_cb
* @Description: Local log get callback
* @Param[out]: path, File path string of the local log archive
* @Param[in]: len，The maximum length of the path string of the local log compressed package file
* @Return: void
*****************************************************************/
STATIC VOID app_log_path_cb(OUT CHAR_T *path, IN CONST INT_T len)
{
PR_DEBUG("app_log_path_cb，log_file_path maxlen:%d",len);
//This is for reference only, the saving and compression of log files need to be implemented by users themselves
CHAR_T log_file_path[] = {"/tmp/tuya_log.tar.gz"};
if( (strlen(log_file_path) < len) && (path != NULL) ){
snprintf(path, len, "%s", log_file_path);
}
}
```
### Error Code Description
* It is convenient for developers to locate problems during debugging and will be continuously updated.
| Error Code | Reason | Solution |
| ---------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| -944 | When reporting function points, the corresponding DPID is not under the product | Login to the Tuya IoT platform to confirm |
| -916 | The device is disconnected from Tuya Cloud MQTT server long connection | Check whether the device is connected to the external network |
| -926 | When the device reports MQTT data, it waits for the server puback to time out | Check the device network condition or reduce the reporting frequency |
| -945 | DP point attribute values do not match | Check whether the reported DP point attribute value is consistent with the platform definition |
Error code definition view: tuya\_cloud\_error\_code.h
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.ifreeq.com/developer/smart-product-solution/gateway/link-sdk-access.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.