OTA 协议(网关)
OTA（Over-The-Air）更新介绍
OTA（Over-The-Air）更新是一种通过无线网络将软件更新直接推送到设备的技术。设备通过 OTA 上报当前固件信息，服务端返回激活状态、WebSocket 连接配置、服务器时间和固件更新信息。
设备正式访问地址为：
https://xrobo.qiniuapi.com/v1/ota/
通过 OTA 请求获取到激活码和 WebSocket 地址后，再进行 WebSocket 通信。
OTA 上报
请求
text
POST https://xrobo.qiniuapi.com/v1/ota/请求头
Activation-Version：激活版本（必需，设备芯片 efuse 区是否存储了有效的序列号，有则为2，无则为1）Device-Id：设备的唯一标识符（必需，使用 MAC 地址或由硬件 ID 生成的伪 MAC 地址）Client-Id：客户端的唯一标识符，由软件自动生成的 UUID v4（必需，擦除 FLASH 或重装后会变化）Serial-Number：设备的序列号（可选；如果设备通过序列号预注册，则应传入序列号）User-Agent：客户端的名称和版本号（必需，例如esp-box-3/1.5.6）Accept-Language：客户端当前语言（可选，例如zh-CN）
请求体
请求体为 JSON，包含以下字段：
application：设备当前固件版本信息（必需）version：当前固件版本号elf_sha256：设备上报的固件 Hash 信息
mac_address：MAC 地址（必需）。该值必须与请求头Device-Id完全一致uuid：Client-Id（可选），与 HTTP Header 中的Client-Id一致chip_model_name：设备芯片型号，例如esp32s3（可选）flash_size：设备闪存大小（可选）partition_table：设备分区表，用于设备侧检查下载固件所需空间（可选）board：开发板类型及其运行环境（必需）type：开发板类型ssid：设备接入的 Wi-Fi 名称rssi：设备接入的 Wi-Fi 信号强度
请求示例
http
POST https://xrobo.qiniuapi.com/v1/ota/
Host: xrobo.qiniuapi.com
Activation-Version: 1
Accept-Language: zh-CN
Content-Type: application/json
Device-Id: D4:06:06:B6:A9:FA
Client-Id: 550e8400-e29b-41d4-a716-446655440000
User-Agent: xiaoling-web-test/1.0.0json
{
"version": 0,
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"application": {
"name": "xiaoling-web-test",
"version": "1.0.0",
"compile_time": "2025-04-16 10:00:00",
"idf_version": "4.4.3",
"elf_sha256": "1234567890abcdef1234567890abcdef1234567890abcdef"
},
"ota": { "label": "xiaoling-web-test" },
"board": {
"type": "xiaoling-web-test",
"ssid": "xxxxxx",
"rssi": 0,
"channel": 0,
"ip": "192.168.1.1",
"mac": "D4:06:06:B6:A9:FA"
},
"flash_size": 0,
"minimum_free_heap_size": 0,
"mac_address": "D4:06:06:B6:A9:FA",
"chip_model_name": "",
"chip_info": { "model": 0, "cores": 0, "revision": 0, "features": 0 },
"partition_table": [
{ "label": "", "type": 0, "subtype": 0, "address": 0, "size": 0 }
]
}成功响应
HTTP 状态码为 200 OK 时，响应体为 JSON。字段是否出现取决于设备绑定状态和固件配置：
activation：激活信息。仅在设备未绑定且未通过预注册自动绑定时返回code：设备激活码。当前为 6 位数字；同一设备在缓存有效期内重复上报会复用激活码message：设备展示用的激活提示，当前由智控台地址、换行符和激活码组成challenge：设备的Device-Id
mqtt：MQTT 协议服务器配置（协议预留字段）websocket：WebSocket 协议服务器配置url：设备建立 WebSocket 连接的地址token：WebSocket 鉴权凭证。仅在设备已经绑定后返回；未绑定设备不返回该字段
server_time：服务器时间信息timestamp：当前时间的 Unix 毫秒时间戳timezone：服务器时区名称timezone_offset：服务器时区相对 UTC 的偏移量，单位为分钟；正数表示快于 UTC，负数表示慢于 UTC，例如480表示 UTC+8
firmware：固件信息，不是每次成功响应都必然存在- 未绑定设备会收到当前版本和兼容用的无效升级地址
- 已绑定设备根据自动更新开关、开发板类型和可用固件决定是否返回及返回内容
version：固件版本号url：固件下载地址（如果有更新）
timezone 和 timezone_offset 表示服务器时区及其相对 UTC 的偏移。
未绑定设备响应示例
json
{
"server_time": {
"timestamp": 1752119934489,
"timezone": "Asia/Shanghai",
"timezone_offset": 480
},
"activation": {
"code": "608303",
"message": "http://60.205.58.18:8002\n608303",
"challenge": "D4:06:06:B6:A9:FA"
},
"firmware": {
"version": "1.0.0",
"url": "https://xrobo.qiniuapi.com/v1/ota/INVALID_FIRMWARE_FOR_TEST"
},
"websocket": {
"url": "ws://xrobo-io.qiniuapi.com/v1/ws/"
}
}已绑定设备响应示例
json
{
"server_time": {
"timestamp": 1752119934489,
"timezone": "Asia/Shanghai",
"timezone_offset": 480
},
"websocket": {
"url": "ws://xrobo-io.qiniuapi.com/v1/ws/",
"token": "设备鉴权令牌"
}
}错误响应
OTA 上报接口当前按以下规则返回错误：
- 缺少
Device-Id，或请求体不是合法 JSON：HTTP400 Bad Request - 请求体业务校验失败（例如
mac_address与Device-Id不一致、缺少application）：HTTP200 OK，响应体包含error - 服务端内部错误：HTTP
500 Internal Server Error，只返回通用错误信息
业务校验失败示例：
json
{
"error": "Invalid OTA request"
}服务端内部错误示例：
http
HTTP/1.1 500 Internal Server Error
Content-Type: application/jsonjson
{
"error": "Internal server error"
}快速激活状态检查
设备完成激活码绑定后，可以调用快速激活状态检查接口确认绑定状态。
请求
text
POST https://xrobo.qiniuapi.com/v1/ota/activate请求头：
Device-Id：设备的唯一标识符（必需）
请求体：无请求体。
响应
设备已绑定
http
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
success设备收到该响应后，应重新调用 POST https://xrobo.qiniuapi.com/v1/ota/。重新上报后，服务端会按已绑定设备返回 WebSocket url 和 token。
设备未绑定
设备不存在、尚未绑定，或者 Device-Id 的值为空时，返回：
http
HTTP/1.1 202 Accepted响应体为空。
请求或服务异常
请求未携带 Device-Id，或者服务端查询失败时，返回：
http
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 500,
"msg": "Server internal exception",
"data": null
}