@seeed-studio/sensecraft-cli 0.1.2 → 0.1.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.
- package/INSTALL.md +442 -0
- package/LICENSE +21 -0
- package/README.md +50 -0
- package/package.json +28 -5
- package/scripts/constants.js +18 -3
- package/scripts/download.js +64 -16
- package/scripts/download.test.js +110 -0
- package/scripts/paths.js +28 -4
- package/scripts/paths.test.js +92 -0
- package/scripts/platform.js +8 -2
- package/scripts/postinstall.js +28 -7
- package/scripts/test-install.js +121 -0
- package/skills/README.md +32 -0
- package/skills/confirmation.md +54 -0
- package/skills/sensecraft-ai/SKILL.md +129 -0
- package/skills/sensecraft-apps/SKILL.md +197 -0
- package/skills/sensecraft-apps/commands.md +195 -0
- package/skills/sensecraft-apps/reference-app-fields.md +95 -0
- package/skills/sensecraft-apps/reference-tool-blocks.md +132 -0
- package/skills/sensecraft-data/SKILL.md +180 -0
- package/skills/sensecraft-data/commands.md +858 -0
- package/skills/sensecraft-devices-cloud/SKILL.md +53 -0
- package/skills/sensecraft-devices-cloud/commands.md +58 -0
- package/skills/sensecraft-files/SKILL.md +73 -0
- package/skills/sensecraft-files/commands.md +61 -0
- package/skills/sensecraft-models/SKILL.md +196 -0
- package/skills/sensecraft-models/commands.md +177 -0
- package/skills/sensecraft-models/reference-model-fields.md +139 -0
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Deploy docs & tool-block reference
|
|
2
|
+
|
|
3
|
+
Help the Agent choose the right block and fill `config` safely. Execution on hardware is **L3** unless noted.
|
|
4
|
+
|
|
5
|
+
## Document layout
|
|
6
|
+
|
|
7
|
+
`deployment.blocks` is a **flat** ordered array.
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
[ intro text blocks... ] [ step ][ text|tools... ] [ step ][ text|tools... ] ...
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
| Region | Rule |
|
|
14
|
+
|--------|------|
|
|
15
|
+
| Introduction | All blocks **before** the first `type === "step"` |
|
|
16
|
+
| One deploy step | A `step` block + following blocks until the next `step` |
|
|
17
|
+
|
|
18
|
+
### Text blocks (`content` HTML/text)
|
|
19
|
+
|
|
20
|
+
`step`, `paragraph`, `h1`–`h6`, `bullet`, `number`, `todo`, `quote`, `code`, `divider`.
|
|
21
|
+
|
|
22
|
+
Common fields: `id`, `type`, `content`, `indent`, `title`/`expanded` for `step`.
|
|
23
|
+
|
|
24
|
+
Prefer `paragraph` under a `step` for instructions; do not overload tool-block `config` with prose.
|
|
25
|
+
|
|
26
|
+
## Tool-block selection
|
|
27
|
+
|
|
28
|
+
| Priority | `type` | Use when | Avoid when |
|
|
29
|
+
|----------|--------|----------|------------|
|
|
30
|
+
| High | `flash-firmware` | User must burn a firmware image to a board | They only need model deploy |
|
|
31
|
+
| High | `deploy-ai-model` | Vision classify/detect or audio model on SenseCraft devices | Pure vibration → `ai-vibration`; pure firmware → `flash-firmware` |
|
|
32
|
+
| High | `ai-vibration` | Abnormal vibration detection flow | General vision/audio models |
|
|
33
|
+
| High | `deploy-container-app` | Edge **container** app deploy UX in the doc | Confusing with App Plaza **clone** or SenseCAP bind |
|
|
34
|
+
| Lower | `node-red` | Node-RED flow + optional model binding | No flow artifact |
|
|
35
|
+
| Lower | `aily-blockly` | Aily Blockly public project | No project id |
|
|
36
|
+
|
|
37
|
+
Multiple tool-blocks may appear in one step (e.g. paragraph → flash → paragraph → deploy-ai-model).
|
|
38
|
+
|
|
39
|
+
## High-priority configs
|
|
40
|
+
|
|
41
|
+
### `flash-firmware`
|
|
42
|
+
|
|
43
|
+
| Path | Meaning |
|
|
44
|
+
|------|---------|
|
|
45
|
+
| `config.device_id` | Device SKU |
|
|
46
|
+
| `config.device_type` | Compat field (may be `""`) |
|
|
47
|
+
| `config.firmware_url` | Firmware URL |
|
|
48
|
+
| `config.firmware_size` | Size string |
|
|
49
|
+
|
|
50
|
+
**Agent:** write URLs/SKU into the app doc. **Do not** claim the firmware was flashed until the user completes Console/Web Serial (L3).
|
|
51
|
+
|
|
52
|
+
### `deploy-ai-model` (vision / audio / related)
|
|
53
|
+
|
|
54
|
+
| Path | Meaning |
|
|
55
|
+
|------|---------|
|
|
56
|
+
| `config.model` | `null` or `{ type, model }` |
|
|
57
|
+
| `config.model.type` | `"model"` \| `"upload"` \| `"defer"` |
|
|
58
|
+
| `config.model.model` | Metadata: `id`, `name`, `task`, `labels`/`classes`, `uniform_types`, `isCustom`, … |
|
|
59
|
+
| `config.device_type` | Device `uniform_type` string (e.g. `"32"`) |
|
|
60
|
+
| `config.powerMode` | 0–5, default `2` (XIAO power-on infer) |
|
|
61
|
+
| `config.conf` / `config.iou` | Detection UI thresholds |
|
|
62
|
+
| `config.threshold` | Audio classify 0–1 when task/device needs it |
|
|
63
|
+
| `config.triggerAction` | Optional GPIO/LED/image trigger object |
|
|
64
|
+
|
|
65
|
+
**Scenes:** vision classify/detect → set `task` accordingly; sound → audio task + threshold; vibration-only product → prefer `ai-vibration`.
|
|
66
|
+
|
|
67
|
+
### `ai-vibration`
|
|
68
|
+
|
|
69
|
+
| Path | Default / notes |
|
|
70
|
+
|------|-----------------|
|
|
71
|
+
| `config.detectionType` | e.g. Abnormal Vibration Detection |
|
|
72
|
+
| `config.deviceType` | e.g. XIAO ESP32S3 Sense |
|
|
73
|
+
| `config.windowSize` | 192–768, default 384 |
|
|
74
|
+
| `config.isPower` | default false |
|
|
75
|
+
| `config.gpio` | `"-1"` = off |
|
|
76
|
+
| `config.dStatus` | default `"1"` |
|
|
77
|
+
|
|
78
|
+
### `deploy-container-app`
|
|
79
|
+
|
|
80
|
+
Used for **container / edge app** deployment UI inside the application doc (Fleet-related preview).
|
|
81
|
+
|
|
82
|
+
**Agent:** configure the block for documentation; installing onto a device fleet is **not** `app clone` and may need Fleet auth — see meta skill routing. Prefer linking users to Console preview deploy when CLI container control is not wired.
|
|
83
|
+
|
|
84
|
+
## Other tool-blocks
|
|
85
|
+
|
|
86
|
+
### `node-red`
|
|
87
|
+
|
|
88
|
+
| Path | Notes |
|
|
89
|
+
|------|-------|
|
|
90
|
+
| `config.flow_data_url` | Flow file URL |
|
|
91
|
+
| `config.flow_data` | Parsed flow; also sync top-level `flow_data` as **JSON string** |
|
|
92
|
+
| `config.model_id` | Cascade pair; `['3', id]` = my model |
|
|
93
|
+
| `config.model_data` | Snapshot; sync top-level `model_data` |
|
|
94
|
+
|
|
95
|
+
### `aily-blockly`
|
|
96
|
+
|
|
97
|
+
| Path | Notes |
|
|
98
|
+
|------|-------|
|
|
99
|
+
| `config.project_id` | Public project id |
|
|
100
|
+
| `config.device_id` | Deploy device SKU |
|
|
101
|
+
| `config.config` | Extension placeholder; avoid nested `config.config` objects |
|
|
102
|
+
|
|
103
|
+
## Minimal step + tool example
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
[
|
|
107
|
+
{
|
|
108
|
+
"id": "step_1",
|
|
109
|
+
"type": "step",
|
|
110
|
+
"title": "Step 1: Flash firmware",
|
|
111
|
+
"content": "Step 1: Flash firmware",
|
|
112
|
+
"expanded": true,
|
|
113
|
+
"indent": 0
|
|
114
|
+
},
|
|
115
|
+
{
|
|
116
|
+
"id": "para_1",
|
|
117
|
+
"type": "paragraph",
|
|
118
|
+
"content": "<p>Connect the board over USB, then flash.</p>",
|
|
119
|
+
"indent": 0
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
"id": "ff_1",
|
|
123
|
+
"type": "flash-firmware",
|
|
124
|
+
"config": {
|
|
125
|
+
"device_id": "",
|
|
126
|
+
"device_type": "",
|
|
127
|
+
"firmware_url": "https://example.com/fw.bin",
|
|
128
|
+
"firmware_size": ""
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
]
|
|
132
|
+
```
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sensecraft-data
|
|
3
|
+
description: >-
|
|
4
|
+
Operates SenseCraft CLI against SenseCAP PaaS HTTP OpenAPI to manage devices,
|
|
5
|
+
groups, development kits, and sensor telemetry data. Use when the user asks to
|
|
6
|
+
list/bind/unbind SenseCAP devices, manage device groups, query telemetry
|
|
7
|
+
(latest/list/chart), provision dev kits, or automate SenseCAP cloud operations
|
|
8
|
+
via CLI or npx. Not for SenseCraft AI apps/models/cloud.
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# SenseCraft Data (SenseCAP PaaS)
|
|
12
|
+
|
|
13
|
+
SenseCraft CLI wrappers for the [SenseCAP HTTP OpenAPI](https://sensecap-docs.seeed.cc/). Every `device`, `group`, and `data` command sends authenticated HTTP requests to the user's configured site (Global / China / Develop). The CLI unwraps the API envelope (`code`, `msg`, `data`) and prints only the `data` payload as indented JSON on stdout.
|
|
14
|
+
|
|
15
|
+
Parent router: [`../sensecraft-ai/SKILL.md`](../sensecraft-ai/SKILL.md).
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npx @seeed-studio/sensecraft-cli install
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
This downloads the platform binary, installs `sensecraft-cli` globally, and may run `auth init` in an interactive terminal.
|
|
24
|
+
|
|
25
|
+
Run without global install:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npx @seeed-studio/sensecraft-cli device list
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Requires Node.js >= 16.
|
|
32
|
+
|
|
33
|
+
## Agent rules
|
|
34
|
+
|
|
35
|
+
1. **Always check auth first** before `device`, `group`, or `data` commands:
|
|
36
|
+
```bash
|
|
37
|
+
sensecraft-cli auth info
|
|
38
|
+
```
|
|
39
|
+
2. **Never run `auth init` on behalf of the user** — it requires browser OAuth in an interactive terminal.
|
|
40
|
+
- SenseCAP Access Key: `sensecraft-cli auth init --kind sensecap`
|
|
41
|
+
- If the user already has Key ID / Access Key, guide them to run `auth add` locally instead (do not pass secrets into the agent context).
|
|
42
|
+
3. **L2 confirm is a separate chat turn** ([`../confirmation.md`](../confirmation.md)) before write ops: `device bind` / `unbind`, `group create` / rename / `delete` / `move-devices`, `device devkit create`. 「解绑这台设备」is **not** confirmation — ask (操作类型 + 环境 + EUI/组), wait for `确认`, then `--yes` where the command has it (`unbind` / `group delete` / `group move-devices`). Never pass `--yes` on the same turn as the first request.
|
|
43
|
+
4. **Treat dev kit credentials as secrets** — `device_key` and `token` must not be logged or echoed unnecessarily.
|
|
44
|
+
5. **Parse stdout JSON** on success; on failure read stderr and check exit code != 0.
|
|
45
|
+
6. **LoRaWAN devices** must use the Global (international) site per SenseCAP platform rules.
|
|
46
|
+
|
|
47
|
+
## Initialization check
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
sensecraft-cli auth info
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
| State | Indicator | Action |
|
|
54
|
+
|-------|-----------|--------|
|
|
55
|
+
| Initialized (SenseCAP) | Output shows SenseCAP `[active]`, Key ID, Site, Organization ID | Proceed with `device` / `group` / `data` |
|
|
56
|
+
| Not initialized | Prompts to run `auth init --kind sensecap` | Ask the user to run `auth init --kind sensecap` locally; for existing Access Key use `auth add` |
|
|
57
|
+
|
|
58
|
+
## Configuration
|
|
59
|
+
|
|
60
|
+
| Item | Env var | Default |
|
|
61
|
+
|------|---------|---------|
|
|
62
|
+
| Config directory | `SENSECRAFT_CLI_PATH` | Current working directory |
|
|
63
|
+
| Config file | `SENSECRAFT_CONFIG_FILE` | `sensecraft.json` (in config dir or as absolute path) |
|
|
64
|
+
|
|
65
|
+
Resolved path priority: `SENSECRAFT_CONFIG_FILE` (absolute or relative to `SENSECRAFT_CLI_PATH`) → `{SENSECRAFT_CLI_PATH}/sensecraft.json` → `{cwd}/sensecraft.json`.
|
|
66
|
+
|
|
67
|
+
## API sites
|
|
68
|
+
|
|
69
|
+
| Site | OpenAPI base URL |
|
|
70
|
+
|------|------------------|
|
|
71
|
+
| Global (International) | `https://sensecap.seeed.cc/openapi` |
|
|
72
|
+
| China | `https://sensecap.seeed.cn/openapi` |
|
|
73
|
+
| Develop (test) | Selected during `auth init` / `auth add`; stored in config |
|
|
74
|
+
|
|
75
|
+
Authentication: HTTP Basic Auth with Key ID (username) and Access Key (password), obtained via `auth init` (OAuth Device Flow) or `auth add` (manual import).
|
|
76
|
+
|
|
77
|
+
## Output and errors
|
|
78
|
+
|
|
79
|
+
- **Success**: indented JSON (2 spaces) on stdout.
|
|
80
|
+
- **Failure**: human-readable error on stderr; non-zero exit code.
|
|
81
|
+
- **API errors**: `API error code=<code>: <msg>` when the platform returns `code != "0"`.
|
|
82
|
+
|
|
83
|
+
## Command index
|
|
84
|
+
|
|
85
|
+
| Group | Command | OpenAPI method & path | Write? |
|
|
86
|
+
|-------|---------|----------------------|--------|
|
|
87
|
+
| auth | `init` | OAuth (not OpenAPI); `--kind sensecap\|ai` | Yes |
|
|
88
|
+
| auth | `add` | GET `/view_organization` (verify) + local config | Yes |
|
|
89
|
+
| auth | `info` | Local config only (SenseCAP + AI sections) | No |
|
|
90
|
+
| auth | `refresh` | authapi refreshToken (AI profile only) | Yes |
|
|
91
|
+
| device | `list` | GET `/list_devices` | No |
|
|
92
|
+
| device | `view` | POST `/view_devices` | No |
|
|
93
|
+
| device | `channels` | POST `/list_device_channels` | No |
|
|
94
|
+
| device | `status` | POST `/view_device_running_status` | No |
|
|
95
|
+
| device | `bind` | POST `/bind_device` | Yes |
|
|
96
|
+
| device | `unbind` | POST `/delete_devices` | Yes |
|
|
97
|
+
| device | `sim` | GET `/view_simcard` | No |
|
|
98
|
+
| device | `devkit create` | POST `/device/create_development_kit` | Yes |
|
|
99
|
+
| device | `devkit key` | GET `/device/view_node_key` | No |
|
|
100
|
+
| group | `list` | GET `/list_groups` | No |
|
|
101
|
+
| group | `create` | POST `/create_group` | Yes |
|
|
102
|
+
| group | `update` | POST `/update_group` | Yes |
|
|
103
|
+
| group | `delete` | POST `/delete_group` | Yes |
|
|
104
|
+
| group | `move-devices` | POST `/move_devices_to_group` | Yes |
|
|
105
|
+
| data | `latest` | GET `/view_latest_telemetry_data` | No |
|
|
106
|
+
| data | `list` | GET `/list_telemetry_data` | No |
|
|
107
|
+
| data | `chart` | GET `/aggregate_chart_points` | No |
|
|
108
|
+
|
|
109
|
+
## Typical workflows
|
|
110
|
+
|
|
111
|
+
### Discover devices and read sensor data
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
sensecraft-cli auth info
|
|
115
|
+
sensecraft-cli group list
|
|
116
|
+
sensecraft-cli device list
|
|
117
|
+
sensecraft-cli device channels --eui <node-eui>
|
|
118
|
+
sensecraft-cli data latest --eui <node-eui> --measurement-id 4097 --channel-index 1
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Bind a new physical device
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
sensecraft-cli group list # optional: get group_uuid
|
|
125
|
+
sensecraft-cli device bind --eui <eui> --code <code> --name "My Sensor" --group-uuid <uuid>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Provision a development kit
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
sensecraft-cli device devkit create --sku xiao --name "lab-xiao"
|
|
132
|
+
sensecraft-cli device devkit key --eui <16-char-eui>
|
|
133
|
+
sensecraft-cli device list --device-type 3
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Device type reference
|
|
137
|
+
|
|
138
|
+
Used by `device list` and `device view`:
|
|
139
|
+
|
|
140
|
+
| Value | Type |
|
|
141
|
+
|-------|------|
|
|
142
|
+
| `1` | Gateway |
|
|
143
|
+
| `2` | Node (default) |
|
|
144
|
+
| `3` | Development kit |
|
|
145
|
+
|
|
146
|
+
## Dev kit SKU reference
|
|
147
|
+
|
|
148
|
+
Used by `device devkit create --sku`:
|
|
149
|
+
|
|
150
|
+
| SKU | Product |
|
|
151
|
+
|-----|---------|
|
|
152
|
+
| `blank_device` | Blank Device |
|
|
153
|
+
| `xiao` | XIAO |
|
|
154
|
+
| `grove_vision_ai` | Grove Vision AI V2 |
|
|
155
|
+
|
|
156
|
+
Limit: max 5 development kits per SKU per organization.
|
|
157
|
+
|
|
158
|
+
## Known output schema gaps
|
|
159
|
+
|
|
160
|
+
The CLI typed models and tests confirm these fields. **If you need fields beyond what is listed, ask the user to provide a live API sample** — the platform may return additional properties that pass through on untyped commands but are stripped on typed devkit create output.
|
|
161
|
+
|
|
162
|
+
| Command | Schema confidence |
|
|
163
|
+
|---------|-------------------|
|
|
164
|
+
| `device devkit create` | **Partial** — code confirms `eui`, `device_key` only |
|
|
165
|
+
| `device devkit key` | **High** — code confirms `eui`, `device_key`, `token` |
|
|
166
|
+
| `data latest/list/chart` | **High** — aligned with OpenAPI v2 paths and query params |
|
|
167
|
+
|
|
168
|
+
Dev kit OpenAPI endpoints (`/device/create_development_kit`, `/device/view_node_key`) are **not documented** in the public SenseCAP HTTP API reference at the time of writing.
|
|
169
|
+
|
|
170
|
+
## Full command reference
|
|
171
|
+
|
|
172
|
+
Every command, flag, limit, example, and documented response field: **[commands.md](commands.md)**
|
|
173
|
+
|
|
174
|
+
## External references
|
|
175
|
+
|
|
176
|
+
- SenseCAP HTTP API overview: https://sensecap-docs.seeed.cc/introduction.html
|
|
177
|
+
- Device Management API: https://sensecap-docs.seeed.cc/device_management.html
|
|
178
|
+
- Group Management API: https://sensecap-docs.seeed.cc/group_management.html
|
|
179
|
+
- Device Data API: https://sensecap-docs.seeed.cc/device_data.html
|
|
180
|
+
- Measurement ID appendix: https://sensecap-docs.seeed.cc/
|