This is the documentation for the latest (main) development branch. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

OTA

Introduction

OTA (Over The Air) is a method for remotely updating the firmware or software of a device through wireless communication technology.

Function List

Full Update: Download and install the complete firmware onto the device.

Compressed Update: Use compression technology to reduce the size of the update package, saving storage space, increasing download success rate, and reducing update time and data usage.

OTA Function Overview

OTA update mechanism allows a device to self-update while the firmware is running normally by receiving data (e.g., by Wi-Fi or Bluetooth). When using OTA, you need to configure the device’s partition table , and choose either the OTA partition table or a custom OTA partition table.

After the OTA function is started, the downloaded update package will be stored in the app_ota partition, and upon device reboot, the bootloader will handle decompression decompression and firmware update.

OTA Update Configuration

Firmware Partition Configuration

The W800 by default has only one OTA partition; please refer to the partition table for settings. During the OTA update process, the new firmware will be stored in the app_ota partition , and after the firmware download is complete, it will be decompressed and updated. The default OTA partition table configuration is as follows:
# name,          offset,    size,      flag
ft,              0x0,       0x2000,    0x0
bootloader,      0x2000,    0xC000,    0x0
partition_table, 0xE000,    0x1000,    0x0
app,             0xF000,    0x122A00,  0x0
app_ota,         0x131A00,  0xAE600,   0x0
user,            0x1E0000,  0x2000,    0x0
nvs,             0x1F0000,  0x8000,    0x0

Bootloader Configuration

The W800 includes a bootloader that runs when the device starts up, responsible for decompressing the OTA update file and performing the firmware update. During firmware burning, the bootloader will be automatically written into the W800.

Firmware Package Configuration

Use developer tools to compile the latest firmware files (.img files), then upload the compiled firmware files to an OTA server or a network-accessible storage location (such as an FTP server, HTTP server, etc.). The generated OTA img files come in two types, as shown in the table below:

File Name

Type

xxxxx.img

Full Update Package

xxxxx_ota.img

Compressed Update Package

During the download process, the device will perform data verification (such as signature and checksum) to ensure data integrity and security. After the download is complete, the device will verify the integrity and authenticity of the firmware package, and if confirmed correct, it will start the installation.

OTA header Format Overview

Structure Member

Description

uint32_t magic_no;

Magic number to identify OTA image

wm_img_attr_t img_attr

Bitfield of image attributes

uint32_t img_addr

Address to execute the image

uint32_t img_len

Binary image length in bytes

uint32_t img_header_addr

Address of the image header

uint32_t upgrade_img_addr

Address of the upgrade image file

uint32_t org_checksum

Original checksum of the image

uint32_t upd_no

Update version tracking number

unsigned char ver[16]

Version string, 16 bytes long

uint32_t _reserved0

Reserved for future use

uint32_t _reserved1

Reserved for future use

struct wm_ota_header_t *next

Pointer to the next OTA header

Network Communication Configuration

During the OTA update process, the W800 needs to connect to WiFi and communicate with the OTA server. It downloads the firmware files from the server using HTTP, FTP, or other protocols, and performs data verification (such as signature and checksum) to ensure data integrity and security. If the device is not connected to the network, the OTA request will fail directly.

Main Functions

Full Update

1. Starting Conditions

Configure the OTA partition table: The device’s partition table needs to be configured to support the OTA format.

Device connected to the network: The device must be connected to the internet by Wi-Fi or Ethernet.

OTA server accessible: The device can access the configured OTA server (supporting HTTP, FTP, etc.).

Firmware version verification: Properly verify xxxx.img as the full update file to determine if an update is needed.

2. Relevant Timing APIs

Open the project configuration menu menuconfig to configure the partition table supporting OTA.

Call wm_wifi_init() to initialize WiFi.

Call wm_wifi_set_config() to configure WiFi parameters.

Call wm_wifi_connect() to connect to WiFi.

Call wm_ota_http_update() to perform the OTA update.

3. Result

OTA full update successful.

Compressed Update

1. Starting Conditions

Configure the OTA partition table: The device’s partition table needs to be configured to support the OTA format.

Device connected to the network: The device must be connected to the internet via Wi-Fi or Ethernet.

OTA server accessible: The device can access the configured OTA server (supporting HTTP, FTP, etc.).

Firmware version verification: Properly verify xxxx_ota.img as the compressed update file to determine if an update is needed.

2. Relevant Timing APIs

Open the project configuration menu menuconfig to configure the partition table supporting OTA.

Call wm_wifi_init() to initialize WiFi.

Call wm_wifi_set_config() to configure WiFi parameters.

Call wm_wifi_connect() to connect to WiFi.

Call wm_ota_http_update() to perform the OTA update.

3. Result

OTA compressed update successful.

Precautions

Ensure that the firmware file size does not exceed the available storage space of the OTA partition .

During the OTA update process, maintain a stable network connection to avoid update failures.

During the OTA update process, do not disconnect the power supply of the W800 to avoid update failures.

Application Example

For a basic OTA example, please refer to examples/ota

API Reference

For OTA-related APIs, please refer to:

OTA_OPS API Reference and OTA_HTTP API Reference