tkl_ota | OTA Firmware Update

The tkl_ota API provides the kernel-layer (TKL) hooks for an over-the-air (OTA) firmware update. The update runs in stages: query the device OTA capability, signal the start, process each data packet, and signal the end. A separate call retrieves the previous firmware's information for resumable transfers. Every function returns OPRT_OK on success or an error code defined in tuya_error_code.h.

The tkl_ota.c implementation is generated by the porting tool. You add platform-specific code in the user-defined areas so it survives regeneration.

tkl_ota_get_ability

OPERATE_RET tkl_ota_get_ability(uint32_t *image_size, TUYA_OTA_TYPE_E *type);

Gets the device's OTA capability: the maximum firmware image size it can receive and the OTA type it supports.

Parameter	Direction	Description
image_size	out	Maximum firmware image size the device accepts.
type	out	Supported OTA type. See TUYA_OTA_TYPE_E.

Returns OPRT_OK on success. Other values indicate an error; see tuya_error_code.h.

tkl_ota_start_notify

OPERATE_RET tkl_ota_start_notify(uint32_t image_size, TUYA_OTA_TYPE_E type, TUYA_OTA_PATH_E path);

Notifies the platform that an OTA update is starting. The implementation initializes the variables and state needed for the transfer.

Parameter	Direction	Description
image_size	in	Size of the firmware image to be written.
type	in	OTA type. See TUYA_OTA_TYPE_E.
path	in	Transport channel the data arrives on. See TUYA_OTA_PATH_E.

Returns OPRT_OK on success. Other values indicate an error; see tuya_error_code.h.

tkl_ota_data_process

OPERATE_RET tkl_ota_data_process(TUYA_OTA_DATA_T *pack, uint32_t *remain_len);

Processes one received OTA data packet, writing its payload to Flash.

Parameter	Direction	Description
pack	in	Pointer to the OTA data packet. See TUYA_OTA_DATA_T.
remain_len	out	Number of bytes in the packet that were not yet processed.

Returns OPRT_OK on success. Other values indicate an error; see tuya_error_code.h.

tkl_ota_end_notify

OPERATE_RET tkl_ota_end_notify(BOOL_T reset);

Notifies the platform that the OTA transfer has ended. The implementation verifies the received image and performs any post-processing, optionally resetting the device.

Parameter	Direction	Description
reset	in	Whether to reset the device after the update completes.

Returns OPRT_OK on success. If verification fails or another error occurs, an error code is returned; see tuya_error_code.h.

tkl_ota_get_old_firmware_info

OPERATE_RET tkl_ota_get_old_firmware_info(TUYA_OTA_FIRMWARE_INFO_T **info);

Gets information about the current firmware. This is used to resume an interrupted transfer at a break-point.

note

This API is used only for BLE sub-devices.

Parameter	Direction	Description
info	out	Receives a pointer to the firmware information structure. See TUYA_OTA_FIRMWARE_INFO_T.

Returns OPRT_OK on success. Other values indicate an error; see tuya_error_code.h.

Types

TUYA_OTA_TYPE_E

OTA package type.

typedef enum {
    TUYA_OTA_FULL = 1, ///< AB area switch, full package upgrade
    TUYA_OTA_DIFF = 2, ///< fixed area, difference package upgrade
} TUYA_OTA_TYPE_E;

TUYA_OTA_PATH_E

Transport channel the OTA data arrives on.

typedef enum {
    TUYA_OTA_PATH_AIR     = 0,   ///< OTA from Wired/Wi-Fi/Cellular/NBIoT
    TUYA_OTA_PATH_UART    = 1,   ///< OTA from uart for MF
    TUYA_OTA_PATH_BLE     = 2,   ///< OTA from BLE protocol for subdev
    TUYA_OTA_PATH_ZIGBEE  = 3,   ///< OTA from Zigbee protocol for subdev
    TUYA_OTA_PATH_SEC_A   = 4,   ///< OTA from multi-section A
    TUYA_OTA_PATH_SEC_B   = 5,   ///< OTA from multi-section B
    TUYA_OTA_PATH_INVALID = 255  ///< OTA from multi-section invalid
} TUYA_OTA_PATH_E;

TUYA_OTA_DATA_T

One OTA packet. The implementation writes the payload to Flash at start_addr + offset.

typedef struct {
    uint32_t total_len;  ///< ota image total len
    uint32_t start_addr; ///< ota flash start addr
    uint32_t offset;     ///< ota image offset
    uint8_t *data;       ///< ota data
    uint32_t len;        ///< ota data len
    void    *pri_data;   ///< private pointer
} TUYA_OTA_DATA_T;

TUYA_OTA_FIRMWARE_INFO_T

Describes a firmware image.

typedef struct {
    uint32_t len;
    uint32_t crc32;
    uint8_t  md5[TUYA_OTA_FILE_MD5_LEN];
} TUYA_OTA_FIRMWARE_INFO_T;

TUYA_OTA_FILE_MD5_LEN is 16.