Skip to content

ota #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sunqirui1987 merged 1 commit into from
Nov 26, 2025
Merged

ota #41

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/xrobot/platform/OTA.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ POST /api/ota/
- Activation-Version: 激活版本（必需，设备芯片 efuse 区是否存储了有效的序列号，有则"2"，无则"1"）
- Device-Id: 设备的唯一标识符（必需，使用 MAC 地址或由硬件 ID 生成的伪 MAC 地址）
- Client-Id: 客户端的唯一标识符，由软件自动生成的 UUID v4（必需，擦除 FLASH 或重装后会变化）
- Serial-Number: 设备的序列号（可选，如果设备通过序列号预注册的，则必须传入序列号）
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

此处的描述 ‘可选，如果设备通过序列号预注册的，则必须传入序列号’ 存在逻辑上的矛盾（既是可选又是必需）。为了让描述更清晰准确，建议修改为：‘设备的序列号。当设备通过序列号预注册时，此字段为必需；否则为可选。’

Copy link

@xgopilot xgopilot bot Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documentation Gap: The new Serial-Number header should be included in the request example (or explicitly noted as omitted). This helps developers understand when and how to use it.

Consider adding context: "可选，如果设备已通过序列号在服务器端进行预注册，则此字段必须传入；否则服务器将返回 400 错误"

- User-Agent: 客户端的名字和版本号（必需，例如 esp-box-3/1.5.6）
- Accept-Language: 客户端的当前语言（可选，例如 zh-CN）

Expand All @@ -36,7 +37,7 @@ POST /api/ota/
- application: 包含设备当前固件版本信息的对象（必需）
- version: 当前固件版本号
- elf_sha256: 用于校验固件文件完整性 Hash
- mac_address: MAC 地址（可选，与 HTTP header 里的 device-id 一致）
- mac_address: MAC 地址（必需，注意：此字段的值必须与 HTTP 请求头中的 Device-Id 字段完全一致）
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

虽然此行正确地将 mac_address 更新为必需字段，但整个“请求体”的文档描述（37-50行）与下方的 JSON 示例（89-118行）之间存在严重的不一致。这会给 API 的使用者带来很大的困惑。

具体问题包括：

  • 字段缺失: 文档中未描述示例中的 version (根级), ota, minimum_free_heap_size, chip_info 等字段。
  • 示例不完整: 示例中缺少了文档中提到的 psram_size 字段。
  • 结构不一致: board 对象在示例中包含了 channel, ip, mac 等未在文档中定义的字段。
  • 内容矛盾: uuid 字段的文档说明其值应与 Client-Id 请求头一致，但在示例中两者并不匹配（web_test_client vs ""）。

为了保证文档的准确性和可用性，强烈建议借此机会全面核对并更新“请求体”部分的文档，使其与实际的 API 行为和示例代码完全保持一致。

Copy link

@xgopilot xgopilot bot Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Security Concern: The documentation should specify validation rules for MAC address matching:

  • Format: IEEE 802 notation (XX:XX:XX:XX:XX:XX)
  • Case sensitivity handling (recommend case-insensitive comparison)
  • Reject broadcast (FF:FF:FF:FF:FF:FF) and null (00:00:00:00:00:00) addresses
  • Error response when Device-Id and mac_address mismatch

This ensures consistent, secure implementation across clients.

- uuid: ClientId（可选，与 HTTP header 里的 client-id 一致）
- chip_model_name: 设备的芯片型号，例如 esp32s3（可选）
- flash_size: 设备的闪存大小（可选）
Expand Down Expand Up @@ -80,7 +81,7 @@ POST https://xrobo.qiniuapi.com/v1/ota/
Host: xrobo.qiniuapi.com
Accept-Language: zh-CN
Content-Type: application/json
Device-Id: D4:06:06:B6:A9:FB
Device-Id: D4:06:06:B6:A9:FA
Client-Id: web_test_client
Copy link

@xgopilot xgopilot bot Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing Headers: The request example is missing required headers documented above:

  • Activation-Version (必需)
  • User-Agent (必需)

This makes the example incomplete and potentially confusing for developers implementing the API.

```

Expand Down