@seeed-studio/sensecraft-cli 0.4.1 → 0.4.3

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.
@@ -2,11 +2,17 @@
2
2
 
3
3
  Help the Agent choose the right block and fill `config` safely. Execution on hardware is **L3** unless noted.
4
4
 
5
+ ## Plan before writing blocks
6
+
7
+ Read this entire reference before drafting a deployment plan or tool config. Inspect `sensecraft-cli app blocks` as the static catalog, then map the real project journey to supported actions. For each action identify prerequisites, the suitable tool, actual artifact/config sources, and the observable result. Select only tools the project needs, and place each immediately after its instructions in the flat array.
8
+
9
+ Check the exact hardware variant, artifact target/architecture, deployment inputs, and device rules below. A local file awaiting upload is a planned upload; a missing artifact or unknown target is an unresolved deployment gap. Preserve a needed tool in the local draft while resolving its inputs. Do not substitute a prose-only instruction that makes an unsupported action appear executable. Report such gaps and agree on a supported path or an explicitly incomplete draft. A format-valid block is not evidence that deployment will work.
10
+
5
11
  ## Content format
6
12
 
7
13
  The editor does **not** render Markdown on read. Preview wraps each block by `type` and treats `content` as HTML or plain text. Raw `**bold**`, `# heading`, or `- item` inside `content` shows up as those characters.
8
14
 
9
- Write inline formatting as HTML the editor stores: `<strong>`, `<em>`, `<code>`, `<s>`, links with `target="_blank"`, file links (pdf/zip/bin/…) also with `download` and `doc-file-download-link`, images with `draggable="false"`. A paragraph that is only a video URL becomes `<video controls>` or a `video-embed-wrapper` iframe (YouTube, TikTok, Douyin, Bilibili, Vimeo, Youku, iQiyi). Prefer `app create --from-md` / `app update --from-md` instead of writing that HTML by hand. `--from-json` fills those video, link, and image attributes when they are missing. Do not wrap a `paragraph` in an extra `<p>`. `code` block `content` is plain source, not HTML.
15
+ Write inline formatting as HTML the editor stores: `<strong>`, `<em>`, `<code>`, `<s>`, links with `target="_blank"`, file links (pdf/zip/bin/…) also with `download` and `doc-file-download-link`, images with `draggable="false"`. A paragraph that is only a video URL becomes `<video controls>` or a `video-embed-wrapper` iframe (YouTube, TikTok, Douyin, Bilibili, Vimeo, Youku, iQiyi). Compile Markdown rather than writing that HTML by hand. For interleaved prose/tools, compile locally, insert tools at their intended positions, and send the final blocks through `--from-json`. Combining `--from-md` with JSON tool blocks appends those tools after the entire compiled document; it does not place them into earlier steps. `--from-json` fills video, link, and image attributes when they are missing. Do not wrap a `paragraph` in an extra `<p>`. `code` block `content` is plain source, not HTML.
10
16
 
11
17
  Compile a Markdown file with `sensecraft-cli app doc compile --from-md <file>` when you only want the JSON (no network). `app create --from-md` and `app update --from-md` run that compile and then write. JSON text blocks that still contain Markdown markers are rejected. How the toolbar maps onto blocks: [../../../docs/md-to-app.md](../../../docs/md-to-app.md).
12
18
 
@@ -16,6 +22,8 @@ Host binaries (images, videos, firmware) via `file upload` first. A relative pat
16
22
 
17
23
  `deployment.blocks` is a **flat** ordered array.
18
24
 
25
+ “Flat” describes the array of blocks, not a tool's settings. Every tool block stores its settings inside one `config` object. The page reads `block.config.*` directly for this format; it does not wrap fields from the block root on read. Flattened settings belong to the separate legacy `deployment[].tools[]` format and must not be copied into modern `deployment.blocks[]`.
26
+
19
27
  ```text
20
28
  [ intro text blocks... ] [ step ][ text|tools... ] [ step ][ text|tools... ] ...
21
29
  ```
