分享
OTA 接口文档
输入“/”快速插入内容
OTA 接口文档
用户8438
用户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
: 服务器时区偏移量