@seeed-studio/sensecraft-cli 0.4.8 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README-zh.md +463 -0
- package/README.md +1 -1
- package/bin/sensecraft-cli.js +1 -1
- package/package.json +2 -2
- package/scripts/install.js +10 -10
- package/skills/sensecraft-cli/SKILL.md +2 -1
- package/skills/sensecraft-cli/create-app/SKILL.md +42 -5
- package/skills/sensecraft-cli/create-app/assets/validate_manifest.py +232 -11
- package/skills/sensecraft-cli/references/app-commands.md +1 -1
- package/skills/sensecraft-cli/references/apps.md +10 -0
- package/skills/sensecraft-cli/references/data-commands.md +2 -2
- package/skills/sensecraft-cli/references/file-commands.md +3 -0
- package/skills/sensecraft-cli/references/files.md +22 -1
- package/skills/sensecraft-cli/references/tool-blocks.md +41 -18
package/README-zh.md
ADDED
|
@@ -0,0 +1,463 @@
|
|
|
1
|
+
# SenseCraft CLI
|
|
2
|
+
|
|
3
|
+
[English](README.md) | 中文
|
|
4
|
+
|
|
5
|
+
SenseCraft CLI(`sensecraft-cli`)是 [SenseCraft](https://sensecraft.seeed.cc) 的官方命令行工具,供开发者和 AI Agent 使用。可以在终端里读取传感数据、创建模型、发布应用,并管理设备和 reCamera。
|
|
6
|
+
|
|
7
|
+
它覆盖这三块产品:
|
|
8
|
+
|
|
9
|
+
| 产品 | 管什么 | 子命令 |
|
|
10
|
+
|------|--------|--------|
|
|
11
|
+
| [SenseCraft Data](https://sensecap.seeed.cc) | 设备、分组、传感数据 | `device` · `group` · `data` |
|
|
12
|
+
| [SenseCraft AI](https://sensecraft.seeed.cc) | 模型库,以及 reCamera | `model` · `recamera` · `cloud` |
|
|
13
|
+
| [CodeCraft Hub](https://codecraft.seeed.cc/hub) | 应用 | `app` |
|
|
14
|
+
|
|
15
|
+
三个平台均以开放 Access Key 访问。在 [SenseCraft 用户中心](https://account.seeed.cc/account/access-keys) 创建和管理钥匙,再用 `auth add` 写入本机。运行 `auth init`,使用 OAuth2 Device Flow 授权 CLI 访问你的账号。
|
|
16
|
+
|
|
17
|
+
也可以放进脚本和 CI。Agent Skills 见 `skills/`。
|
|
18
|
+
|
|
19
|
+
**安装与排障请先读 → [`INSTALL.md`](INSTALL.md)**(平台要求、PATH、升级卸载、离线镜像、Cursor Skills)。
|
|
20
|
+
|
|
21
|
+
## 环境要求
|
|
22
|
+
|
|
23
|
+
- Node.js >= 16(用于 npm 安装与分发)
|
|
24
|
+
- 构建源码:Go(见 `go.mod`)
|
|
25
|
+
|
|
26
|
+
## 安装
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npx @seeed-studio/sensecraft-cli install
|
|
30
|
+
sensecraft-cli --version
|
|
31
|
+
sensecraft-cli update
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
完整步骤、Windows PATH、离线安装与 Skills 接入见 [`INSTALL.md`](INSTALL.md)。
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
sensecraft-cli --help
|
|
38
|
+
# 或
|
|
39
|
+
npx @seeed-studio/sensecraft-cli device list
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## 快速开始
|
|
43
|
+
|
|
44
|
+
### 1. 初始化认证
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# 使用 OAuth2 Device Flow 授权 CLI 访问你的账号。交互选择站点:Global / China
|
|
48
|
+
sensecraft-cli auth init
|
|
49
|
+
|
|
50
|
+
# 已在账号页创建好钥匙时,直接写入本机
|
|
51
|
+
sensecraft-cli auth add --key-id <Key ID> --access-key <Access Key>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
创建和管理 Access Key:<https://account.seeed.cc/account/access-keys>。
|
|
55
|
+
|
|
56
|
+
中国站仅支持 SenseCraft Data。如果需要使用 SenseCraft CLI 访问 SenseCraft AI 和 CodeCraft Hub,请选择国际站(Global)。
|
|
57
|
+
|
|
58
|
+
### 2. 查看配置
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
sensecraft-cli auth info
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### 3. 示例
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# SenseCraft Data
|
|
68
|
+
sensecraft-cli device list
|
|
69
|
+
sensecraft-cli data latest --eui <EUI>
|
|
70
|
+
|
|
71
|
+
# SenseCraft AI。任务编号用 model constants 查,不要猜一个数字
|
|
72
|
+
sensecraft-cli model constants
|
|
73
|
+
sensecraft-cli model list --public --uniform-type 40
|
|
74
|
+
sensecraft-cli recamera check --model-id <id>
|
|
75
|
+
sensecraft-cli recamera open --model-id <id> --print-only
|
|
76
|
+
sensecraft-cli cloud device list --uniform-type 26
|
|
77
|
+
|
|
78
|
+
# CodeCraft Hub
|
|
79
|
+
sensecraft-cli app list --public --name "vision"
|
|
80
|
+
sensecraft-cli app list --public --uniform-type 40
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`--uniform-type`:`40` 是 reCamera,`32` 是 XIAO ESP32S3,`53` 是 reCamera Pro。`cloud device list` 里的 `26` 是 Jetson 云设备界面常用的设备类型。
|
|
84
|
+
|
|
85
|
+
删除、解绑、发布、部署这类写操作必须加 `--yes`。Agent 的确认步骤见 [skills/sensecraft-cli/references/confirmation.md](skills/sensecraft-cli/references/confirmation.md)。
|
|
86
|
+
|
|
87
|
+
## 配置
|
|
88
|
+
|
|
89
|
+
| 项 | 说明 |
|
|
90
|
+
|----|------|
|
|
91
|
+
| npm 安装默认 | macOS/Linux:`~/.config/sensecraft-cli/sensecraft.json`;Windows:`%APPDATA%\sensecraft-cli\sensecraft.json`(wrapper 注入 `SENSECRAFT_CLI_PATH`) |
|
|
92
|
+
| 源码直接运行默认 | 当前工作目录下的 `sensecraft.json` |
|
|
93
|
+
| `SENSECRAFT_CLI_PATH` | 配置目录(文件名为 `sensecraft.json`) |
|
|
94
|
+
| `SENSECRAFT_CONFIG_FILE` | 配置文件完整路径(优先于上面两项) |
|
|
95
|
+
|
|
96
|
+
## 输出格式
|
|
97
|
+
|
|
98
|
+
- 业务命令成功:stdout JSON(缩进 2 空格)
|
|
99
|
+
- `auth info` / `auth init`:人类可读文本(非 JSON)
|
|
100
|
+
- 失败:stderr + 非 0 退出码
|
|
101
|
+
- 版本:`sensecraft-cli --version`(与 npm 包版本一致)
|
|
102
|
+
|
|
103
|
+
## 用在脚本和 CI
|
|
104
|
+
|
|
105
|
+
无交互环境不会打开浏览器。用 `auth add` 写入钥匙,并用 `SENSECRAFT_CONFIG_FILE` 指到项目自己的配置文件,避免写进本机的 `~/.config/sensecraft-cli/`。
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
export SENSECRAFT_CONFIG_FILE="$PWD/.sensecraft/sensecraft.json"
|
|
109
|
+
sensecraft-cli auth add \
|
|
110
|
+
--key-id "$SENSECRAFT_KEY_ID" \
|
|
111
|
+
--access-key "$SENSECRAFT_ACCESS_KEY" \
|
|
112
|
+
--site Global
|
|
113
|
+
sensecraft-cli device list
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
这个文件含有 Access Key,不要提交到仓库。`--site` 省略时是 `Global`。业务命令成功时解析 stdout 的 JSON;失败看退出码,错误在 stderr。`auth info` 的输出是文本。
|
|
117
|
+
|
|
118
|
+
## AI Agent Skills
|
|
119
|
+
|
|
120
|
+
入口是 [`skills/sensecraft-cli/SKILL.md`](skills/sensecraft-cli/SKILL.md)。设备、模型、应用等说明在 `skills/sensecraft-cli/references/`。从本地工程生成应用用嵌套技能 `skills/sensecraft-cli/create-app/`。
|
|
121
|
+
|
|
122
|
+
安装后把这个目录软链到 Agent 的技能目录,不要复制。升级 CLI 时技能会一起更新。步骤见 [`INSTALL.md` §9](INSTALL.md#9-agent-skills-cursor-and-others)。
|
|
123
|
+
|
|
124
|
+
## 从源码构建
|
|
125
|
+
|
|
126
|
+
完整说明见 [`INSTALL.md` §8](INSTALL.md#8-build-from-source)。摘要:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
# 本机调试
|
|
130
|
+
go build -o sensecraft-cli .
|
|
131
|
+
./sensecraft-cli --version
|
|
132
|
+
|
|
133
|
+
# 多平台发布二进制 → dist/(注入 -ldflags 版本信息)
|
|
134
|
+
./script/build.sh
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
贡献本仓库时的自检:`./script/smoke-ai.sh`、`./script/smoke-sensecap.sh`。隔离安装检查要先 `./script/build.sh`,再在 `packages/cli` 里运行 `npm run test:install`。使用 CLI 的项目不需要这些脚本。
|
|
138
|
+
|
|
139
|
+
## 许可证
|
|
140
|
+
|
|
141
|
+
[MIT](LICENSE)
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 命令文档
|
|
146
|
+
|
|
147
|
+
本文展开 SenseCraft Data。其它命令的参数、限制和示例:
|
|
148
|
+
|
|
149
|
+
| 范围 | 文档 |
|
|
150
|
+
|------|------|
|
|
151
|
+
| SenseCraft Data | [data-commands.md](skills/sensecraft-cli/references/data-commands.md) |
|
|
152
|
+
| 模型库 | [model-commands.md](skills/sensecraft-cli/references/model-commands.md) |
|
|
153
|
+
| reCamera | [recamera-commands.md](skills/sensecraft-cli/references/recamera-commands.md) |
|
|
154
|
+
| 云设备部署与订单 | [cloud-commands.md](skills/sensecraft-cli/references/cloud-commands.md) |
|
|
155
|
+
| CodeCraft Hub 应用 | [app-commands.md](skills/sensecraft-cli/references/app-commands.md) |
|
|
156
|
+
| 文件上传 | [file-commands.md](skills/sensecraft-cli/references/file-commands.md) |
|
|
157
|
+
|
|
158
|
+
## 命令参考(SenseCraft Data)
|
|
159
|
+
|
|
160
|
+
### auth — 认证与配置
|
|
161
|
+
|
|
162
|
+
#### `auth init`
|
|
163
|
+
|
|
164
|
+
使用 OAuth2 Device Flow 授权 CLI 访问你的账号。交互选择站点:Global / China。
|
|
165
|
+
|
|
166
|
+
| 参数 | 说明 |
|
|
167
|
+
|------|------|
|
|
168
|
+
| `--sandbox` | 沙盒:不发真实网络请求 |
|
|
169
|
+
|
|
170
|
+
#### `auth add`
|
|
171
|
+
|
|
172
|
+
把已有的 Access Key 写入本机,并设为当前钥匙。无交互环境必须带上 `--key-id` 和 `--access-key`。
|
|
173
|
+
|
|
174
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
175
|
+
|------|------|--------|------|
|
|
176
|
+
| `--key-id` | 交互终端可省略 | — | Key ID |
|
|
177
|
+
| `--access-key` | 交互终端可省略 | — | Access Key |
|
|
178
|
+
| `--site` | 否 | `Global` | `Global` 或 `China` |
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
sensecraft-cli auth add --key-id <Key ID> --access-key <Access Key> --site Global
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
#### `auth info`
|
|
185
|
+
|
|
186
|
+
`info` 展示当前 Access Key 的站点、组织 ID 和 Key ID,不打印密钥。
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
### device — 设备管理(SenseCraft Data)
|
|
191
|
+
|
|
192
|
+
#### `device list`
|
|
193
|
+
|
|
194
|
+
获取当前账号下的设备列表。
|
|
195
|
+
|
|
196
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
197
|
+
|------|------|--------|------|
|
|
198
|
+
| `--device-type` | 否 | `2` | 设备类型:`1`=网关,`2`=节点,`3`=开发套件 |
|
|
199
|
+
| `--group-uuid` | 否 | — | 按分组 UUID 筛选;不传则返回所有分组下的设备 |
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
# 列出所有节点(默认)
|
|
203
|
+
sensecraft-cli device list
|
|
204
|
+
|
|
205
|
+
# 列出网关
|
|
206
|
+
sensecraft-cli device list --device-type 1
|
|
207
|
+
|
|
208
|
+
# 列出开发套件
|
|
209
|
+
sensecraft-cli device list --device-type 3
|
|
210
|
+
|
|
211
|
+
# 列出指定分组下的设备
|
|
212
|
+
sensecraft-cli device list --group-uuid <group-uuid>
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
#### `device view`
|
|
216
|
+
|
|
217
|
+
获取设备详情(最多 50 个 EUI)。
|
|
218
|
+
|
|
219
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
220
|
+
|------|------|--------|------|
|
|
221
|
+
| `--eui` | 是 | — | 设备 EUI,可多次指定 |
|
|
222
|
+
| `--device-type` | 否 | `2` | 设备类型:`1`=网关,`2`=节点,`3`=开发套件 |
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
sensecraft-cli device view --eui 0123456789ABCDEF
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
#### `device channels`
|
|
229
|
+
|
|
230
|
+
查询节点通道列表(最多 50 个 EUI)。
|
|
231
|
+
|
|
232
|
+
| 参数 | 必填 | 说明 |
|
|
233
|
+
|------|------|------|
|
|
234
|
+
| `--eui` | 是 | 设备 EUI,可多次指定 |
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
sensecraft-cli device channels --eui 0123456789ABCDEF
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
#### `device status`
|
|
241
|
+
|
|
242
|
+
获取设备运行状态(最多 50 个 EUI)。
|
|
243
|
+
|
|
244
|
+
| 参数 | 必填 | 说明 |
|
|
245
|
+
|------|------|------|
|
|
246
|
+
| `--eui` | 是 | 设备 EUI,可多次指定 |
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
sensecraft-cli device status --eui 0123456789ABCDEF
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
#### `device bind`
|
|
253
|
+
|
|
254
|
+
将设备绑定到当前账号。
|
|
255
|
+
|
|
256
|
+
| 参数 | 必填 | 说明 |
|
|
257
|
+
|------|------|------|
|
|
258
|
+
| `--eui` | 是 | 设备 EUI |
|
|
259
|
+
| `--code` | 是 | 设备绑定码 |
|
|
260
|
+
| `--name` | 否 | 设备名称 |
|
|
261
|
+
| `--group-uuid` | 否 | 目标分组 UUID |
|
|
262
|
+
| `--longitude` | 否 | 经度 |
|
|
263
|
+
| `--latitude` | 否 | 纬度 |
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
sensecraft-cli device bind --eui 0123456789ABCDEF --code ABCD1234 --name "我的传感器"
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
#### `device unbind`
|
|
270
|
+
|
|
271
|
+
解绑设备(最多 50 个 EUI)。须加 `--yes`。
|
|
272
|
+
|
|
273
|
+
| 参数 | 必填 | 说明 |
|
|
274
|
+
|------|------|------|
|
|
275
|
+
| `--eui` | 是 | 设备 EUI,可多次指定 |
|
|
276
|
+
| `--yes` | 是 | 确认执行 |
|
|
277
|
+
|
|
278
|
+
```bash
|
|
279
|
+
sensecraft-cli device unbind --eui 0123456789ABCDEF --yes
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
#### `device sim`
|
|
283
|
+
|
|
284
|
+
查看 SIM 卡状态。
|
|
285
|
+
|
|
286
|
+
| 参数 | 必填 | 说明 |
|
|
287
|
+
|------|------|------|
|
|
288
|
+
| `--iccid` | 是 | SIM 卡 ICCID |
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
sensecraft-cli device sim --iccid 89860000000000000000
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
### device devkit — 开发套件
|
|
297
|
+
|
|
298
|
+
#### `device devkit create`
|
|
299
|
+
|
|
300
|
+
创建开发套件设备。同一组织下每个 SKU 最多创建 5 个。
|
|
301
|
+
|
|
302
|
+
| 参数 | 必填 | 说明 |
|
|
303
|
+
|------|------|------|
|
|
304
|
+
| `--sku` | 是 | 开发套件 SKU |
|
|
305
|
+
| `--name` | 否 | 设备名称 |
|
|
306
|
+
|
|
307
|
+
支持的 SKU:
|
|
308
|
+
|
|
309
|
+
| SKU | 说明 |
|
|
310
|
+
|-----|------|
|
|
311
|
+
| `blank_device` | Blank Device |
|
|
312
|
+
| `xiao` | XIAO |
|
|
313
|
+
| `grove_vision_ai` | Grove Vision AI V2 |
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
sensecraft-cli device devkit create --sku xiao --name "我的 XIAO 套件"
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
#### `device devkit key`
|
|
320
|
+
|
|
321
|
+
查看开发套件设备的 `device_key` 与 `token`(仅支持开发套件设备,EUI 为 16 位字符)。
|
|
322
|
+
|
|
323
|
+
| 参数 | 必填 | 说明 |
|
|
324
|
+
|------|------|------|
|
|
325
|
+
| `--eui` | 是 | 开发套件设备 EUI(16 位) |
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
sensecraft-cli device devkit key --eui 0123456789ABCDEF
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
---
|
|
332
|
+
|
|
333
|
+
### group — 设备分组
|
|
334
|
+
|
|
335
|
+
#### `group list`
|
|
336
|
+
|
|
337
|
+
列出当前账号下的所有设备分组。
|
|
338
|
+
|
|
339
|
+
#### `group create`
|
|
340
|
+
|
|
341
|
+
创建设备分组(最多 50 个分组)。
|
|
342
|
+
|
|
343
|
+
| 参数 | 必填 | 说明 |
|
|
344
|
+
|------|------|------|
|
|
345
|
+
| `--name` | 是 | 分组名称 |
|
|
346
|
+
|
|
347
|
+
```bash
|
|
348
|
+
sensecraft-cli group create --name "温室传感器"
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
#### `group update`
|
|
352
|
+
|
|
353
|
+
更新设备分组名称。
|
|
354
|
+
|
|
355
|
+
| 参数 | 必填 | 说明 |
|
|
356
|
+
|------|------|------|
|
|
357
|
+
| `--group-uuid` | 是 | 分组 UUID |
|
|
358
|
+
| `--name` | 是 | 新分组名称 |
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
sensecraft-cli group update --group-uuid <uuid> --name "新名称"
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
#### `group delete`
|
|
365
|
+
|
|
366
|
+
删除设备分组(组内设备将移至默认分组)。须加 `--yes`。
|
|
367
|
+
|
|
368
|
+
| 参数 | 必填 | 说明 |
|
|
369
|
+
|------|------|------|
|
|
370
|
+
| `--group-uuid` | 是 | 分组 UUID |
|
|
371
|
+
| `--yes` | 是 | 确认执行 |
|
|
372
|
+
|
|
373
|
+
```bash
|
|
374
|
+
sensecraft-cli group delete --group-uuid <uuid> --yes
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
#### `group move-devices`
|
|
378
|
+
|
|
379
|
+
将设备移动到指定分组。须加 `--yes`。
|
|
380
|
+
|
|
381
|
+
| 参数 | 必填 | 说明 |
|
|
382
|
+
|------|------|------|
|
|
383
|
+
| `--group-uuid` | 是 | 目标分组 UUID |
|
|
384
|
+
| `--eui` | 是 | 设备 EUI,可多次指定 |
|
|
385
|
+
| `--yes` | 是 | 确认执行 |
|
|
386
|
+
|
|
387
|
+
```bash
|
|
388
|
+
sensecraft-cli group move-devices --group-uuid <uuid> --eui 0123456789ABCDEF --yes
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
---
|
|
392
|
+
|
|
393
|
+
### data — 传感数据
|
|
394
|
+
|
|
395
|
+
#### `data latest`
|
|
396
|
+
|
|
397
|
+
获取设备最近一年内的最新遥测数据;未指定通道时返回每个通道下最新数据点。
|
|
398
|
+
|
|
399
|
+
| 参数 | 必填 | 说明 |
|
|
400
|
+
|------|------|------|
|
|
401
|
+
| `--eui` | 是 | 设备 EUI |
|
|
402
|
+
| `--measurement-id` | 否 | 测量值 ID |
|
|
403
|
+
| `--channel-index` | 否 | 通道编号 |
|
|
404
|
+
|
|
405
|
+
```bash
|
|
406
|
+
sensecraft-cli data latest --eui 0123456789ABCDEF --measurement-id 4097 --channel-index 1
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
#### `data list`
|
|
410
|
+
|
|
411
|
+
获取设备历史遥测数据(单次最长约一个月,且仅可查近三个月内数据)。
|
|
412
|
+
|
|
413
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
414
|
+
|------|------|--------|------|
|
|
415
|
+
| `--eui` | 是 | — | 设备 EUI |
|
|
416
|
+
| `--measurement-id` | 否 | — | 测量值 ID |
|
|
417
|
+
| `--channel-index` | 否 | — | 通道编号 |
|
|
418
|
+
| `--limit` | 否 | — | 返回记录数 |
|
|
419
|
+
| `--time-start` | 否 | — | 起始时间戳(毫秒) |
|
|
420
|
+
| `--time-end` | 否 | — | 结束时间戳(毫秒) |
|
|
421
|
+
|
|
422
|
+
```bash
|
|
423
|
+
sensecraft-cli data list --eui 0123456789ABCDEF --limit 100 --time-start 1700000000000 --time-end 1700086400000
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
#### `data chart`
|
|
427
|
+
|
|
428
|
+
获取设备遥测折线聚合点(最长一年;每个测量最多约 250 个点)。
|
|
429
|
+
|
|
430
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
431
|
+
|------|------|--------|------|
|
|
432
|
+
| `--eui` | 是 | — | 设备 EUI |
|
|
433
|
+
| `--measurement-id` | 否 | — | 测量值 ID |
|
|
434
|
+
| `--channel-index` | 否 | — | 通道编号 |
|
|
435
|
+
| `--interval` | 否 | `60` | 时间段长度(分钟) |
|
|
436
|
+
| `--time-start` | 否 | — | 起始时间戳(毫秒) |
|
|
437
|
+
| `--time-end` | 否 | — | 结束时间戳(毫秒) |
|
|
438
|
+
|
|
439
|
+
```bash
|
|
440
|
+
sensecraft-cli data chart --eui 0123456789ABCDEF --interval 60 --time-start 1700000000000 --time-end 1702592000000
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
---
|
|
444
|
+
|
|
445
|
+
## 典型工作流
|
|
446
|
+
|
|
447
|
+
```bash
|
|
448
|
+
# 安装并初始化
|
|
449
|
+
npx @seeed-studio/sensecraft-cli install
|
|
450
|
+
|
|
451
|
+
# 查看分组
|
|
452
|
+
sensecraft-cli group list
|
|
453
|
+
|
|
454
|
+
# 列出节点设备
|
|
455
|
+
sensecraft-cli device list
|
|
456
|
+
|
|
457
|
+
# 查看设备详情与通道
|
|
458
|
+
sensecraft-cli device view --eui 0123456789ABCDEF
|
|
459
|
+
sensecraft-cli device channels --eui 0123456789ABCDEF
|
|
460
|
+
|
|
461
|
+
# 查询最新数据
|
|
462
|
+
sensecraft-cli data latest --eui 0123456789ABCDEF
|
|
463
|
+
```
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
The official command-line tool for [SenseCraft](https://sensecraft.seeed.cc). Read sensor data, create models, and publish applications — for developers and AI agents.
|
|
4
4
|
|
|
5
|
-
Chinese: [README
|
|
5
|
+
Chinese: [README-zh.md](README-zh.md).
|
|
6
6
|
|
|
7
7
|
## Install
|
|
8
8
|
|
package/bin/sensecraft-cli.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@seeed-studio/sensecraft-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "SenseCAP / SenseCraft AI cloud CLI (devices, apps, models, files, cloud deploy)",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"skills",
|
|
27
27
|
"LICENSE",
|
|
28
28
|
"README.md",
|
|
29
|
-
"README
|
|
29
|
+
"README-zh.md",
|
|
30
30
|
"INSTALL.md"
|
|
31
31
|
],
|
|
32
32
|
"os": [
|
package/scripts/install.js
CHANGED
|
@@ -27,7 +27,7 @@ function getGlobalCliPath() {
|
|
|
27
27
|
|
|
28
28
|
function installGlobally() {
|
|
29
29
|
const packageRoot = getPackageRoot();
|
|
30
|
-
console.log('
|
|
30
|
+
console.log('正在全局安装 sensecraft-cli...');
|
|
31
31
|
execSync(`npm install -g ${JSON.stringify(packageRoot)}`, {
|
|
32
32
|
stdio: 'inherit',
|
|
33
33
|
env: process.env,
|
|
@@ -35,7 +35,7 @@ function installGlobally() {
|
|
|
35
35
|
|
|
36
36
|
const cliPath = getGlobalCliPath();
|
|
37
37
|
if (!fs.existsSync(cliPath)) {
|
|
38
|
-
throw new Error(
|
|
38
|
+
throw new Error(`全局命令未找到: ${cliPath},请确认 npm 全局 bin 目录在 PATH 中`);
|
|
39
39
|
}
|
|
40
40
|
return cliPath;
|
|
41
41
|
}
|
|
@@ -43,20 +43,20 @@ function installGlobally() {
|
|
|
43
43
|
function runInitIfNeeded(cliPath) {
|
|
44
44
|
if (isInitialized()) {
|
|
45
45
|
console.log('');
|
|
46
|
-
console.log('
|
|
46
|
+
console.log('✓ 配置文件已存在,跳过初始化');
|
|
47
47
|
console.log(' sensecraft-cli auth info');
|
|
48
48
|
return;
|
|
49
49
|
}
|
|
50
50
|
|
|
51
51
|
if (!process.stdin.isTTY || !process.stdout.isTTY) {
|
|
52
52
|
console.log('');
|
|
53
|
-
console.log('
|
|
54
|
-
console.log('
|
|
53
|
+
console.log('未检测到交互式终端,已跳过自动初始化。');
|
|
54
|
+
console.log('请稍后运行: sensecraft-cli auth init');
|
|
55
55
|
return;
|
|
56
56
|
}
|
|
57
57
|
|
|
58
58
|
console.log('');
|
|
59
|
-
console.log('
|
|
59
|
+
console.log('未检测到配置文件,开始自动初始化...');
|
|
60
60
|
console.log('');
|
|
61
61
|
|
|
62
62
|
const result = spawnSync(cliPath, ['auth', 'init'], {
|
|
@@ -76,12 +76,12 @@ function runInitIfNeeded(cliPath) {
|
|
|
76
76
|
function printDone(globalCliPath) {
|
|
77
77
|
const globalBin = getGlobalBinDir();
|
|
78
78
|
console.log('');
|
|
79
|
-
console.log('
|
|
80
|
-
console.log(
|
|
81
|
-
console.log(`
|
|
79
|
+
console.log('✓ 安装完成');
|
|
80
|
+
console.log(` 命令: sensecraft-cli`);
|
|
81
|
+
console.log(` 路径: ${globalCliPath}`);
|
|
82
82
|
if (!process.env.PATH || !process.env.PATH.split(path.delimiter).includes(globalBin)) {
|
|
83
83
|
console.log('');
|
|
84
|
-
console.log('
|
|
84
|
+
console.log('提示: 若无法直接运行 sensecraft-cli,请将以下目录加入 PATH:');
|
|
85
85
|
console.log(` ${globalBin}`);
|
|
86
86
|
}
|
|
87
87
|
console.log('');
|
|
@@ -41,7 +41,7 @@ SenseCraft Data: [`references/data.md`](references/data.md).
|
|
|
41
41
|
Create a key with `--label <name> --access-level read-write` (or `only-read`) instead of `--key-id`. Use Global for SenseCraft AI and CodeCraft Hub. China is SenseCraft Data only. Do not print `access_token` or `access_key`. If the user already has a key, they can run `auth add` locally.
|
|
42
42
|
4. **L2 confirmation is a separate chat turn** — follow [references/confirmation.md](references/confirmation.md). 「删这个63760」/「删除应用 demo」is **intent, not confirmation**. Ask first (操作类型 + 环境 + 对象 ID), wait for `确认`/`confirm`, **then** `--yes`. Never add `--yes` on the same turn as the first request. Applies to: app update·publish·unpublish·withdraw·delete, model create·update·publish·unpublish·delete, upload attach, cloud deploy, device bind/unbind, group create/rename/delete/move. **Exception: `app create`, including one-shot `--from-json`, is not L2 and takes no `--yes`; resolve uncertain content decisions and review the result first.**
|
|
43
43
|
5. **Treat tokens and keys as secrets** — do not echo full `access_token`, `refresh_token`, or `access_key`. **Public model artifacts are not downloadable** — if the user asks for 下载地址 / 下载链接 / download URL / 怎么下载, that is the same as asking for `file_url`: refuse the address, explain deploy-only (`cloud deploy` or Console). Never run `model download --url-only` on public models.
|
|
44
|
-
6. **
|
|
44
|
+
6. **Business-command success = indented JSON on stdout**; auth commands print human-readable text. Failure = stderr + non-zero exit. Parse stdout only on success.
|
|
45
45
|
7. **Local USB / IP flashing is L3** — do not pretend remote auto-flash. Classic reCamera (`40`): [`sensecraft-recamera`](references/recamera.md) (`check` / `open` the AI deploy page). Other USB benches: Console `/ai/device/local/32|36|37|41|52`. Do **not** use `/ai/recamera` (it 301s to Grove `36`) or `/ai/device/local/40` (no such bench).
|
|
46
46
|
8. **Upgrading the CLI itself** is `sensecraft-cli update` (npm registry, then `npm install -g`). This is not `app update` or `model update`. Uninstall with `npm uninstall -g @seeed-studio/sensecraft-cli`. Do not delete `~/.config/sensecraft-cli` unless the user asked to clear the saved Access Key.
|
|
47
47
|
|
|
@@ -63,6 +63,7 @@ Bare `auth init` asks the user to pick Global or China. The split flow takes `--
|
|
|
63
63
|
| Turn a local project into an app (discovery + reviewed copy + tool blocks + API-confirmed BOM + manifest + upload), or update its manifest-managed app | [`create-app`](create-app/SKILL.md) | Read required references before authoring; create needs no `--yes`; existing-app updates use one batch confirmation; stops before publish |
|
|
64
64
|
| Create / update / publish / unpublish / withdraw / delete / bom app | same + `app …` / `app bom …` | **CLI shipped** (L2 `--yes`; publish also `--agree-declaration`; `create`, including `--from-json`, is not L2). `withdraw` is only for an app under review (`be_public=2`); `unpublish` is only for an already public app |
|
|
65
65
|
| Upload image/file/firmware/static/archive and obtain `file_url` | [`sensecraft-files`](references/files.md) + `file upload` | Types `1`–`2` require `--model-id`/`--app-id --yes`/`--for-app`/`--unlinked`; type `5` requires `--flow-id`; types `3`–`6` direct |
|
|
66
|
+
| Before compiling board firmware for Hub flash | `firmware advise --device-id` / `--name` | Offline JSON `build_recipe` (artifact/chip/forbid/Muse/upload). Also on `app blocks` → `device_defaults` |
|
|
66
67
|
| Model library search/view/download/constants | [`sensecraft-models`](references/models.md) | **CLI shipped** |
|
|
67
68
|
| Upload / publish / unpublish / delete model | same + `model upload --id --yes` / `create\|update\|publish\|unpublish\|delete` | Attach bumps patch version like Console |
|
|
68
69
|
| Classic reCamera (`40`) pick / check / open deploy page | [`sensecraft-recamera`](references/recamera.md) + `app/model list --uniform-type 40` + `recamera check` / `open` | **CLI shipped**. Flash is Console L3 (IP/USB). Not `cloud deploy`. Not Pro `53`. |
|
|
@@ -38,7 +38,7 @@ Keep concise evidence and open decisions in `.sensecraft/<manifest-stem>.review.
|
|
|
38
38
|
- Prefer `codecraft-app.json`; otherwise use a single `codecraft-app.<slug>.json` with `manifest_version`, `identity`, and `sync`. Exclude `*.payload.json`, `*.patch.json`, and `*.materials.json`. Several candidates → ask which app. An explicit request for another app → use a separate slugged manifest, preserve the existing one.
|
|
39
39
|
- Also discover legacy `sensecraft-app.json` / `sensecraft-app.<slug>.json` with the same shape checks and transient exclusions. Migrate the chosen manifest to the corresponding `codecraft-app` filename, preserving its contents, especially `identity.app_id` and `sync`. Never overwrite an existing destination: resolve competing manifests first. Preserve old archive snapshots; carry forward any existing review/artifact notes and sync baseline. A filename change is not a new app.
|
|
40
40
|
- Preserve an invalid pre-create manifest in `.sensecraft/archive/` before rebuilding it from the template. Explain the fault and run `app list --mine --name "<app_name>"` before creating. If an app ID exists, preserve it and repair/resume that app.
|
|
41
|
-
- Run `sensecraft-cli auth info` before cloud reads. CodeCraft Hub requires Global and an active SenseCAP Access Key. If auth is missing, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md): `--site Global --no-wait`, show `verification_url` and end the turn, then `--device-code
|
|
41
|
+
- Run `sensecraft-cli auth info` before cloud reads. CodeCraft Hub requires Global and an active SenseCAP Access Key. If auth is missing, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md): `--site Global --no-wait`, show `verification_url` and end the turn, then `--device-code`. Do not run bare `auth init`. Do not invent account, scene, or catalog values before authentication succeeds.
|
|
42
42
|
|
|
43
43
|
## 2. Synthesize fields, deployment, and BOM
|
|
44
44
|
|
|
@@ -50,6 +50,43 @@ Read the applicable references in the table **before** doing each part. Build ev
|
|
|
50
50
|
|
|
51
51
|
**Deployment.** Read all of [tool-blocks.md](../references/tool-blocks.md), then map the complete first-time user journey to its supported blocks. For each action, record prerequisites, the chosen tool, verified config/artifact source, and the observable result. Inspect real artifact existence, target/architecture, build configuration, and required runtime inputs. A firmware file does not establish a model-deploy step; source code alone does not establish a flashable image. Place each tool directly after its instructions in a flat `deployment.blocks` array.
|
|
52
52
|
|
|
53
|
+
**Firmware / Muse / address (required before uploading or writing `flash-firmware`).** The CLI does **not** generate firmware. It tells you, for each Hub-supported device’s **default `flash_address`**, **what shape of binary to upload**. Run:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
sensecraft-cli firmware advise --list
|
|
57
|
+
sensecraft-cli firmware advise --device-id <SKU>
|
|
58
|
+
# or: sensecraft-cli firmware advise --name sticky
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Follow `rule` + `upload_guide` (`upload_what` / `do_not_upload` / recommended name / Muse flags). Same data is on `app blocks` → `flash-firmware.device_defaults` (offline) and [tool-blocks.md](../references/tool-blocks.md). **Pick the file that matches the default address — do not invent an address to match a random `.bin`.**
|
|
62
|
+
|
|
63
|
+
### A. Default address → what to upload
|
|
64
|
+
|
|
65
|
+
Resolve SKU via `app bom search` / BOM. Muse OFF unless the user explicitly wants Muse Gadget:
|
|
66
|
+
|
|
67
|
+
| Default `flash_address` | Upload this | Do **not** upload |
|
|
68
|
+
|-------------------------|-------------|-------------------|
|
|
69
|
+
| **`0x0`** (Watcher / Sticky / Indicator / IPS / 1.47 non-Muse; optional XIAO full image) | **Merged** `.bin` (bootloader + partitions + app) | App-only / SSCMA `application` package; `0x10000` bins |
|
|
70
|
+
| **`0x90000`** (E100x / XIAO e-paper) | **Application-region** `.bin` only | `0x0` merged whole-flash image |
|
|
71
|
+
| **`0x4000`** (Wio Terminal) | **Application-region** `.bin` | `0x0` image (overwrites UF2 bootloader) |
|
|
72
|
+
| **`0x10000`** (ordinary XIAO application package) | **Application** `.bin` (name/URL often contains `application`) | Merged `0x0` unless user asked for full image |
|
|
73
|
+
| **Muse Gadget** (user chooses Muse on a Muse SKU) | **`muse-gadget.bin` only** | Companion bootloader/partition files; writing `flash_address: "0x20000"` |
|
|
74
|
+
|
|
75
|
+
If Muse is requested: upload the device folder (`--type 4`) or `muse-gadget.bin`, set `muse_gadget: true`, `full_flash: false`, keep the **device default** address (not `0x20000`). If Muse is not requested on a Muse-capable SKU: upload the non-Muse row above and set `full_flash: true` (Sticky/Watcher/Indicator/1.47 **must** keep it true; E100x may set false only when intentional).
|
|
76
|
+
|
|
77
|
+
### B. Map the file you upload into config
|
|
78
|
+
|
|
79
|
+
| File you upload | Muse-capable SKU? | `muse_gadget` | `full_flash` | `flash_address` |
|
|
80
|
+
|-----------------|-------------------|---------------|--------------|-----------------|
|
|
81
|
+
| `muse-gadget.bin` / Muse SDK folder | yes | `true` | `false` | device default (**never** `0x20000`) |
|
|
82
|
+
| Merged image for `0x0` | yes / no | `false` | **`true` forced** on Sticky/Watcher/Indicator/1.47; else `false` | `0x0` |
|
|
83
|
+
| App-region bin for `0x90000` / `0x4000` | as SKU | `false` | `true` default on E100x (explicit `false` ok); else `false` | that offset |
|
|
84
|
+
| XIAO `application` package | no (ordinary XIAO) | `false` | `false` | `0x10000` |
|
|
85
|
+
|
|
86
|
+
Ambiguous single `.bin` → **ask once**: Muse Gadget or normal? Merged `0x0` or app-region? Prefer a **matched device folder** with `file upload --path <folder> --type 4 --checksum` and copy returned `muse.*`. Never store SDK tokens.
|
|
87
|
+
|
|
88
|
+
`app create` / `app update` **reject** with an explicit reason when: `device_id` is empty once the flash block has firmware/settings; `flash_mode` is `zip` on a non-ordinary-XIAO board; `muse_gadget` and the filename disagree (`muse-gadget.bin` ↔ Muse flag); `firmware_size` is implausible for the address (e.g. tiny bin at `0x0`, multi‑MiB dump at `0x90000`). Always copy upload `size` into `firmware_size`. Read the CLI error text and fix that field — do not retry the same payload.
|
|
89
|
+
|
|
53
90
|
Use available artifacts or a documented reproducible build when feasible within the user's scope. If an artifact, board variant, model, container version, or necessary action is unresolved, explain the specific gap and propose choices. Keep needed blocks in the local draft with pending values; never replace them with prose that pretends the deployment works. If no tool supports a required action, say so and agree on a supported path or an explicitly incomplete draft. Do not claim deployability until every required action has a usable path.
|
|
54
91
|
|
|
55
92
|
**BOM.** Follow [app-fields.md § Catalog verification](../references/app-fields.md#catalog-verification-before-authoring-a-bom). Identify devices and app-specific accessories from project evidence; exclude ordinary cables, computers, and generic tools by default. Query `app bom search --name "<product or SKU>"` for each catalog candidate, broadening the name if necessary. Match the exact variant. Copy returned `sku` to manifest row `id`, along with the returned name and purchase URL; derive quantity and a useful role note from the project. Do not use a catalog's internal `id` as the SKU.
|
|
@@ -60,7 +97,7 @@ Record the query and selected result in review notes. Multiple plausible variant
|
|
|
60
97
|
|
|
61
98
|
Present a concise project summary, proposed fields, activity candidates with a recommendation, deployment actions/tools, BOM matches, and actual gaps. Batch questions about consequential choices: name/language/audience when unclear, scene, clone/commercial permissions, activity choice (join which activity or none), hardware variant and BOM scope/quantity, assets, or an unsupported deployment path. Include a recommendation and why; reuse answers already in the conversation.
|
|
62
99
|
|
|
63
|
-
Ask only for uncertainty that affects correctness or the user's choice. Do not require an arbitrary one-round limit: a new material conflict can need a follow-up. Continue independent preparation while waiting, but do not commit guessed decisions or perform dependent uploads. Review is not an extra approval gate when the requested creation and all necessary decisions are already authorized.
|
|
100
|
+
Ask only for uncertainty that affects correctness or the user's choice. Hardware firmware Muse vs normal (when the binary is ambiguous) and exact board SKU/variant are consequential — ask rather than guess. Do not require an arbitrary one-round limit: a new material conflict can need a follow-up. Continue independent preparation while waiting, but do not commit guessed decisions or perform dependent uploads. Review is not an extra approval gate when the requested creation and all necessary decisions are already authorized.
|
|
64
101
|
|
|
65
102
|
## 4. Build the local manifest
|
|
66
103
|
|
|
@@ -92,7 +129,7 @@ Update the review notes with corrections, evidence, remaining gaps, and readines
|
|
|
92
129
|
|
|
93
130
|
## 6. Upload and create once
|
|
94
131
|
|
|
95
|
-
1. Read the upload references.
|
|
132
|
+
1. Read the upload references. Recheck auth/environment and that selected files still match their reviewed hashes. If auth is missing, use the split flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`. Upload only reviewed assets; reuse unchanged URLs. Images: `file upload --path <image> --type 1 --for-app`. Firmware: `--type 4`. Other artifacts: select the actual type/flags from the reference. App images use at most 16 JPG/JPEG/PNG/GIF/WebP files, each ≤5 MB; other artifacts are ≤100 MB.
|
|
96
133
|
|
|
97
134
|
For Muse Gadget, upload the application image built as `muse-gadget.bin` and linked at `0x20000`. Give each app its own requested name:
|
|
98
135
|
|
|
@@ -109,7 +146,7 @@ Update the review notes with corrections, evidence, remaining gaps, and readines
|
|
|
109
146
|
```
|
|
110
147
|
|
|
111
148
|
Exit code **1** means no complete token was found and this check passes. **0** means a token pattern was found: rebuild without the token and scan again. **2 or higher** is a path or read error to fix before retrying. Report only pass, match, or check error. Do not print matching values.
|
|
112
|
-
2. Write returned `file_url` values into the canonical manifest as each upload succeeds, keeping image order. Update the intended tool/media fields and the artifact ledger. For firmware fill `config.firmware_url`, `config.firmware_name`, and string `config.firmware_size` on the target block. Optional `file upload --name` only sets the name sent to the server. The server decides the stored object name, so a name specified for the upload is not necessarily the downloaded file name. `firmware_url` and every other stored URL must be the returned `file_url`. Do not build a URL from `--name` or from stdout `file_name`. Never expose temporary signed upload URLs in review prose.
|
|
149
|
+
2. Write returned `file_url` values into the canonical manifest as each upload succeeds, keeping image order. Update the intended tool/media fields and the artifact ledger. For firmware fill `config.firmware_url`, `config.firmware_name`, and string `config.firmware_size` on the target block. Optional `file upload --name` only sets the name sent to the server. The server decides the stored object name, so a name specified for the upload is not necessarily the downloaded file name. `firmware_url` and every other stored URL must be the returned `file_url`. Do not build a URL from `--name` or from stdout `file_name`. When the type-4 response includes `muse`, also copy `device_id`, `flash_address`, `muse_gadget`, and `full_flash` into that `flash-firmware` config (do not invent conflicting flags). Never expose temporary signed upload URLs in review prose.
|
|
113
150
|
3. Validate again, inspect the final projection, and reassess readiness. Required deployment inputs must now be filled unless the user chose an incomplete draft. Apply the [activity submission rules](../references/app-fields.md#activity-selection-during-app-authoring) when relevant and follow [manifest → CLI payload](references/manifest.md#manifest--cli-payload). Omit local bookkeeping; images become URLs with `pic_url = images[0]`; no images → omit both keys, never `images: []`. Never send `be_public` or `privacy`.
|
|
114
151
|
4. Write `.sensecraft/<manifest-stem>.payload.json`, then create **without `--yes`**:
|
|
115
152
|
```bash
|
|
@@ -118,7 +155,7 @@ Update the review notes with corrections, evidence, remaining gaps, and readines
|
|
|
118
155
|
Parse successful stdout for `app_id`, `console_url`, and `detail_url`. Record the ID and local UTC `created_at` immediately, before verification. On any ambiguous failure or missing ID/URLs, run `app list --mine --name "<app_name>"` before deciding whether creation happened; do not blindly retry. An internal follow-up save may fail after creating the app: recover that ID and resume by update.
|
|
119
156
|
5. Re-read `app view --id <app_id> --sketch` and `app bom list --id <app_id> --sketch`. Confirm stdout `view_kind` is `sketch`. Compare intended fields, image order, blocks/configs, and BOM rows, accounting for documented server normalization. For an app never published, the default `app view` returns only its name; `--sketch` reads the saved draft. Verify any requested activity association per the activity reference. A create response alone is not proof all sections saved. On a mismatch preserve the ID and report/repair through the update path.
|
|
120
157
|
6. Only after verification, advance `sync.last_pushed_*` using the manifest contract and snapshot. Delete only transient payloads created by this session after success; preserve prior files and failure evidence.
|
|
121
|
-
7. Report app name, ID, returned editor/detail links, counts, manifest revision/path, activity choice/result, and readiness. State **private draft (`be_public=0`)**; private and deployment-ready are separate facts. Missing cover affects publishing; missing tool inputs affect deployment. Tell the user to test flash on the **editor** (`console_url`); the bare `detail_url` preview may still show the empty published shell. Close the editor while CLI updates so auto-save cannot overwrite the sketch. Never claim the hardware was flashed or the app is public. Sketch vs published: [apps.md](../references/apps.md#sketch-vs-published-snapshots). Publish/unpublish/delete/clone use [apps.md](../references/apps.md).
|
|
158
|
+
7. Report app name, ID, returned editor/detail links, counts, manifest revision/path, activity choice/result, and readiness. State **private draft (`be_public=0`)**; private and deployment-ready are separate facts. Missing cover affects publishing; missing tool inputs affect deployment. Tell the user to test flash on the **editor** (`console_url`); the bare `detail_url` preview may still show the empty published shell. Close the editor while CLI updates so auto-save cannot overwrite the sketch. Never claim the hardware was flashed or the app is public. Sketch vs published: [apps.md](../references/apps.md#sketch-vs-published-snapshots). Publish/unpublish/delete/clone use [apps.md](../references/apps.md). If the user later asks to publish and a `flash-firmware` block exists, print the flash summary from [apps.md](../references/apps.md) (SKU / address / artifact / Muse / size) and get explicit acceptance before `app publish`.
|
|
122
159
|
|
|
123
160
|
## Existing app: update or resume
|
|
124
161
|
|
|
@@ -41,13 +41,62 @@ TOOL_CONFIG_FIELDS = {
|
|
|
41
41
|
FLASH_ADDRESSES = {"0x0", "0x4000", "0x10000", "0x90000"}
|
|
42
42
|
# Keep aligned with museDeviceTable (muse: true) and tool-blocks.md.
|
|
43
43
|
MUSE_GADGET_SKUS = {
|
|
44
|
-
"114993068", #
|
|
45
|
-
"113991315", "113991275", #
|
|
44
|
+
"114993068", "114993069", "114993070", "114993071", # Indicator D1 / D1S / D1L / D1Pro
|
|
45
|
+
"113991315", "113991275", "114993275", # Watcher (+ enclosure alias)
|
|
46
46
|
"100073581", # reTerminal E1001
|
|
47
47
|
"100017057", # reTerminal E1002
|
|
48
48
|
"100069905", # XIAO 1.47" Touch Display
|
|
49
49
|
"100056818", # reTerminal Sticky
|
|
50
50
|
}
|
|
51
|
+
# Fixed flash_address by SKU (matches CLI flashAddressBySKU.fixed / App address bar).
|
|
52
|
+
FLASH_ADDRESS_FIXED = {
|
|
53
|
+
"114993068": "0x0", "114993069": "0x0", "114993070": "0x0", "114993071": "0x0",
|
|
54
|
+
"113991315": "0x0", "113991275": "0x0", "114993275": "0x0",
|
|
55
|
+
"100073581": "0x90000",
|
|
56
|
+
"100017057": "0x90000",
|
|
57
|
+
"100069905": "0x0",
|
|
58
|
+
"100056818": "0x0",
|
|
59
|
+
"102991299": "0x4000",
|
|
60
|
+
"110061162": "0x0",
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def forces_full_flash_when_muse_off(device_id):
|
|
65
|
+
"""Sticky/Watcher/Indicator/1.47: only non-Muse address is 0x0 — full_flash locked on."""
|
|
66
|
+
if device_id not in MUSE_GADGET_SKUS:
|
|
67
|
+
return False
|
|
68
|
+
return FLASH_ADDRESS_FIXED.get(device_id) == "0x0"
|
|
69
|
+
XIAO_EE_DIY_RE = re.compile(r"(?i)\bee0[2-5]\b")
|
|
70
|
+
FLASH_MIN_MERGED_BYTES = 200 * 1024
|
|
71
|
+
FLASH_MAX_APP_REGION_BYTES = 4 * 1024 * 1024
|
|
72
|
+
XIAO_ZIP_SKUS = {"113991054", "113991254", "113991115"}
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def flash_address_from_material_name(name):
|
|
76
|
+
"""App hmiEspFlashProfile name rules when SKU is not in FLASH_ADDRESS_FIXED."""
|
|
77
|
+
n = (name or "").lower()
|
|
78
|
+
if not n:
|
|
79
|
+
return None
|
|
80
|
+
if "sticky" in n:
|
|
81
|
+
return "0x0"
|
|
82
|
+
if "sensecap" in n and "indicator" in n:
|
|
83
|
+
return "0x0"
|
|
84
|
+
if "watcher" in n and "xiao" not in n:
|
|
85
|
+
return "0x0"
|
|
86
|
+
if "wio" in n and "terminal" in n:
|
|
87
|
+
return "0x4000"
|
|
88
|
+
if "reterminal" in n and "sticky" not in n:
|
|
89
|
+
return "0x90000"
|
|
90
|
+
if "xiao" in n:
|
|
91
|
+
if "nrf" in n or "52840" in n:
|
|
92
|
+
return None
|
|
93
|
+
if "ips" in n or ("touch" in n and "display" in n and "esp32" in n):
|
|
94
|
+
return "0x0"
|
|
95
|
+
if "sense" in n or "watcher" in n or "trmnl" in n or "round" in n:
|
|
96
|
+
return None
|
|
97
|
+
if "display" in n or XIAO_EE_DIY_RE.search(n) or ("epaper" in n and "diy" in n):
|
|
98
|
+
return "0x90000"
|
|
99
|
+
return None
|
|
51
100
|
BOM_QUANTITY_MAX = 999
|
|
52
101
|
SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
|
|
53
102
|
QUANTITY_RE = re.compile(r"^[1-9][0-9]*$")
|
|
@@ -250,6 +299,31 @@ def main():
|
|
|
250
299
|
elif url is None:
|
|
251
300
|
warn(f"images[{i}] {p!r}: not uploaded yet (file_url null)")
|
|
252
301
|
|
|
302
|
+
materials_preview = m.get("bom", {}).get("materials", [])
|
|
303
|
+
material_name_by_id = {}
|
|
304
|
+
if isinstance(materials_preview, list):
|
|
305
|
+
for row in materials_preview:
|
|
306
|
+
if not isinstance(row, dict):
|
|
307
|
+
continue
|
|
308
|
+
mid = row.get("id") or row.get("sku")
|
|
309
|
+
if isinstance(mid, str) and mid.strip() and isinstance(row.get("name"), str):
|
|
310
|
+
material_name_by_id[mid.strip()] = row["name"]
|
|
311
|
+
|
|
312
|
+
def muse_capable(device_id):
|
|
313
|
+
if device_id in MUSE_GADGET_SKUS:
|
|
314
|
+
return True
|
|
315
|
+
name = (material_name_by_id.get(device_id) or "").lower()
|
|
316
|
+
if "sensecap" in name and "indicator" in name:
|
|
317
|
+
return True
|
|
318
|
+
if "watcher" in name and "xiao" not in name:
|
|
319
|
+
return True
|
|
320
|
+
return False
|
|
321
|
+
|
|
322
|
+
def fixed_flash_address(device_id):
|
|
323
|
+
if device_id in FLASH_ADDRESS_FIXED:
|
|
324
|
+
return FLASH_ADDRESS_FIXED[device_id]
|
|
325
|
+
return flash_address_from_material_name(material_name_by_id.get(device_id, ""))
|
|
326
|
+
|
|
253
327
|
blocks = m.get("deployment", {}).get("blocks", [])
|
|
254
328
|
if not isinstance(blocks, list):
|
|
255
329
|
vio("deployment.blocks must be an array")
|
|
@@ -293,10 +367,39 @@ def main():
|
|
|
293
367
|
elif block_type not in TEXT_BLOCK_TYPES:
|
|
294
368
|
vio(f"{label}: unsupported block type")
|
|
295
369
|
if block_type == "flash-firmware":
|
|
370
|
+
def flash_has_payload(c):
|
|
371
|
+
for key in (
|
|
372
|
+
"firmware_url", "firmware_name", "firmware_size", "flash_address", "flash_mode",
|
|
373
|
+
"project_zip_url", "project_zip_name", "project_zip_size", "device_type",
|
|
374
|
+
):
|
|
375
|
+
if isinstance(c.get(key), str) and c.get(key).strip():
|
|
376
|
+
return True
|
|
377
|
+
if "muse_gadget" in c or "full_flash" in c or "precheck_fields" in c:
|
|
378
|
+
return True
|
|
379
|
+
return False
|
|
380
|
+
|
|
296
381
|
if "device_id" in cfg and not isinstance(cfg["device_id"], str):
|
|
297
382
|
vio(f"{label}: config.device_id must be a SKU string")
|
|
298
|
-
|
|
299
|
-
|
|
383
|
+
device_id = cfg.get("device_id") if isinstance(cfg.get("device_id"), str) else ""
|
|
384
|
+
device_id = device_id.strip()
|
|
385
|
+
if not device_id and flash_has_payload(cfg):
|
|
386
|
+
vio(
|
|
387
|
+
f"{label}: config.device_id is required before create/update once flash-firmware has "
|
|
388
|
+
"firmware or flash settings. Resolve the material SKU with `sensecraft-cli app bom search` "
|
|
389
|
+
"or `app blocks` → flash-firmware.device_defaults. Empty config {{}} remains allowed as a pending scaffold"
|
|
390
|
+
)
|
|
391
|
+
elif not device_id:
|
|
392
|
+
warn(f"{label}: config.device_id is pending — resolve the exact device SKU before create/update")
|
|
393
|
+
elif device_id and flash_has_payload(cfg) and device_id not in FLASH_ADDRESS_FIXED and device_id not in XIAO_ZIP_SKUS:
|
|
394
|
+
# Ordinary XIAO zip SKUs are also in the Go hard table (non-fixed).
|
|
395
|
+
if fixed_flash_address(device_id) is None and not (material_name_by_id.get(device_id) or "").strip():
|
|
396
|
+
# XIAO C3/C6/Sense are known non-fixed SKUs; allow without materials.
|
|
397
|
+
if device_id not in {"113991054", "113991254", "113991115"}:
|
|
398
|
+
vio(
|
|
399
|
+
f"{label}: config.device_id {device_id!r} is not in flash-firmware.device_defaults and no "
|
|
400
|
+
"matching materials[].name was provided. Add a BOM row with that id/sku and the catalog "
|
|
401
|
+
"product name, or use a listed SKU from `app blocks`"
|
|
402
|
+
)
|
|
300
403
|
for key in ("device_type", "firmware_name", "project_zip_name", "flash_mode", "flash_address", "firmware_url", "project_zip_url"):
|
|
301
404
|
if key in cfg and not isinstance(cfg[key], str):
|
|
302
405
|
vio(f"{label}: config.{key} must be a string (empty is allowed for a pending value)")
|
|
@@ -304,28 +407,146 @@ def main():
|
|
|
304
407
|
if mode is None or mode == "":
|
|
305
408
|
warn(f"{label}: config.flash_mode is pending")
|
|
306
409
|
elif mode not in ("bin", "zip"):
|
|
307
|
-
vio(f"{label}: config.flash_mode must be bin or zip")
|
|
410
|
+
vio(f"{label}: config.flash_mode must be \"bin\" or \"zip\" (got {mode!r}); .hex is only for Grove Beginner file content")
|
|
308
411
|
else:
|
|
309
412
|
prefix = "firmware" if mode == "bin" else "project_zip"
|
|
310
413
|
if not cfg.get(prefix + "_url"):
|
|
311
414
|
warn(f"{label}: config.{prefix}_url is pending — deployment input incomplete")
|
|
415
|
+
if mode == "zip":
|
|
416
|
+
want_addr = fixed_flash_address(device_id)
|
|
417
|
+
if want_addr:
|
|
418
|
+
vio(
|
|
419
|
+
f"{label}: config.flash_mode \"zip\" rejected — device_id {device_id} only accepts a "
|
|
420
|
+
f"single .bin at {want_addr}. Set flash_mode to \"bin\". Zip is only for ordinary "
|
|
421
|
+
"XIAO ESP32 (C3/C6/S3 Sense, …)"
|
|
422
|
+
)
|
|
423
|
+
elif device_id and device_id not in XIAO_ZIP_SKUS and device_id not in FLASH_ADDRESS_FIXED:
|
|
424
|
+
vio(
|
|
425
|
+
f"{label}: config.flash_mode \"zip\" rejected — device_id {device_id!r} is not a "
|
|
426
|
+
"known ordinary XIAO zip target. Use flash_mode \"bin\", or set device_id to "
|
|
427
|
+
"113991054 / 113991254 / 113991115"
|
|
428
|
+
)
|
|
312
429
|
for size_key in ("firmware_size", "project_zip_size"):
|
|
313
430
|
if size_key in cfg and not isinstance(cfg[size_key], str):
|
|
314
431
|
vio(f"{label}: config.{size_key} must be a string")
|
|
315
432
|
elif cfg.get(size_key) and not QUANTITY_RE.fullmatch(cfg[size_key]):
|
|
316
433
|
vio(f"{label}: config.{size_key} must be a positive byte count string or pending empty string")
|
|
434
|
+
if mode == "bin" and cfg.get("firmware_url") and not cfg.get("firmware_size"):
|
|
435
|
+
vio(
|
|
436
|
+
f"{label}: config.firmware_size is required when config.firmware_url is set — copy numeric "
|
|
437
|
+
"`size` from the type-4 file upload response"
|
|
438
|
+
)
|
|
439
|
+
if mode == "zip" and cfg.get("project_zip_url") and not cfg.get("project_zip_size"):
|
|
440
|
+
vio(
|
|
441
|
+
f"{label}: config.project_zip_size is required when config.project_zip_url is set — copy "
|
|
442
|
+
"numeric `size` from the upload response"
|
|
443
|
+
)
|
|
317
444
|
address = cfg.get("flash_address")
|
|
318
445
|
if address is not None and address != "" and (not isinstance(address, str) or address not in FLASH_ADDRESSES):
|
|
319
|
-
vio(
|
|
446
|
+
vio(
|
|
447
|
+
f"{label}: unsupported config.flash_address {address!r} — allowed: 0x0, 0x4000, 0x10000, "
|
|
448
|
+
"0x90000 (never 0x20000; Muse app offset is applied by the site). See tool-blocks.md"
|
|
449
|
+
)
|
|
450
|
+
want_addr = fixed_flash_address(device_id)
|
|
451
|
+
if want_addr and isinstance(address, str) and address and address != want_addr:
|
|
452
|
+
vio(
|
|
453
|
+
f"{label}: config.flash_address {address!r} is unsafe for device_id {device_id} — this board "
|
|
454
|
+
f"is fixed at {want_addr}. Omit it for CLI default, or set {want_addr}"
|
|
455
|
+
)
|
|
456
|
+
if not address:
|
|
457
|
+
warn(f"{label}: config.flash_address is empty — CLI fills the device default on create/update; prefer writing it explicitly")
|
|
320
458
|
for key in ("muse_gadget", "full_flash"):
|
|
321
459
|
if key in cfg and type(cfg[key]) is not bool:
|
|
322
|
-
vio(f"{label}: config.{key} must be a JSON boolean")
|
|
460
|
+
vio(f"{label}: config.{key} must be a JSON boolean true/false, not a string or number")
|
|
323
461
|
if cfg.get("muse_gadget") is True and cfg.get("full_flash") is True:
|
|
324
|
-
vio(
|
|
462
|
+
vio(
|
|
463
|
+
f"{label}: config.full_flash must be false when config.muse_gadget is true — Muse uses a "
|
|
464
|
+
"multi-segment layout without erase-all"
|
|
465
|
+
)
|
|
325
466
|
elif cfg.get("muse_gadget") is True or cfg.get("full_flash") is True:
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
467
|
+
if not muse_capable(device_id):
|
|
468
|
+
vio(
|
|
469
|
+
f"{label}: config.muse_gadget/full_flash can be true only for Muse-capable SKUs "
|
|
470
|
+
f"(Indicator/Watcher/E1001/E1002/1.47 Touch/Sticky). device_id {device_id!r} is not in that set"
|
|
471
|
+
)
|
|
472
|
+
name = str(cfg.get("firmware_name") or "")
|
|
473
|
+
url = str(cfg.get("firmware_url") or "")
|
|
474
|
+
looks_muse = "muse-gadget" in (name + " " + url).lower()
|
|
475
|
+
if cfg.get("muse_gadget") is True:
|
|
476
|
+
if (name or url) and not looks_muse:
|
|
477
|
+
vio(
|
|
478
|
+
f"{label}: muse_gadget is true but firmware_url/firmware_name do not look like "
|
|
479
|
+
f"muse-gadget.bin (firmware_name={name!r}). Upload Muse SDK output as muse-gadget.bin, "
|
|
480
|
+
"or set muse_gadget false for a normal image"
|
|
481
|
+
)
|
|
482
|
+
elif (name or url) and looks_muse:
|
|
483
|
+
vio(
|
|
484
|
+
f"{label}: firmware looks like muse-gadget.bin but muse_gadget is false "
|
|
485
|
+
f"(firmware_name={name!r}). Set muse_gadget true and full_flash false on a Muse-capable SKU, "
|
|
486
|
+
"or upload a normal board image without \"muse-gadget\" in the name"
|
|
487
|
+
)
|
|
488
|
+
elif muse_capable(device_id) and cfg.get("muse_gadget") is not True:
|
|
489
|
+
if forces_full_flash_when_muse_off(device_id):
|
|
490
|
+
if cfg.get("full_flash") is False:
|
|
491
|
+
vio(
|
|
492
|
+
f"{label}: device_id {device_id} writes merged firmware at 0x0 — config.full_flash "
|
|
493
|
+
"must be true and cannot be turned off (CLI/App force it). Omit the field or set true"
|
|
494
|
+
)
|
|
495
|
+
elif "full_flash" not in cfg:
|
|
496
|
+
warn(
|
|
497
|
+
f"{label}: merged-at-0x0 Muse SKU with muse_gadget off should set full_flash true "
|
|
498
|
+
"(forced on create/update)"
|
|
499
|
+
)
|
|
500
|
+
elif "full_flash" not in cfg:
|
|
501
|
+
warn(
|
|
502
|
+
f"{label}: Muse SKU with muse_gadget off should set full_flash true "
|
|
503
|
+
"(CLI defaults it on create/update; E100x may set false explicitly)"
|
|
504
|
+
)
|
|
505
|
+
size_raw = cfg.get("firmware_size") if isinstance(cfg.get("firmware_size"), str) else ""
|
|
506
|
+
if mode == "bin" and size_raw and QUANTITY_RE.fullmatch(size_raw):
|
|
507
|
+
size = int(size_raw)
|
|
508
|
+
shape_addr = address if isinstance(address, str) and address else (want_addr or "")
|
|
509
|
+
display_name = name or "(unnamed)"
|
|
510
|
+
if cfg.get("muse_gadget") is True and size > FLASH_MAX_APP_REGION_BYTES:
|
|
511
|
+
vio(
|
|
512
|
+
f"{label}: firmware_size {size_raw} bytes ({display_name}) is too large for Muse "
|
|
513
|
+
"muse-gadget.bin (app segment). Rebuild the Muse app binary only, or disable Muse"
|
|
514
|
+
)
|
|
515
|
+
elif (
|
|
516
|
+
cfg.get("muse_gadget") is not True
|
|
517
|
+
and shape_addr == "0x0"
|
|
518
|
+
and device_id != "110061162"
|
|
519
|
+
and size < FLASH_MIN_MERGED_BYTES
|
|
520
|
+
):
|
|
521
|
+
vio(
|
|
522
|
+
f"{label}: firmware_size {size_raw} bytes ({display_name}) is too small for flash_address "
|
|
523
|
+
f"0x0 on device_id {device_id} — 0x0 expects a merged image (typically ≥ "
|
|
524
|
+
f"{FLASH_MIN_MERGED_BYTES} bytes). Rebuild a merge, or on ordinary XIAO use 0x10000 for an "
|
|
525
|
+
"application package"
|
|
526
|
+
)
|
|
527
|
+
elif (
|
|
528
|
+
cfg.get("muse_gadget") is not True
|
|
529
|
+
and shape_addr == "0x0"
|
|
530
|
+
and device_id != "110061162"
|
|
531
|
+
and want_addr == "0x0"
|
|
532
|
+
and "application" in (name + " " + url).lower()
|
|
533
|
+
):
|
|
534
|
+
vio(
|
|
535
|
+
f"{label}: firmware_url/firmware_name {display_name!r} looks like an application-only "
|
|
536
|
+
f"package, but device_id {device_id} flash_address 0x0 requires a merged image "
|
|
537
|
+
"(bootloader+partitions+app). Rebuild a merge; ordinary XIAO application packages use "
|
|
538
|
+
"0x10000 — not Watcher/Sticky/Indicator/IPS/1.47"
|
|
539
|
+
)
|
|
540
|
+
elif (
|
|
541
|
+
cfg.get("muse_gadget") is not True
|
|
542
|
+
and shape_addr in ("0x90000", "0x4000", "0x10000")
|
|
543
|
+
and size > FLASH_MAX_APP_REGION_BYTES
|
|
544
|
+
):
|
|
545
|
+
vio(
|
|
546
|
+
f"{label}: firmware_size {size_raw} bytes ({display_name}) is too large for flash_address "
|
|
547
|
+
f"{shape_addr} on device_id {device_id} — that offset expects an application-region .bin "
|
|
548
|
+
f"(typically ≤ {FLASH_MAX_APP_REGION_BYTES} bytes), not a whole-flash/merged image"
|
|
549
|
+
)
|
|
329
550
|
if block_type == "node-red":
|
|
330
551
|
if cfg.get("flow_data") is not None and not isinstance(cfg["flow_data"], (dict, list)):
|
|
331
552
|
vio(f"{label}: config.flow_data must be an object or array, not a JSON string")
|
|
@@ -26,7 +26,7 @@ List apps.
|
|
|
26
26
|
| `--name` | | Search keyword → API `app_name` (Console app list) |
|
|
27
27
|
| `--scene` | | Scene id |
|
|
28
28
|
| `--uniform-type` | | Device type → API `uniform_type` (`40` reCamera, `32` XIAO ESP32S3, `53` reCamera Pro) |
|
|
29
|
-
| `--sort` | | `popular
|
|
29
|
+
| `--sort` | | `popular`, `newest`, or `likes` → `sort_by`. Omit to leave the API unordered |
|
|
30
30
|
| `--priority-activity-id` | | Positive integer. Only with `--sort popular`. If omitted on popular, CLI fills the first ongoing activity |
|
|
31
31
|
| `--mark-type` | | `1` = my likes, `0` = my collections |
|
|
32
32
|
| `--likes` | | `mark_type=1` and `be_public=1`. Not with `--mine` |
|
|
@@ -120,6 +120,16 @@ sensecraft-cli app delete --id <app_id> --yes # private only (be_public=0)
|
|
|
120
120
|
|
|
121
121
|
`app publish` matches Console 「发布确认」: show https://sensecraft.seeed.cc/legal/en/declaration and warn that review locks editing until approval or `app withdraw`; only then pass `--agree-declaration --yes`. Missing either flag → non-zero. API body is still only `{app_id, privacy:2}` (agreement is client-side, like Console `warrantyAccepted`). stdout includes `detail_url`: `https://codecraft.seeed.cc/hub/view-application/<id>-<slug>`. Give the user that URL as printed. Do not include `console_url` or `/application/edit`. Do not append `from`, `section`, `state`, or `tab`. Do **not** invent `/application/detail/<id>`.
|
|
122
122
|
|
|
123
|
+
**Before asking for publish confirmation**, if the sketch has a `flash-firmware` block, print a one-screen flash summary from `app view --id … --sketch` and wait for the user to accept it:
|
|
124
|
+
|
|
125
|
+
- `device_id` (SKU) + board name if known
|
|
126
|
+
- `flash_address` + expected artifact (`0x0` merged / `0x90000|0x4000|0x10000` app-region / Muse `muse-gadget.bin`)
|
|
127
|
+
- `muse_gadget` / `full_flash`
|
|
128
|
+
- `firmware_name` + `firmware_size` (must match the type-4 upload `size`)
|
|
129
|
+
- reminder: CLI does not flash hardware; user tests in the editor
|
|
130
|
+
|
|
131
|
+
If any field looks wrong, fix the sketch with `app update` first — do not publish a bad flash block.
|
|
132
|
+
|
|
123
133
|
**Never** send `privacy=1` (ops-approved public). After editing a **published** app, tell the user plaza is unchanged until they confirm `app publish --agree-declaration --yes`.
|
|
124
134
|
|
|
125
135
|
### BOM
|
|
@@ -30,8 +30,8 @@ With no split flags, in a terminal:
|
|
|
30
30
|
1. Select site: Global (International) or China. China supports SenseCraft Data only. SenseCraft AI and CodeCraft Hub require Global.
|
|
31
31
|
2. Request a device authorization code and show the verification URL/code.
|
|
32
32
|
3. Wait for the user to approve in the browser; the CLI polls automatically.
|
|
33
|
-
4. Resolve
|
|
34
|
-
5. Save to local config and set
|
|
33
|
+
4. Resolve account/organization, then select an existing Access Key or create one with a label and permission level.
|
|
34
|
+
5. Save to local config and set as active profile.
|
|
35
35
|
|
|
36
36
|
### Split flow
|
|
37
37
|
|
|
@@ -42,10 +42,13 @@ sensecraft-cli file upload --path ./model.rknn --type 2 --checksum --unlinked
|
|
|
42
42
|
sensecraft-cli file upload --path ./model.rknn --model-id <model_id> --yes
|
|
43
43
|
sensecraft-cli file upload --path ./application.zip --type 3 --checksum
|
|
44
44
|
sensecraft-cli file upload --path ./firmware.bin --type 4 --checksum
|
|
45
|
+
sensecraft-cli file upload --path ./reterminal-e1001 --type 4 --checksum
|
|
45
46
|
sensecraft-cli file upload --path ./manual.pdf --type 5 --flow-id <flow_id>
|
|
46
47
|
sensecraft-cli file upload --path ./dataset.zip --type 6 --checksum
|
|
47
48
|
```
|
|
48
49
|
|
|
50
|
+
Type 4 may accept a matched device folder (Muse SDK slug or display name). Success JSON can include `muse` with `device_id`, `flash_address`, `muse_gadget`, `full_flash`, and a `note` for the flash-firmware block. See [files.md](files.md).
|
|
51
|
+
|
|
49
52
|
Output:
|
|
50
53
|
|
|
51
54
|
Unlinked (`--unlinked` / `--for-app`) output includes `"attached": false` and `hint`. Attached model output:
|
|
@@ -44,7 +44,10 @@ sensecraft-cli file upload --path ./demo.png --type 1 --unlinked
|
|
|
44
44
|
sensecraft-cli model upload --path ./model.rknn --unlinked
|
|
45
45
|
|
|
46
46
|
# Firmware, static resource, and archive (no model/app attach)
|
|
47
|
-
sensecraft-cli file upload --path ./firmware.bin --type 4 --checksum
|
|
47
|
+
sensecraft-cli file upload --path ./firmware.bin --type 4 --checksum --device-id 100073581
|
|
48
|
+
# Muse SDK / device folder: uploads muse-gadget.bin (or the single app bin) and returns muse hints
|
|
49
|
+
sensecraft-cli file upload --path ./reterminal-e1001 --type 4 --checksum
|
|
50
|
+
sensecraft-cli file upload --path ./sensecap-watcher --type 4 --checksum
|
|
48
51
|
sensecraft-cli file upload --path ./guide.pdf --type 5 --flow-id <flow_id>
|
|
49
52
|
sensecraft-cli file upload --path ./dataset.zip --type 6 --checksum
|
|
50
53
|
|
|
@@ -55,6 +58,24 @@ sensecraft-cli file upload --path ./fixture.bin --type 2 --checksum --unlinked -
|
|
|
55
58
|
Success JSON contains `file_name`, `file_type`, `file_url`, `size`, optional `checksum`, and `attached`. `file_url` is the access link, and the object name in it is the name the server stored. `file_name` is the name sent with `--name` or the local base name; it is not necessarily the downloaded file name.
|
|
56
59
|
When attached to a model it also includes `model_id`, `previous_version`, `version`. Explicit `--unlinked` / `--for-app` sets `attached: false` and a `hint`.
|
|
57
60
|
|
|
61
|
+
### Type 4 firmware (`muse` in the response)
|
|
62
|
+
|
|
63
|
+
Matched folder names (Muse SDK slugs or display names like `E1001设备`) select the board. A **bare** `.bin` should pass `--device-id <SKU>` so the same hints are returned. The JSON may include `muse`:
|
|
64
|
+
|
|
65
|
+
| Situation | Upload | Write into `flash-firmware` config |
|
|
66
|
+
|-----------|--------|------------------------------------|
|
|
67
|
+
| Muse SDK folder with `muse-gadget.bin` | Only that file; companions ignored | `muse_gadget: true`, `full_flash: false`, device default `flash_address` (not `0x20000`) |
|
|
68
|
+
| Muse-capable board + normal app/merged bin | That one firmware file | `muse_gadget: false`, **`full_flash: true`** (forced on Sticky/Watcher/Indicator/1.47; default on E100x) |
|
|
69
|
+
| Wio / Grove / non-Muse | That one firmware file | `muse_gadget: false`, `full_flash: false` |
|
|
70
|
+
| Bare file + `--device-id` | That file | Same as above from the SKU; also `build_artifact` |
|
|
71
|
+
| Bare file **without** `--device-id` | That file | `muse.note` only — incomplete; re-run with `--device-id` or a matched folder |
|
|
72
|
+
|
|
73
|
+
Also copy upload `size` into `config.firmware_size`. Device defaults: `sensecraft-cli app blocks` → `flash-firmware.device_defaults`, or [tool-blocks.md](tool-blocks.md). E100x uses application-region bin at `0x90000` only (no `0x0`); Watcher/Sticky/Indicator/1.47 use merged bin at `0x0` only (no `0x10000`, and `*application*` filenames are rejected on upload/create); Wio uses `0x4000` only (no `0x0`). Conflicting `--device-id` vs folder match is rejected with a clear reason.
|
|
74
|
+
|
|
75
|
+
For non-Muse boards whose default address is `0x0`, `muse.note` always includes: **upload a merged `.bin`**. A file that is far too small for a merge (under ~200 KiB) is **rejected before OSS** with that reason (Grove Beginner `.hex`/`.bin` is exempt).
|
|
76
|
+
|
|
77
|
+
Before uploading, Agents should run `sensecraft-cli firmware advise --device-id <SKU>` (or `--list`) and follow `upload_guide` / `rule` (also on `app blocks` → `device_defaults`). CLI does not compile firmware.
|
|
78
|
+
|
|
58
79
|
## Model shortcut
|
|
59
80
|
|
|
60
81
|
For model artifacts, this wrapper fixes `type=2` and enables checksum. Pass `--id` to attach and bump version:
|
|
@@ -66,27 +66,27 @@ Write every field below inside **`block.config`**. Keep `id` and `type` on the b
|
|
|
66
66
|
|-------|----------------|
|
|
67
67
|
| `device_id` | Material SKU string, e.g. `"100017057"`, matching the BOM row's SKU in `id`. Not a production type (`"29"`) or an internal catalog product id |
|
|
68
68
|
| `device_type` | `uniform_type` string. Use `""` when the board has none (Wio / Grove may) |
|
|
69
|
-
| `flash_mode` | `"bin"` when a firmware URL is set. `"zip"` for
|
|
69
|
+
| `flash_mode` | `"bin"` when a firmware URL is set. `"zip"` only for ordinary XIAO ESP32 (C3/C6/S3 Sense, …). E100x / Wio / Watcher / Sticky / Indicator / e-paper / IPS / Grove → **bin only** (CLI rejects zip with a reason) |
|
|
70
70
|
| `firmware_url` / `firmware_name` / `firmware_size` | Bin mode. `firmware_size` is a string, not a number. Empty `firmware_name` is filled from the URL by the editor |
|
|
71
|
-
| `flash_address` | Only `"0x0"`, `"0x4000"`, `"0x10000"`, `"0x90000"`.
|
|
71
|
+
| `flash_address` | Only `"0x0"`, `"0x4000"`, `"0x10000"`, `"0x90000"`. Prefer the device default below. Omit it and `app create` / `app update` fill the default. Ordinary XIAO: URL/name containing `application` → `0x10000`. Fixed-address SKUs **reject** any other address on create/update: E100x `0x90000` (no `0x0`), Wio `0x4000` (no `0x0`), Watcher/Sticky/Indicator/1.47" `0x0` (no `0x10000`). Do not upload an `*application*` package to those merged-at-`0x0` boards. Do not write `0x20000` here |
|
|
72
72
|
| `project_zip_url` / `project_zip_name` / `project_zip_size` / `precheck_fields` | Zip mode only. Sizes are strings. `precheck_fields` is `[{ key, name, info, type, default }]` from `sensecraft_config.h`, or omit / `[]` |
|
|
73
73
|
| `muse_gadget` | JSON boolean, default `false`; write `true`/`false`, never strings or numbers. Some read paths coerce non-booleans by truthiness, so `"false"` can enable the option. `true` shows the Muse SDK token input under the flash button in preview |
|
|
74
|
-
| `full_flash` | JSON boolean
|
|
74
|
+
| `full_flash` | JSON boolean. Kept only on the Muse SKUs below; any other device is reset to `false`. `true` erases the whole flash before the write. When `muse_gadget` is `true`, set `full_flash` to `false` (CLI coerces it). When `muse_gadget` is `false` on a Muse SKU and `full_flash` is omitted, CLI defaults it to `true`. **Sticky / Watcher / Indicator / XIAO 1.47"** (fixed `0x0` merged firmware): `full_flash` is **forced `true`** and cannot be turned off (CLI coerces explicit `false`; App locks the checkbox). **E1001 / E1002** (fixed `0x90000`): explicit `false` is still kept. The editor hides the checkbox while Muse is on |
|
|
75
75
|
|
|
76
76
|
`muse_gadget: true` is kept only for these SKUs. The CLI and `validate_manifest.py` reject `muse_gadget: true` or `full_flash: true` for any other `device_id`. The editor resets those flags to `false` when the document is opened. `full_flash` uses the same SKU list:
|
|
77
77
|
|
|
78
78
|
| Device | `device_id` (SKU) |
|
|
79
79
|
|--------|-------------------|
|
|
80
|
-
| SenseCAP Indicator D1 / D1S / D1L / D1Pro | `114993068` (aliases
|
|
81
|
-
| SenseCAP Watcher | `113991315` or `113991275` |
|
|
80
|
+
| SenseCAP Indicator D1 / D1S / D1L / D1Pro | `114993068` (aliases `114993069` D1S, `114993071` D1Pro kept) |
|
|
81
|
+
| SenseCAP Watcher | `113991315` or `113991275` (enclosure alias `114993275`) |
|
|
82
82
|
| reTerminal E1001 | `100073581` |
|
|
83
83
|
| reTerminal E1002 | `100017057` |
|
|
84
84
|
| XIAO 1.47" Touch Display | `100069905` |
|
|
85
85
|
| reTerminal Sticky | `100056818` |
|
|
86
86
|
|
|
87
|
-
When `muse_gadget` is `true`, set `full_flash` to `false`. The editor hides that checkbox until Muse is turned off. `firmware_url` must be the Muse application image linked at `0x20000`. The local build product is usually `muse-gadget.bin`; the name stored by the server does not have to stay that name. Upload it with `file upload --path <build-dir>/muse-gadget.bin --type 4 --name <project>-muse-gadget.bin`, and set `firmware_url` to the returned `file_url`. A binary linked at `0x90000` or `0x10000` will not boot. Checking the box does not change `flash_address
|
|
87
|
+
When `muse_gadget` is `true`, set `full_flash` to `false`. The editor hides that checkbox until Muse is turned off. `firmware_url` must be the Muse application image linked at `0x20000`. The local build product is usually `muse-gadget.bin`; the name stored by the server does not have to stay that name. `firmware_url` or `firmware_name` should still contain `muse-gadget` so the CLI can recognize the image. Upload it with `file upload --path <build-dir>/muse-gadget.bin --type 4 --name <project>-muse-gadget.bin`, and set `firmware_url` to the returned `file_url`. A binary linked at `0x90000` or `0x10000` will not boot. **Reverse check:** if the name or URL contains `muse-gadget` but `muse_gadget` is `false`, the CLI rejects create/update — either enable Muse on a Muse SKU or upload a normal board image under a different name. Checking the box does not change `flash_address` (and the address bar is hidden): E100x stays `0x90000`, Watcher / Sticky / Indicator / 1.47" Touch stay `0x0`. Type-4 folder upload of a Muse SDK directory returns these fields under `muse` in the JSON. `device_id` is required once the block has firmware/flash settings (empty `{}` scaffold is still allowed).
|
|
88
88
|
|
|
89
|
-
`full_flash: true` with `muse_gadget: false` is
|
|
89
|
+
`full_flash: true` with `muse_gadget: false` is required when writing a normal image after a multi-segment layout (and is the CLI/app default when Muse is off). E1001 / E1002 then also rewrite the stock bootloader at `0x0` and the partition table at `0x8000`; the app stays at `0x90000`. Indicator, 1.47" Touch, Sticky, and Watcher non-Muse images are merged at `0x0`, so the flag only turns on erase-all — and those four boards **lock** `full_flash` on. Do not put the reTerminal stock bootloader into those images, and do not put it into a Muse image.
|
|
90
90
|
|
|
91
91
|
Do **not** write an SDK token (`mgst_…`), `flash_target`, `flash_address_adapted`, or the bootloader, partition table, OTA, and PHY addresses and files. The app site supplies those. A token stays in the browser session. Watcher fills `flash_target` with `"xiao"` on open; do not write `"himax"`.
|
|
92
92
|
|
|
@@ -106,21 +106,44 @@ Unchecked `muse_gadget` keeps the single-file device table below and does not re
|
|
|
106
106
|
| XIAO ESP32C3 | `113991054` | `bin` or `zip` | URL contains `application` → `0x10000`, otherwise `0x0` | `.bin` or zip |
|
|
107
107
|
| XIAO ESP32C6 / S3 / S3 Plus | matching SKU (`material.device_id` empty; row comes from `app_block_options`) | same as C3 | same as C3 | same as C3 |
|
|
108
108
|
| XIAO ESP32S3 Sense | `113991115` | same as C3 | same as C3 | same as C3 |
|
|
109
|
-
| SenseCAP Watcher | `113991315` or `113991275` (one group) | `bin` |
|
|
110
|
-
| Wio Terminal | `102991299` | `bin` |
|
|
109
|
+
| SenseCAP Watcher | `113991315` or `113991275` (one group) | `bin` | **`0x0` only** (merged firmware; **do not** write `0x10000`) | `merged-binary.bin`: bootloader at `0x0`, partition table at `0x8000`, app at `0x10000` |
|
|
110
|
+
| Wio Terminal | `102991299` | `bin` | **`0x4000` only** (**do not** write `0x0`; bootloader via UF2/J-Link) | application-region `.bin` |
|
|
111
111
|
| Grove Beginner Kit | `110061162` | `bin` | `0x0` (address bar hidden; `.hex` uses addresses inside the file) | `.bin` or `.hex`. `.hex` locks the board to this kit |
|
|
112
|
-
| XIAO 0.96" / 1.14" IPS, 1.47" Touch (ESP32-S3) |
|
|
113
|
-
| reTerminal E1001 | `100073581` | `bin` |
|
|
114
|
-
| reTerminal E1002 | `100017057` | `bin` |
|
|
115
|
-
| XIAO e-paper / EE02–EE05 DIY (name contains Display, and is not IPS / Round / Touch / Sense) | matching SKU | `bin` |
|
|
116
|
-
| reTerminal Sticky | `100056818` | `bin` |
|
|
117
|
-
| SenseCAP Indicator D1 / D1S / D1L / D1Pro | one group; example `114993068` (D1) | `bin` |
|
|
112
|
+
| XIAO 0.96" / 1.14" IPS, 1.47" Touch (ESP32-S3) | IPS by material **name**; 1.47" Touch Muse SKU is `100069905` | `bin` | **`0x0` only** (merged; Muse hides the address bar) | merged `.bin`. nRF52840 variants cannot be flashed. Include the BOM material `name` so CLI can apply this rule |
|
|
113
|
+
| reTerminal E1001 | `100073581` | `bin` | **`0x90000` only** (**do not** write `0x0`; restore bootloader via `full_flash`) | application-region `.bin`, not a full image with a bootloader |
|
|
114
|
+
| reTerminal E1002 | `100017057` | `bin` | **`0x90000` only** (same) | same as E1001 |
|
|
115
|
+
| XIAO e-paper / EE02–EE05 DIY (name contains Display, and is not IPS / Round / Touch / Sense) | matching SKU + material **name** | `bin` | **`0x90000` only** | same as E1001. Include BOM material `name` so CLI coerces address |
|
|
116
|
+
| reTerminal Sticky | `100056818` | `bin` | **`0x0` only** (merged; Muse hides the address bar) | merged `.bin` |
|
|
117
|
+
| SenseCAP Indicator D1 / D1S / D1L / D1Pro | one group; example `114993068` (D1) | `bin` | **`0x0` only** (merged; Muse hides the address bar) | merged ESP32-S3 `.bin`, not the RP2040 port |
|
|
118
118
|
|
|
119
|
-
A SenseCAP Watcher project that is not joining an activity uploads `merged-binary.bin` at `0x0`. Build it from the same `flash_args` (`0x0` bootloader, `0x8000` partition table, `0x10000` app). Leave out the app-only `.bin`, `bootloader.bin`, and `partition-table.bin`. The file name and URL must not contain `application`; that word moves the write to `0x10000`.
|
|
119
|
+
A SenseCAP Watcher project that is not joining an activity uploads `merged-binary.bin` at `0x0`. Build it from the same `flash_args` (`0x0` bootloader, `0x8000` partition table, `0x10000` app). Leave out the app-only `.bin`, `bootloader.bin`, and `partition-table.bin`. The file name and URL must not contain `application`; that word moves the write to `0x10000`.
|
|
120
120
|
|
|
121
|
-
`.hex` is only for Grove Beginner (`110061162`). E100x, e-paper, Sticky, IPS, Touch, and Indicator accept `.bin` only. Do not use zip for Grove, Wio, those screens, or Indicator. XIAO
|
|
121
|
+
`.hex` is only for Grove Beginner (`110061162`). E100x, e-paper, Sticky, IPS, Touch, and Indicator accept `.bin` only. Do not use zip for Grove, Wio, those screens, or Indicator. Ordinary XIAO still allows `0x0` / `0x10000`. Watcher / Sticky / IPS / Indicator non-Muse images are merged at `0x0` only — do not reuse the XIAO `application` → `0x10000` rule on them. XIAO C3 / C6 / S3 / S3 Sense / S3 Plus keep 115200 and `flashSize` / `flashMode` / `flashFreq` = `keep`.
|
|
122
122
|
|
|
123
|
-
|
|
123
|
+
### Upload the binary that matches the default address
|
|
124
|
+
|
|
125
|
+
CLI does **not** generate firmware. It guides **what to upload** for each supported device’s default `flash_address`.
|
|
126
|
+
|
|
127
|
+
**Required first step for Agents:**
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
sensecraft-cli firmware advise --list
|
|
131
|
+
sensecraft-cli firmware advise --device-id <SKU>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Use JSON `rule` + `upload_guide` (`upload_what` / `do_not_upload`). Same rows are on `app blocks` → `flash-firmware.device_defaults` (no Access Key) and in `build_recipe`.
|
|
135
|
+
|
|
136
|
+
| Default `flash_address` | Upload | Typical boards |
|
|
137
|
+
|-------------------------|--------|----------------|
|
|
138
|
+
| `0x0` | **Merged** image (bootloader + table + app) | Watcher, Sticky, Indicator, IPS, 1.47" (non-Muse); optional full XIAO image |
|
|
139
|
+
| `0x90000` | **App-region only** `.bin` (no bootloader in the file) | E1001 / E1002, XIAO e-paper |
|
|
140
|
+
| `0x4000` | **App-region** `.bin` | Wio Terminal |
|
|
141
|
+
| `0x10000` | **Application package** `.bin` (often `*application*`) | Ordinary XIAO C3/C6/S3 when not shipping a merge |
|
|
142
|
+
| Muse path | **`muse-gadget.bin` only**; keep device default address in config | Muse-capable SKUs; app site writes app at `0x20000` |
|
|
143
|
+
|
|
144
|
+
CLI rejects implausible `firmware_size` when present: `0x0` merge typically ≥ 200 KiB; app-region / Muse typically ≤ 4 MiB. Copy `size` from `file upload`.
|
|
145
|
+
|
|
146
|
+
**Agent:** choose SKU → `firmware advise` → obtain a file matching `upload_guide` → upload → write `device_id` / `flash_address` / Muse flags / `firmware_size`. **Do not** claim the firmware was flashed. Serial flashing stays L3.
|
|
124
147
|
|
|
125
148
|
### `deploy-ai-model` (vision / audio / related)
|
|
126
149
|
|