Skip to content

Commit 3afda10

Browse files
srsngsrsng
committed
调整部分页面，丰富ws协议api部分
1 parent 48ffab3 commit 3afda10

File tree

16 files changed

+226
-189
lines changed

16 files changed

+226
-189
lines changed

‎docs/.vitepress/theme/constrants/route.ts‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -105,9 +105,11 @@ export const items_xrobot_api_protocol = [
105105
text: "WebSocket API参考",
106106
collapsed: true,
107107
link: Chapters.xrobot_api_protocol,
108-
items: [{ text: "服务通信协议", link: "device-protocol" }].map((item) =>
109-
apply_prefix(item, Chapters.xrobot_api_protocol)
110-
),
108+
items: [
109+
{ text: "WebSocket 协议", link: "websocket" },
110+
{ text: "MQTT 协议", link: "MQTT" },
111+
{ text: "OTA协议", link: "OTA" },
112+
].map((item) => apply_prefix(item, Chapters.xrobot_api_protocol)),
111113
},
112114
];
113115

@@ -143,10 +145,9 @@ export const items_xrobot_platform_device = [
143145
text: "设备配置与使用",
144146
link: Chapters.xrobot_platform_others_device,
145147
collapsed: true,
146-
items: [
147-
{ text: "使用指南", link: "device-intro" },
148-
{ text: "绑定", link: "device-bind" },
149-
].map((item) => apply_prefix(item, Chapters.xrobot_platform_others_device)),
148+
items: [{ text: "使用指南", link: "device-intro" }].map((item) =>
149+
apply_prefix(item, Chapters.xrobot_platform_others_device)
150+
),
150151
},
151152
];
152153

