@seeed-studio/sensecraft-cli 0.4.7 → 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 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.zh.md](README.zh.md).
5
+ Chinese: [README-zh.md](README-zh.md).
6
6
 
7
7
  ## Install
8
8
 
@@ -43,7 +43,7 @@ async function main() {
43
43
  await runInstall();
44
44
  } catch (err) {
45
45
  console.error('');
46
- console.error('Install failed:', err.message);
46
+ console.error('安装失败:', err.message);
47
47
  console.error('');
48
48
  process.exit(1);
49
49
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seeed-studio/sensecraft-cli",
3
- "version": "0.4.7",
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.zh.md",
29
+ "README-zh.md",
30
30
  "INSTALL.md"
31
31
  ],
32
32
  "os": [
@@ -27,7 +27,7 @@ function getGlobalCliPath() {
27
27
 
28
28
  function installGlobally() {
29
29
  const packageRoot = getPackageRoot();
30
- console.log('Installing sensecraft-cli globally...');
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(`Global command not found: ${cliPath}. Add the npm global bin directory to PATH.`);
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('Config file already exists; skipped initialization');
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('No interactive terminal; skipped automatic initialization.');
54
- console.log('Run later: sensecraft-cli auth init');
53
+ console.log('未检测到交互式终端,已跳过自动初始化。');
54
+ console.log('请稍后运行: sensecraft-cli auth init');
55
55
  return;
56
56
  }
57
57
 
58
58
  console.log('');
59
- console.log('No config file found; starting initialization...');
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('Install complete');
80
- console.log(' Command: sensecraft-cli');
81
- console.log(` Path: ${globalCliPath}`);
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('If sensecraft-cli is not on PATH, add this directory:');
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. **Success = indented JSON on stdout** for business commands and the split `auth init` flow. The interactive wizard prints human-readable text. Failure = stderr + non-zero exit. Parse stdout only on success.
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` after the user authorizes. Do not run bare `auth init`. Do not invent account, scene, or catalog values before authentication succeeds.
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. Run `sensecraft-cli auth info`. If no Access Key is active, use the split `auth init` flow in [`../SKILL.md`](../SKILL.md). Do not run bare `auth init`. Recheck the environment and that selected files still match their reviewed hashes. 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.
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 may rewrite part of that name for security, so `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", # SenseCAP Indicator
45
- "113991315", "113991275", # SenseCAP Watcher
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
- elif not cfg.get("device_id"):
299
- warn(f"{label}: config.device_id is pending — resolve the exact device SKU")
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(f"{label}: unsupported config.flash_address; read tool-blocks.md for device defaults")
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(f"{label}: config.full_flash must be false when config.muse_gadget is true")
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
- device_id = cfg.get("device_id")
327
- if not isinstance(device_id, str) or device_id.strip() not in MUSE_GADGET_SKUS:
328
- vio(f"{label}: config.muse_gadget and config.full_flash can be true only for a Muse device SKU")
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")
@@ -62,7 +62,7 @@ Formats JPG/JPEG/PNG/GIF/WebP, ≤ 5 MB each, prefer 4:3. SVG is rejected by the
62
62
 
63
63
  ## `deployment.blocks`
64
64
 
65
- Flat ordered array, copied through to the payload unchanged. Blocks before the first `step` = introduction; each `step` starts a deploy step. Read [../../references/tool-blocks.md](../../references/tool-blocks.md) before selecting or configuring tools. After `file upload --type 4`, write `config.firmware_url`, `config.firmware_name`, and string `config.firmware_size` inside the `flash-firmware` block. Every tool uses one nested `config` object. Do not repeat those fields on the block. A needed block with missing inputs may stay in a local draft, but the app is not deployment-ready until those inputs have a usable path; mark gaps in review notes rather than inventing URLs or IDs.
65
+ Flat ordered array, copied through to the payload unchanged. Blocks before the first `step` = introduction; each `step` starts a deploy step. Read [../../references/tool-blocks.md](../../references/tool-blocks.md) before selecting or configuring tools. After `file upload --type 4`, write `config.firmware_url`, `config.firmware_name`, and string `config.firmware_size` inside the `flash-firmware` block. `firmware_url` is the returned `file_url`. The object name in that URL is the name used to download the file; the name specified for the upload is not necessarily that name. Every tool uses one nested `config` object. Do not repeat those fields on the block. A needed block with missing inputs may stay in a local draft, but the app is not deployment-ready until those inputs have a usable path; mark gaps in review notes rather than inventing URLs or IDs.
66
66
 
67
67
  ## `bom.materials`
68
68
 
@@ -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` → `order_type=1`, `newest` → `2`, `likes` → `3`. Omit to leave `order_type` unset |
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 the account and organization, then select an existing Access Key or create one with a label and permission level.
34
- 5. Save to local config and set it as the active profile.
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
 
@@ -32,7 +32,7 @@ Acquires an OSS POST policy, uploads the local file with multipart/form-data, an
32
32
 
33
33
  `--model-id` and `--app-id` are mutually exclusive. Types `1`/`2` without attach/`--for-app`/`--unlinked` exit non-zero **before** the OSS POST (`ErrAttachRequired`). Types `3`–`6` upload directly. Type `5` without `--flow-id` exits before acquire.
34
34
 
35
- `--name` is only the name sent with the upload. The server may rewrite part of that name for security. Use the returned `file_url` as the access link. Do not build a URL from `--name` or from the printed `file_name`; that name may not be the object that can be opened. stdout `file_name` echoes the name sent, not a name read back from the cloud.
35
+ `--name` is only the name sent with the upload. The filename used to access or download the file is the object name in the returned `file_url`. A name specified for the upload is not necessarily that download name. stdout `file_name` echoes the name sent, not a name read back from the server. Do not build a URL from `--name` or from the printed `file_name`.
36
36
 
37
37
  ```bash
38
38
  sensecraft-cli file upload --path ./cover.png --type 1 --for-app
@@ -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:
@@ -23,7 +23,7 @@ Auth: **Access Key**. The China site supports SenseCraft Data only; file upload
23
23
  7. Do not pass oversized files or more than 16 app image URLs; CLI rejects them before upload/update.
24
24
  8. Types `3`–`6` have no model/app attach path and upload directly (no `--unlinked` needed).
25
25
  9. **Security gates**: empty (0 B) files rejected; type 2–6 ≤ **100 MB**; every image ≤ **5 MB**. The CLI does not count uploads. A rate limit comes back as `11209` or `11210`.
26
- 10. **Use the returned access link.** Optional `--name` is the `file_name` sent to the server. The server may rewrite part of that name for security. Put the returned `file_url` into the app or model payload. Do not build a URL from `--name`, the local file name, or stdout `file_name`.
26
+ 10. **The access name is the server's.** Optional `--name` is the `file_name` sent to the server. The filename used to open or download the file is the object name in the returned `file_url`. A name specified for the upload is not necessarily that download name. Put the returned `file_url` into the app or model payload. Do not build a URL from `--name`, the local file name, or stdout `file_name`.
27
27
 
28
28
  ## Examples
29
29
 
@@ -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
 
@@ -52,9 +55,27 @@ sensecraft-cli file upload --path ./dataset.zip --type 6 --checksum
52
55
  sensecraft-cli file upload --path ./fixture.bin --type 2 --checksum --unlinked --sandbox
53
56
  ```
54
57
 
55
- Success JSON contains `file_name`, `file_type`, `file_url`, `size`, optional `checksum`, and `attached`. `file_url` is the access link. `file_name` is the name sent with `--name` or the local base name; the server may store the object under a different name.
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 a project zip |
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"`. Use the device default below. The editor resets a non-default address the first time the doc is opened. Do not write `0x20000` here |
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, default `false`. 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`. The editor hides the checkbox while Muse is on |
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 on the same row are kept) |
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 point to the Muse Gadget application image, built as `muse-gadget.bin` and linked at `0x20000`. Upload it with `file upload --path <build-dir>/muse-gadget.bin --type 4 --name <project>-muse-gadget.bin`. The server may rewrite part of the stored name, so `firmware_url` must be the returned `file_url`. A binary linked at `0x90000` or `0x10000` will not boot. Checking the box does not change `flash_address`: E100x stays `0x90000`, Sticky / Indicator / 1.47" Touch stay `0x0`, Watcher stays on the XIAO address rule.
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 the switch back from a Muse image to another firmware. 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 already merged at `0x0`, so the flag only turns on erase-all. Do not put the reTerminal stock bootloader into those images, and do not put it into a Muse image.
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,19 +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` | same as XIAO, optional | `.bin` on the Xiao / ESP32-S3 port |
110
- | Wio Terminal | `102991299` | `bin` | `0x4000` | `.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) | representative SKU of the group; 1.47" Touch Muse SKU is `100069905` | `bin` | `0x0` | merged `.bin`. nRF52840 variants cannot be flashed |
113
- | reTerminal E1001 | `100073581` | `bin` | `0x90000` | application-region `.bin`, not a full image with a bootloader |
114
- | reTerminal E1002 | `100017057` | `bin` | `0x90000` | same as E1001 |
115
- | XIAO e-paper / EE02–EE05 DIY (name contains Display, and is not IPS / Round / Touch / Sense) | matching SKU | `bin` | `0x90000` | same as E1001 |
116
- | reTerminal Sticky | `100056818` | `bin` | `0x0` | merged `.bin` |
117
- | SenseCAP Indicator D1 / D1S / D1L / D1Pro | one group; example `114993068` (D1) | `bin` | `0x0` | merged ESP32-S3 `.bin`, not the RP2040 port |
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
- `.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 C3 / C6 / S3 / S3 Sense / S3 Plus / Watcher keep 115200 and `flashSize` / `flashMode` / `flashFreq` = `keep`; do not apply the screen `0x90000` or merged-`0x0` rules to them.
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
- **Agent:** write the SKU, file, and address into the app doc. **Do not** claim the firmware was flashed. Serial flashing stays L3 (Console / Web Serial).
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
+
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.
122
147
 
123
148
  ### `deploy-ai-model` (vision / audio / related)
124
149