Firmware Update

This topic describes the APIs used to implement the functionality of the firmware update.

Structs

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;

Functional specification

The firmware update information.

Member description

Member	Description
tp	The firmware type.
type	The update methods: UPGRADE_TYPE_NORMAL: Normal update. UPGRADE_TYPE_SILENT: Auto update.
fw_url	The update download URL.
sw_ver	The firmware version number.
file_size	The size of the firmware update.
fw_hmac	The firmware HMAC code.

API reference

tuya_iot_upgrade_gw

#define tuya_iot_upgrade_gw(fw, get_file_cb, upgrd_nofity_cb, pri_data) \
    tuya_iot_upgrade_gw_notify(fw, get_file_cb, upgrd_nofity_cb, pri_data, TRUE, 0)
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)

Functional description

Downloads the firmware update of the gateway.

Parameter description

Parameter name	Description
fw	The firmware information. For more information, see FW_UG_S.
get_file_cb	The callback processes the downloaded file. For more information, see GET_FILE_DATA_CB.
upgrd_nofity_cb	The callback notifies the gateway of the download result. For more information, see UPGRADE_NOTIFY_CB.
pri_data	The private data passed to the get_file_cb and upgrd_nofity_cb callbacks. You can set it to NULL.

Return value

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

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)

Functional description

Downloads the firmware update.

Parameter description

Parameter name	Description
devid	The device ID.
fw	The firmware information. For more information, see FW_UG_S.
get_file_cb	The callback processes the downloaded file. For more information, see GET_FILE_DATA_CB.
upgrd_nofity_cb	The callback notifies the gateway of the download result. For more information, see UPGRADE_NOTIFY_CB.
pri_data	The private data passed to the get_file_cb and upgrd_nofity_cb callbacks. You can set it to NULL.

Return value

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

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)

Functional description

Reports the update progress.

Parameter description

Parameter name	Description
percent	The progress of the update. Valid values are from 0 to 99.
devid	If devid is NULL, it indicates the gateway and the gateway’s module. If devid is not NULL, it indicates the sub-device.
tp	The firmware type. Its value is associated with the update channel.

Return value

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

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)

Functional description

Reports the update result.

Parameter description

Parameter name	Description
devid	If devid is NULL, it indicates the gateway and the gateway’s module. If devid is not NULL, it indicates the sub-device.
tp	The firmware type. Its value is associated with the update channel.
result	The update result: TUS_RD: Ready to install the update. TUS_UPGRDING: The update is being installed. TUS_UPGRD_FINI: The update is installed successfully. TUS_UPGRD_EXEC: Failed to install the update.

Return value

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

tuya_iot_refuse_upgrade

OPERATE_RET tuya_iot_refuse_upgrade(IN CONST FW_UG_S *fw, IN CONST CHAR_T *dev_id);

Functional description

Rejects an update request.

Parameter description

Parameter name	Description
fw	The firmware information. For more information, see FW_UG_S.
devid	If devid is NULL, it indicates the gateway and the gateway’s module. If devid is not NULL, it indicates the sub-device.

Return value

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

tuya_iot_gw_subdevice_update

OPERATE_RET tuya_iot_gw_subdevice_update (IN CONST CHAR_T *id,
                                          IN CONST CHAR_T *ver);

Functional description

Reports the firmware version number of the sub-device.

Parameter description

Parameter name	Description
dev_id	The device ID of the sub-device. Its length cannot exceed 25 bytes.
ver	The firmware version number of the sub-device, in the format x.x.x where x must be a number.

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

GET_FILE_DATA_CB

typedef OPERATE_RET (*GET_FILE_DATA_CB)(IN CONST FW_UG_S *fw,
                                        IN CONST UINT_T total_len,
                                        IN CONST UINT_T offset,
                                        IN CONST BYTE_T *data,
                                        IN CONST UINT_T len,
                                        OUT UINT_T *remain_len,
                                        IN PVOID_T pri_data)

Functional description

The callback processes the downloaded file.

Parameter description

Parameter name	Description
fw	The firmware information. For more information, see FW_UG_S.
total_len	The total size of the firmware update.
offset	The current download offset.
data	Data
len	Data length.
remain_len	The length of unprocessed data. Typically, the update file can be completely downloaded in one operation and the remain_len is 0.
pri_data	The private data passed as parameters.

Return value

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

UPGRADE_NOTIFY_CB

typedef VOID (*UPGRADE_NOTIFY_CB)(IN CONST FW_UG_S *fw,
                                  IN CONST INT_T download_result,
                                  IN PVOID_T pri_data)

Functional description

The callback notifies the gateway of the download result.

Parameter description

Parameter name	Description
fw	The firmware information. For more information, see FW_UG_S.
download_result	The download result: 0: Success. Other values: Failure.
pri_data	The private data passed as parameters.

Return value

Return value	Description
VOID	/