@@ -155,7 +156,11 @@ const items_xrobot_platform_console = [
155156
text: "控制台（智控台）",
156157
link: Chapters.xrobot_platform_others_console,
157158
collapsed: true,
158-
items: [{ text: "智能体连接指南", link: "device-connection" }].map((item) =>
159+
items: [
160+
{ text: "基本介绍", link: "intro" },
161+
{ text: "智能体连接指南", link: "device-connection" },
162+
{ text: "设备绑定", link: "device-bind" },
163+
].map((item) =>
159164
apply_prefix(item, Chapters.xrobot_platform_others_console)
160165
),
161166
},

‎docs/xrobot/api/protocol/MQTT.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: MQTT 通信协议
3+
---
4+
5+
## MQTT 通信协议
6+
7+
待补充。

‎docs/xrobot/api/protocol/OTA.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: OTA 协议
3+
---
4+
5+
## OTA 地址
6+
7+
<https://xrobo.qiniuapi.com/v1/ota/>
8+
9+
## OTA 协议描述
10+
11+
请求方法
12+
13+
- POST /api/ota/
14+
请求头
15+
- Device-Id: 设备的唯一标识符（必需，使用 MAC 地址或由硬件 ID 生成的伪 MAC 地址）
16+
- Client-Id: 客户端的唯一标识符，由软件自动生成的 UUID v4（必需，擦除 FLASH 或重装后会变化）
17+
- User-Agent: 客户端的名字和版本号（必需，例如 esp-box-3/1.5.6）
18+
- Accept-Language: 客户端的当前语言（可选，例如 zh-CN）
19+
请求体
20+
请求体应为 JSON 格式，包含以下字段：
21+
- application: 包含设备当前固件版本信息的对象（必需）
22+
- version: 当前固件版本号
23+
- elf_sha256: 用于校验固件文件完整性 Hash
24+
- mac_address: MAC 地址（可选，与 HTTP header 里的 device-id 一致）
25+
- uuid: ClientId（可选，与 HTTP header 里的 client-id 一致）
26+
- chip_model_name: 设备的芯片型号，例如 esp32s3（可选）
27+
- flash_size: 设备的闪存大小（可选）
28+
- psram_size: 设备的 PSRAM 大小（可选）
29+
- partition_table: 设备分区表，用于检查是否有足够的空间，用于下载固件（可选）
30+
- board: 开发板类型与版本，以及所运行的环境（必需）
31+
- type: 开发板类型
32+
- name: 开发板 SKU（与 user-agent 中的前面部分保持一致）
33+
- ssid: 设备接入的 Wi-Fi 名字
34+
- rssi: 设备接入的 Wi-Fi 信号强度
35+
响应
36+
成功响应
37+
响应体为 JSON 格式，包含以下字段：
38+
- activation: 设备需要激活
39+
- code: 激活码
40+
- message: 屏幕显示消息
41+
- mqtt: MQTT 协议服务器配置信息
42+
- websocket: WebSocket 协议服务器配置信息
43+
- server_time: 服务器时间信息（用于同步设备时间）
44+
- timestamp: 当前时间戳
45+
- timezone: 服务器时区
46+
- timezone_offset: 服务器时区偏移量
47+
- firmware: 最新版本固件信息
48+
- version: 固件版本号
49+
- url: 固件下载链接（如果有更新）
50+
错误响应
51+
- 400 Bad Request: 请求缺少必需的字段或字段无效
52+
- error: 错误信息
53+
- 500 Internal Server Error: 服务器内部错误 - error: 错误信息
54+
2.1.2 OTA 协议举例
55+
以 Web 端模拟设备为例，也可以直接体验我们的 Web-demo
56+
<!-- todo Web-demo超链 -->
57+
58+
```Plain Text
59+
POST https://xrobo.qiniuapi.com/v1/ota/
60+
Host: xrobo.qiniuapi.com
61+
Accept-Language: zh-CN
62+
Content-Type: application/json
63+
Device-Id: D4:06:06:B6:A9:FB
64+
Client-Id: web_test_client
65+
```
66+
67+
```json
68+
{
69+
"version": 0,
70+
"uuid": "",
71+
"application": {
72+
"name": "xiaoniu-web-test",
73+
"version": "1.0.0",
74+
"compile_time": "2025-04-16 10:00:00",
75+
"idf_version": "4.4.3",
76+
"elf_sha256": "1234567890abcdef1234567890abcdef1234567890abcdef"
77+
},
78+
"ota": { "label": "xiaoling-web-test" },
79+
"board": {
80+
"type": "xiaoling-web-test",
81+
"ssid": "xiaoling-web-test",
82+
"rssi": 0,
83+
"channel": 0,
84+
"ip": "192.168.1.1",
85+
"mac": "D4:06:06:B6:A9:FA"
86+
},
87+
"flash_size": 0,
88+
"minimum_free_heap_size": 0,
89+
"mac_address": "D4:06:06:B6:A9:FA",
90+
"chip_model_name": "",
91+
"chip_info": { "model": 0, "cores": 0, "revision": 0, "features": 0 },
92+
"partition_table": [
93+
{ "label": "", "type": 0, "subtype": 0, "address": 0, "size": 0 }
94+
]
95+
}
96+
```
97+
98+
## 响应示例
99+
100+
```json
101+
{
102+
"server_time": {
103+
"timestamp": 1752119934489,
104+
"timeZone": "Asia/Shanghai",
105+
"timezone_offset": 480
106+
},
107+
"activation": {
108+
"code": "608303", //【这就是我们需要的激活码】
109+
"message": "http://60.205.58.18:8002\n608303",
110+
"challenge": "D4:06:06:B6:A9:FA"
111+
},
112+
"firmware": {
113+
"version": "1.0.0",
114+
"url": "https://xrobo.qiniuapi.com/v1/ota/INVALID_FIRMWARE_FOR_TEST"
115+
},
116+
"websocket": {
117+
"url": "ws://xrobo-io.qiniuapi.com/v1/ws/"
118+
}
119+
}
120+
```
121+
122+
## 错误响应
123+
124+
```json
125+
//缺少 device-id
126+
HTTP/1.1 400 Bad Request
127+
Content-Type: application/json
128+
129+
{
130+
"error": "Device ID is required"
131+
}
132+
133+
//无效的 OTA 请求
134+
{
135+
"error": "Invalid OTA request"
136+
}
137+
138+
//服务器内部错误
139+
{
140+
"error": "Failed to read device auto_update status"
141+
}
142+
143+
```

docs/xrobot/api/protocol/imgs/device-protocol/auto.png renamed to docs/xrobot/api/protocol/imgs/websocket/auto.png

File renamed without changes.

docs/xrobot/api/protocol/imgs/device-protocol/manual.png renamed to docs/xrobot/api/protocol/imgs/websocket/manual.png

File renamed without changes.

docs/xrobot/api/protocol/device-protocol.md renamed to docs/xrobot/api/protocol/websocket.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,17 @@
11
---
2-
title: 设备服务通信协议
2+
title: WebSocket 协议
33
---
44

5-
## 1. Websocket 通信协议
5+
## 1. WebSocket 地址
6+
7+
<wss://xrobo-io.qiniuapi.com/v1/ws/>
8+
9+
## 2. WebSocket 通信协议
610

711
### 基本信息
812

913
- 协议版本: 1
10-
- 传输方式: Websocket
14+
- 传输方式: WebSocket
1115
- 音频格式: OPUS
1216
- 音频参数:
1317
- 采样率: 16000Hz
@@ -16,7 +20,7 @@ title: 设备服务通信协议
1620

1721
### 会话流程
1822

19-
1. 建立 Websocket 连接
23+
1. 建立 WebSocket 连接
2024
2. 交换 hello 消息
2125
3. 开始语音交互:
2226

@@ -27,7 +31,7 @@ title: 设备服务通信协议
2731

2832
### 连接建立
2933

30-
1. 客户端连接 Websocket 服务器时需要携带以下 headers:
34+
1. 客户端连接 WebSocket 服务器时需要携带以下 headers:
3135

3236
```Plain Text
3337
Authorization: Bearer <access_token> 【服务端如果开启 auth，则需要验证 token】
@@ -73,7 +77,7 @@ title: 设备服务通信协议
7377
}
7478
```
7579

76-
Websocket 协议不返回 session_id，所以消息中的会话 ID 可设置为空。
80+
WebSocket 协议不返回 session_id，所以消息中的会话 ID 可设置为空。
7781

7882
### 消息类型
7983

@@ -181,10 +185,10 @@ title: 设备服务通信协议
181185
### 状态流程图
182186

183187
Manual 模式
184-
<img src="./imgs/device-protocol/manual.png" class="img-center" />
188+
<img src="./imgs/websocket/manual.png" class="img-center" />
185189

186190
Auto 模式
187-
<img src="./imgs/device-protocol/auto.png" class="img-center" />
191+
<img src="./imgs/websocket/auto.png" class="img-center" />
188192

189193
### 二进制数据传输
190194

@@ -195,7 +199,3 @@ Auto 模式
195199
### 错误处理
196200

197201
当发生网络错误时，客户端会收到错误消息并关闭连接。客户端需要实现重连机制。
198-
199-
## 2. MQTT 通信协议
200-
201-
待补充。

‎docs/xrobot/platform/others/console/device-bind.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: 设备绑定
3+
---
4+
5+
## 1. 绑定 MAC 地址
6+
7+
- 第一步：访问控制台，注册账号，登录
8+
9+
- 第二步：新建智能体：
10+
11+
<img src="./imgs/device-bind/agentcard-eg.png">
12+
13+
- 第三步：在“设备管理”中，选择 批量导入，填写设备的 mac 地址：
14+
15+
<img src="./imgs/device-bind/device-import.png">
16+
17+
不知道设备 mac 地址怎么办？
18+
19+
## 2. 绑定设备激活码
20+
21+
- 第三步：通过 在“设备管理”中，选择新增，填写 设备激活码
22+
<img src="./imgs/device-bind/3.device-code.png">
23+
24+
怎么获取设备激活码？
25+
26+
### 2.1 获取设备激活码
27+
28+
通过 OTA 通信协议获取，参考 [OTA 协议](/xrobot/api/protocol/ota)
29+
30+
### 2.2 ESP32 设备通过 OTA 拿到激活码后，没有及时绑定会怎么样？
31+
32+
首先，设备会一直定期的发送 ota/activate 请求，提醒您去绑定；此时设备也无法唤醒，无法通话
33+
34+
<img src="./imgs/device-bind/2.2.png" class="img-center">
35+
36+
其次，如果服务端 auth 验证需要 token，这个 token 是有保活期，超过了，需要重启设备，因为市面上的固件都没有定期 ota 过程，只有重启设备才会有 ota 消息发送。
37+
38+
### 2.3 怎么重新绑定
39+
40+
需要在控制台先解除绑定，再重新绑定，设备解除绑定后，设备当前通话并不会立刻终止，只有当重新开启会话时，会提醒你重启设备，重新拿到激活码，重新去走一遍流程。
41+
42+
<img src="./imgs/device-bind/2.3.png" class="img-center">

docs/xrobot/platform/others/device/imgs/device-bind/2.2.png renamed to docs/xrobot/platform/others/console/imgs/device-bind/2.2.png

File renamed without changes.

docs/xrobot/platform/others/device/imgs/device-bind/2.3.png renamed to docs/xrobot/platform/others/console/imgs/device-bind/2.3.png

File renamed without changes.

docs/xrobot/platform/others/device/imgs/device-bind/3.device-code.png renamed to docs/xrobot/platform/others/console/imgs/device-bind/3.device-code.png

File renamed without changes.

0 commit comments

Comments
 (0)