@@ -52,18 +60,18 @@ Multiple tool-blocks may appear in one step (e.g. paragraph → flash → paragr
52
60
 
53
61
  ### `flash-firmware`
54
62
 
55
- Write these as **flat fields** on the block. The editor wraps them into `config` when it reloads the doc. Do not nest them under `config` in `app create` / `app update`.
63
+ Write every field below inside **`block.config`**, just like other tool blocks, for `app create` / `app update`. Keep `id`, `type`, and layout metadata on the block itself. Reject flat or mixed root/config settings and an extra `config.config` wrapper; do not rely on opening the editor to repair them. Existing flat blocks need an explicit migration that preserves all their settings.
56
64
 
57
65
  | Field | How to write |
58
66
  |-------|----------------|
59
- | `device_id` | Material SKU string, e.g. `"100017057"`. Not a production type id (`"29"`) and not the material row `id` |
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 |
60
68
  | `device_type` | `uniform_type` string. Use `""` when the board has none (Wio / Grove may) |
61
69
  | `flash_mode` | `"bin"` when a firmware URL is set. `"zip"` for a project zip |
62
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 |
63
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 |
64
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 / `[]` |
65
- | `muse_gadget` | Boolean, default `false`. A missing field is `false`. `"true"` and `1` are read as `true`. `true` shows the Muse SDK token input under the flash button in preview |
66
- | `full_flash` | Boolean, default `false`. Same true/false reading as `muse_gadget`. 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 |
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 |
67
75
 
68
76
  `muse_gadget: true` is kept only for these SKUs. Any other device written `true` is reset to `false` by the editor. `full_flash` uses the same SKU list:
69
77
 
@@ -167,7 +175,7 @@ Used for **container / edge app** deployment UI inside the application doc. Fiel
167
175
  | Path | Notes |
168
176
  |------|-------|
169
177
  | `config.flow_data_url` | Flow file URL |
170
- | `config.flow_data` | Parsed flow; also sync top-level `flow_data` as **JSON string** |
178
+ | `config.flow_data` | Parsed flow object **or array**, not a JSON string; also sync top-level `flow_data` as **JSON string** |
171
179
  | `config.model_id` | Cascade pair; `['3', id]` = my model |
172
180
  | `config.model_data` | Snapshot; sync top-level `model_data` |
173
181
 
@@ -200,15 +208,23 @@ Used for **container / edge app** deployment UI inside the application doc. Fiel
200
208
  {
201
209
  "id": "ff_1",
202
210
  "type": "flash-firmware",
203
- "device_id": "100017057",
204
- "device_type": "",
205
- "flash_mode": "bin",
206
- "firmware_url": "https://example.com/e1002-app.bin",
207
- "firmware_name": "e1002-app.bin",
208
- "firmware_size": "1234567",
209
- "flash_address": "0x90000",
210
- "muse_gadget": false,
211
- "full_flash": false
211
+ "config": {
212
+ "device_id": "100017057",
213
+ "device_type": "",
214
+ "flash_mode": "bin",
215
+ "firmware_url": "https://example.com/e1002-app.bin",
216
+ "firmware_name": "e1002-app.bin",
217
+ "firmware_size": "1234567",
218
+ "flash_address": "0x90000",
219
+ "muse_gadget": false,
220
+ "full_flash": false
221
+ }
212
222
  }
213
223
  ]
214
224
  ```
225
+
226
+ ## Repair an existing malformed block
227
+
228
+ Read the latest owner sketch, clone its **complete** `deployment`, and move the affected block's settings into `config`, preserving its ID, all values, order, and every other block. If flat and nested values disagree, resolve that conflict before writing. An update containing only a one-element `deployment.blocks` array replaces the document; it is not a patch of that one block.
229
+
230
+ Validate the corrected document and follow the parent's existing-app write protocol. Re-read the sketch afterward and check the saved `config` and unchanged surrounding blocks. Reconcile the project's local manifest and sync baseline too, so a later push does not restore the malformed shape. A successful API response only proves storage; verify the consumer-visible field paths as well.