OTA 接口文档

用户8438

2025年4月30日修改

概述

该 API 用于处理设备的 OTA（Over-The-Air）升级请求。设备通过发送设备信息和当前固件版本，服务器将返回最新的固件版本和下载链接（如果有更新）。​

新版本返回信息中，还增加了 MQTT 和 Websocket 服务器信息，设备激活码。​

请求方法

•
POST /api/ota/​

请求头

•
Device-Id: 设备的唯一标识符（必需，使用MAC地址或由硬件ID生成的伪MAC地址）​

•
Client-Id: 客户端的唯一标识符，由软件自动生成的UUID v4（必需，擦除FLASH或重装后会变化）​

•
User-Agent: 客户端的名字和版本号（必需，例如 esp-box-3/1.5.6）​

•
Accept-Language: 客户端的当前语言（可选，例如 zh-CN）​

请求体

请求体应为JSON格式，包含以下字段：

•
application: 包含设备当前固件版本信息的对象（必需）​
◦
version: 当前固件版本号​
◦
elf_sha256: 用于校验固件文件完整性Hash​

•
mac_address: MAC地址（可选，与 HTTP header 里的 device-id 一致）​

•
uuid: ClientId（可选，与 HTTP header 里的 client-id 一致）​

•
chip_model_name: 设备的芯片型号，例如 esp32s3（可选）​

•
flash_size: 设备的闪存大小（可选）​

•
psram_size: 设备的PSRAM大小（可选）​

•
partition_table: 设备分区表，用于检查是否有足够的空间，用于下载固件（可选）​

•
board: 开发板类型与版本，以及所运行的环境（必需）​
◦
type: 开发板类型​
◦
name: 开发板SKU（与user-agent中的前面部分保持一致）​
◦
ssid: 设备接入的 Wi-Fi 名字​
◦
rssi: 设备接入的 Wi-Fi 信号强度​

响应

成功响应

响应体为JSON格式，包含以下字段：

•
activation: 设备需要激活​
◦
code: 激活码​
◦
message: 屏幕显示消息​

•
mqtt: MQTT协议服务器配置信息​

•
websocket: Websocket协议服务器配置信息​

•
server_time: 服务器时间信息（用于同步设备时间）​
◦
timestamp: 当前时间戳​
◦
timezone: 服务器时区​
◦
timezone_offset: 服务器时区偏移量​

OTA 接口文档​