@seeed-studio/sensecraft-cli 0.1.1 → 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.
@@ -0,0 +1,858 @@
1
+ # SenseCraft CLI — Command Reference
2
+
3
+ Complete reference for AI agents. All paths are relative to the OpenAPI base URL (`https://sensecap.seeed.cc/openapi` or `https://sensecap.seeed.cn/openapi`).
4
+
5
+ ---
6
+
7
+ ## auth init
8
+
9
+ Interactive setup wizard (OAuth Device Flow). Obtains an Access Key and writes `sensecraft.json`.
10
+
11
+ **Not an OpenAPI call.** Requires interactive terminal (TTY) unless using sandbox mode.
12
+
13
+ ### Flags
14
+
15
+ | Flag | Required | Default | Description |
16
+ |------|----------|---------|-------------|
17
+ | `--sandbox` | No | `false` | Simulate the full wizard without sending real network requests |
18
+
19
+ ### Wizard steps
20
+
21
+ 1. Select site: Global (International), China, or Develop (test)
22
+ 2. Browser OAuth Device Flow authorization
23
+ 3. Organization selection
24
+ 4. Access Key creation
25
+ 5. Save to local config and set as active profile
26
+
27
+ ### Output
28
+
29
+ Human-readable progress on stdout/stderr. No JSON payload.
30
+
31
+ ### Agent notes
32
+
33
+ - Do **not** run on behalf of the user in non-interactive environments.
34
+ - In sandbox mode, simulated credentials are written locally for testing.
35
+
36
+ ---
37
+
38
+ ## auth add
39
+
40
+ Manually add an existing Access Key to local config. Verifies credentials via OpenAPI `GET /view_organization`, saves to `sensecraft.json`, and sets the profile as active.
41
+
42
+ Site defaults to Global when omitted. In an interactive terminal, missing `--key-id` / `--access-key` will be prompted.
43
+
44
+ ### Flags
45
+
46
+ | Flag | Required | Default | Description |
47
+ |------|----------|---------|-------------|
48
+ | `--key-id` | Yes* | — | Access Key ID (API ID) |
49
+ | `--access-key` | Yes* | — | Access Key secret |
50
+ | `--site` | No | `Global` | Site: `Global`, `China`, or `Develop` |
51
+
52
+ \* Required unless running interactively (then prompted).
53
+
54
+ ### Steps
55
+
56
+ 1. Collect Key ID, Access Key, and optional site
57
+ 2. Call `GET /view_organization` with HTTP Basic Auth to verify and obtain `org_id`
58
+ 3. Save profile to local config and set as active
59
+
60
+ ### Output
61
+
62
+ Human-readable progress on stdout/stderr. No JSON payload.
63
+
64
+ ### Agent notes
65
+
66
+ - Prefer this over `auth init` when the user already has Key ID / Access Key (e.g. from SenseCAP Portal).
67
+ - Do **not** echo `--access-key` in logs; treat it as a secret.
68
+ - Still requires network access to the selected site's OpenAPI host.
69
+
70
+ ---
71
+
72
+ ## auth info
73
+
74
+ Display local authentication configuration. Does not call the cloud API.
75
+
76
+ ### Flags
77
+
78
+ None.
79
+
80
+ ### Output (text, not JSON)
81
+
82
+ ```
83
+ Config file: /path/to/sensecraft.json
84
+ Active Key ID: <key-id>
85
+
86
+ [active]
87
+ Site: Global (International)
88
+ Organization ID: <org-id>
89
+ Key ID: <key-id>
90
+ Created at: <RFC3339 timestamp>
91
+ ```
92
+
93
+ When uninitialized:
94
+
95
+ ```
96
+ Config file: /path/to/sensecraft.json
97
+
98
+ No Access Key configured yet. Run: sensecraft-cli auth init
99
+ ```
100
+
101
+ ---
102
+
103
+ ## device list
104
+
105
+ List devices under the current account.
106
+
107
+ **OpenAPI:** `GET /list_devices`
108
+
109
+ ### Flags
110
+
111
+ | Flag | Required | Default | Description |
112
+ |------|----------|---------|-------------|
113
+ | `--device-type` | No | `2` | Device type: `1`=gateway, `2`=node, `3`=development kit |
114
+ | `--group-uuid` | No | — | Filter by group UUID; omit to return devices from all groups |
115
+
116
+ ### Query parameters sent to API
117
+
118
+ | Parameter | Source |
119
+ |-----------|--------|
120
+ | `device_type` | `--device-type` |
121
+ | `group_uuid` | `--group-uuid` (omitted if empty) |
122
+
123
+ ### Examples
124
+
125
+ ```bash
126
+ sensecraft-cli device list
127
+ sensecraft-cli device list --device-type 1
128
+ sensecraft-cli device list --device-type 3
129
+ sensecraft-cli device list --group-uuid 80523B280630E611
130
+ ```
131
+
132
+ ### Response schema
133
+
134
+ JSON **array** of objects:
135
+
136
+ | Field | Type | Description |
137
+ |-------|------|-------------|
138
+ | `device_eui` | string | Device unique identifier (EUI) |
139
+ | `device_name` | string | Device display name |
140
+
141
+ ### Example output
142
+
143
+ ```json
144
+ [
145
+ {
146
+ "device_eui": "2CF7F12010700088",
147
+ "device_name": "device2CF7F12010700088"
148
+ }
149
+ ]
150
+ ```
151
+
152
+ ---
153
+
154
+ ## device view
155
+
156
+ Get detailed information for one or more devices.
157
+
158
+ **OpenAPI:** `POST /view_devices`
159
+
160
+ ### Flags
161
+
162
+ | Flag | Required | Default | Description |
163
+ |------|----------|---------|-------------|
164
+ | `--eui` | **Yes** | — | Device EUI; repeat flag for multiple devices (max **50** per request) |
165
+ | `--device-type` | No | `2` | Device type: `1`=gateway, `2`=node, `3`=development kit |
166
+
167
+ ### Request body sent to API
168
+
169
+ ```json
170
+ {
171
+ "device_euis": ["<eui1>", "<eui2>"],
172
+ "device_type": 2
173
+ }
174
+ ```
175
+
176
+ ### Examples
177
+
178
+ ```bash
179
+ sensecraft-cli device view --eui 2CF7F15000100122
180
+ sensecraft-cli device view --eui EUI1 --eui EUI2 --device-type 1
181
+ ```
182
+
183
+ ### Response schema
184
+
185
+ JSON **array** of device detail objects (per [SenseCAP Device Management API](https://sensecap-docs.seeed.cc/device_management.html)):
186
+
187
+ | Field | Type | Description |
188
+ |-------|------|-------------|
189
+ | `frequency` | string | Communication frequency |
190
+ | `device_eui` | string | Device EUI |
191
+ | `device_name` | string | Device name |
192
+ | `device_network` | number | Network type: `1`=LoRaWAN, `2`=NB-IoT, `3`=2G, `4`=LoRaPP |
193
+ | `position` | object | GPS location (`latitude`, `longitude`) |
194
+ | `position_source` | number | `0`=manually set, `1`=reported by device |
195
+ | `hardware_version` | string | Hardware version |
196
+ | `software_version` | string | Software/firmware version |
197
+ | `sim` | object | SIM info (e.g. `iccid`) |
198
+
199
+ Additional fields may be present depending on device type.
200
+
201
+ ---
202
+
203
+ ## device channels
204
+
205
+ List measurement channels for node devices.
206
+
207
+ **OpenAPI:** `POST /list_device_channels`
208
+
209
+ ### Flags
210
+
211
+ | Flag | Required | Default | Description |
212
+ |------|----------|---------|-------------|
213
+ | `--eui` | **Yes** | — | Node device EUI; repeat for multiple (max **50**) |
214
+
215
+ ### Request body
216
+
217
+ ```json
218
+ { "device_euis": ["<eui1>", "<eui2>"] }
219
+ ```
220
+
221
+ ### Examples
222
+
223
+ ```bash
224
+ sensecraft-cli device channels --eui 2CF7F16221200060
225
+ ```
226
+
227
+ ### Response schema
228
+
229
+ JSON **array**; each element:
230
+
231
+ | Field | Type | Description |
232
+ |-------|------|-------------|
233
+ | `device_eui` | string | Device EUI |
234
+ | `channels` | array | Channel list for this device |
235
+
236
+ Each channel object:
237
+
238
+ | Field | Type | Description |
239
+ |-------|------|-------------|
240
+ | `channel_index` | number | Channel number (use as `--channel-index` in data commands) |
241
+ | `sensor_id` | string | Sensor identifier |
242
+ | `sensor_status` | number | `0`=idle, `1`=normal, `2`=abnormal |
243
+ | `channel_type` | number | `1`=485 Sensor, `2`=Seeed Sensor, `3`=485 Output, `4`=Seeed Output |
244
+ | `sensor_type` | string | Sensor type ID |
245
+ | `channel_name` | string | Channel name |
246
+ | `measurement_ids` | array of string | Measurement IDs (use as `--measurement-id` in data commands) |
247
+
248
+ ### Agent tip
249
+
250
+ Run this before `data latest`, `data list`, or `data chart` to discover valid `measurement_ids` and channel numbers.
251
+
252
+ ---
253
+
254
+ ## device status
255
+
256
+ Get running status for devices.
257
+
258
+ **OpenAPI:** `POST /view_device_running_status`
259
+
260
+ ### Flags
261
+
262
+ | Flag | Required | Default | Description |
263
+ |------|----------|---------|-------------|
264
+ | `--eui` | **Yes** | — | Device EUI; repeat for multiple (max **50**) |
265
+
266
+ ### Request body
267
+
268
+ ```json
269
+ { "device_euis": ["<eui1>"] }
270
+ ```
271
+
272
+ ### Examples
273
+
274
+ ```bash
275
+ sensecraft-cli device status --eui 2CF7F16221200060
276
+ sensecraft-cli device status --eui EUI1 --eui EUI2
277
+ ```
278
+
279
+ ### Response schema
280
+
281
+ JSON **array** of status objects:
282
+
283
+ | Field | Type | Description |
284
+ |-------|------|-------------|
285
+ | `device_eui` | string | Device EUI |
286
+ | `latest_message_time` | string | Last message time (ISO 8601); empty if none |
287
+ | `online_status` | number | `0`=offline, `1`=online |
288
+ | `battery_status` | number | `0`=low battery, `1`=good battery |
289
+ | `battery_digit` | number | Battery level percentage |
290
+ | `report_frequency` | number | Report interval in minutes; `-1` if unavailable |
291
+
292
+ ---
293
+
294
+ ## device bind
295
+
296
+ Bind a device to the current account.
297
+
298
+ **OpenAPI:** `POST /bind_device`
299
+
300
+ **Write operation** — confirm EUI and binding code with the user.
301
+
302
+ ### Flags
303
+
304
+ | Flag | Required | Default | Description |
305
+ |------|----------|---------|-------------|
306
+ | `--eui` | **Yes** | — | Device EUI (printed on device label) |
307
+ | `--code` | **Yes** | — | Device binding code (printed on device label) |
308
+ | `--name` | No | — | Custom device display name |
309
+ | `--group-uuid` | No | — | Target group UUID (from `group list`) |
310
+ | `--longitude` | No | — | Longitude string |
311
+ | `--latitude` | No | — | Latitude string |
312
+
313
+ ### Request body sent to API
314
+
315
+ | JSON field | CLI flag |
316
+ |------------|----------|
317
+ | `eui` | `--eui` |
318
+ | `code` | `--code` |
319
+ | `device_name` | `--name` (omitted if empty) |
320
+ | `group_uuid` | `--group-uuid` (omitted if empty) |
321
+ | `longitude` | `--longitude` (omitted if empty) |
322
+ | `latitude` | `--latitude` (omitted if empty) |
323
+
324
+ ### Examples
325
+
326
+ ```bash
327
+ sensecraft-cli device bind --eui 2CF7F15000100122 --code ABCD1234
328
+ sensecraft-cli device bind --eui 2CF7F15000100122 --code ABCD1234 \
329
+ --name "Greenhouse Node 1" --group-uuid 80523B280630E611 \
330
+ --longitude 113.926979 --latitude 22.573724
331
+ ```
332
+
333
+ ### Response schema
334
+
335
+ Empty object on success:
336
+
337
+ ```json
338
+ {}
339
+ ```
340
+
341
+ ---
342
+
343
+ ## device unbind
344
+
345
+ Remove devices from the current account (devices can be re-bound via the SenseCAP App).
346
+
347
+ **OpenAPI:** `POST /delete_devices`
348
+
349
+ **Write operation** — L2: separate chat confirm, then `--yes`.
350
+
351
+ ### Flags
352
+
353
+ | Flag | Required | Default | Description |
354
+ |------|----------|---------|-------------|
355
+ | `--eui` | **Yes** | — | Device EUI; repeat for multiple (max **50**) |
356
+ | `--yes` | **Yes** | `false` | Confirm L2 unbind |
357
+
358
+ ### Request body
359
+
360
+ ```json
361
+ { "device_euis": ["<eui1>", "<eui2>"] }
362
+ ```
363
+
364
+ ### Examples
365
+
366
+ ```bash
367
+ sensecraft-cli device unbind --eui 2CF7F15000100122 --yes
368
+ sensecraft-cli device unbind --eui EUI1 --eui EUI2 --yes
369
+ ```
370
+
371
+ ### Response schema
372
+
373
+ ```json
374
+ {}
375
+ ```
376
+
377
+ ---
378
+
379
+ ## device sim
380
+
381
+ Query SIM card status by ICCID.
382
+
383
+ **OpenAPI:** `GET /view_simcard?iccid=<iccid>`
384
+
385
+ ### Flags
386
+
387
+ | Flag | Required | Default | Description |
388
+ |------|----------|---------|-------------|
389
+ | `--iccid` | **Yes** | — | SIM card ICCID |
390
+
391
+ ### Examples
392
+
393
+ ```bash
394
+ sensecraft-cli device sim --iccid 89860446091891237424
395
+ ```
396
+
397
+ ### Response schema
398
+
399
+ | Field | Type | Description |
400
+ |-------|------|-------------|
401
+ | `iccid` | string | ICCID |
402
+ | `msisdn` | string | MSISDN |
403
+ | `activateTime` | string | Activation date (timestamp ms) |
404
+ | `expiryDate` | string | Billing end date (timestamp ms) |
405
+ | `status` | string | `0`=unknown, `1`=normal, `2`=single stop, `3`=stop, `4`=pre-sale, `5`=sale, `6`=transfer, `7`=sleep, `8`=pending activation |
406
+ | `flow` | string | Current month data usage |
407
+ | `residueFlow` | string | Remaining data allowance |
408
+
409
+ ---
410
+
411
+ ## device devkit create
412
+
413
+ Create a development kit virtual device.
414
+
415
+ **OpenAPI:** `POST /device/create_development_kit`
416
+
417
+ **Write operation.** Max **5** kits per SKU per organization.
418
+
419
+ > **Schema note:** This endpoint is not in the public SenseCAP API docs. The CLI only types `eui` and `device_key`. If the live API returns additional fields, they may be omitted from CLI output. Ask the user for a sample response if more fields are needed.
420
+
421
+ ### Flags
422
+
423
+ | Flag | Required | Default | Description |
424
+ |------|----------|---------|-------------|
425
+ | `--sku` | **Yes** | — | Dev kit SKU (see SKU table in SKILL.md) |
426
+ | `--name` | No | — | Device display name |
427
+
428
+ ### Request body sent to API
429
+
430
+ ```json
431
+ {
432
+ "sku": "xiao",
433
+ "dev_name": "my-xiao"
434
+ }
435
+ ```
436
+
437
+ (`dev_name` omitted when `--name` is not set.)
438
+
439
+ ### Examples
440
+
441
+ ```bash
442
+ sensecraft-cli device devkit create --sku blank_device
443
+ sensecraft-cli device devkit create --sku xiao --name "lab-xiao"
444
+ sensecraft-cli device devkit create --sku grove_vision_ai --name "vision-lab"
445
+ ```
446
+
447
+ ### Response schema (confirmed by CLI code)
448
+
449
+ | Field | Type | Description |
450
+ |-------|------|-------------|
451
+ | `eui` | string | 16-character device EUI assigned to the kit |
452
+ | `device_key` | string | Device access key for onboarding |
453
+
454
+ ### Example output
455
+
456
+ ```json
457
+ {
458
+ "eui": "0123456789ABCDEF",
459
+ "device_key": "your-device-key"
460
+ }
461
+ ```
462
+
463
+ ### Follow-up
464
+
465
+ Use `device devkit key --eui <eui>` to retrieve `token` for MQTT/network configuration.
466
+
467
+ ---
468
+
469
+ ## device devkit key
470
+
471
+ Retrieve development kit credentials by EUI.
472
+
473
+ **OpenAPI:** `GET /device/view_node_key?node_eui=<eui>`
474
+
475
+ > **Schema note:** Not in public SenseCAP API docs. CLI validates EUI length (16 chars) and types three response fields.
476
+
477
+ ### Flags
478
+
479
+ | Flag | Required | Default | Description |
480
+ |------|----------|---------|-------------|
481
+ | `--eui` | **Yes** | — | 16-character dev kit EUI (auto uppercased and trimmed) |
482
+
483
+ ### Examples
484
+
485
+ ```bash
486
+ sensecraft-cli device devkit key --eui 0123456789ABCDEF
487
+ ```
488
+
489
+ ### Response schema (confirmed by CLI code)
490
+
491
+ | Field | Type | Description |
492
+ |-------|------|-------------|
493
+ | `eui` | string | Device EUI |
494
+ | `device_key` | string | Device access key |
495
+ | `token` | string | Authentication token (e.g. for MQTT connection) |
496
+
497
+ ### Example output
498
+
499
+ ```json
500
+ {
501
+ "eui": "0123456789ABCDEF",
502
+ "device_key": "your-device-key",
503
+ "token": "your-token"
504
+ }
505
+ ```
506
+
507
+ ### Agent notes
508
+
509
+ - EUI must be exactly **16 characters**; otherwise CLI returns a validation error before calling the API.
510
+ - Only supported for dev kit devices (Blank Device / XIAO / Grove Vision AI V2).
511
+ - **Treat all credential fields as secrets.**
512
+
513
+ ---
514
+
515
+ ## group list
516
+
517
+ List all device groups.
518
+
519
+ **OpenAPI:** `GET /list_groups`
520
+
521
+ ### Flags
522
+
523
+ None.
524
+
525
+ ### Example
526
+
527
+ ```bash
528
+ sensecraft-cli group list
529
+ ```
530
+
531
+ ### Response schema
532
+
533
+ JSON **array** of group objects:
534
+
535
+ | Field | Type | Description |
536
+ |-------|------|-------------|
537
+ | `group_name` | string | Group display name |
538
+ | `group_uuid` | string | Group UUID; empty string for the default group |
539
+
540
+ ### Example output
541
+
542
+ ```json
543
+ [
544
+ { "group_name": "Default", "group_uuid": "" },
545
+ { "group_name": "test group", "group_uuid": "80523B280630E611" }
546
+ ]
547
+ ```
548
+
549
+ ---
550
+
551
+ ## group create
552
+
553
+ Create a new device group.
554
+
555
+ **OpenAPI:** `POST /create_group`
556
+
557
+ **Write operation.** Max **50** groups per account.
558
+
559
+ ### Flags
560
+
561
+ | Flag | Required | Default | Description |
562
+ |------|----------|---------|-------------|
563
+ | `--name` | **Yes** | — | Group name |
564
+
565
+ ### Request body
566
+
567
+ ```json
568
+ { "name": "Greenhouse A" }
569
+ ```
570
+
571
+ ### Example
572
+
573
+ ```bash
574
+ sensecraft-cli group create --name "Greenhouse A"
575
+ ```
576
+
577
+ ### Response schema
578
+
579
+ | Field | Type | Description |
580
+ |-------|------|-------------|
581
+ | `group_name` | string | Created group name |
582
+ | `group_uuid` | string | New group UUID |
583
+
584
+ ---
585
+
586
+ ## group update
587
+
588
+ Rename a device group.
589
+
590
+ **OpenAPI:** `POST /update_group`
591
+
592
+ **Write operation.**
593
+
594
+ ### Flags
595
+
596
+ | Flag | Required | Default | Description |
597
+ |------|----------|---------|-------------|
598
+ | `--group-uuid` | **Yes** | — | Group UUID to update |
599
+ | `--name` | **Yes** | — | New group name |
600
+
601
+ ### Request body
602
+
603
+ ```json
604
+ { "group_uuid": "<uuid>", "name": "New Name" }
605
+ ```
606
+
607
+ ### Example
608
+
609
+ ```bash
610
+ sensecraft-cli group update --group-uuid 80523B280630E611 --name "Renamed Group"
611
+ ```
612
+
613
+ ### Response schema
614
+
615
+ ```json
616
+ {}
617
+ ```
618
+
619
+ ---
620
+
621
+ ## group delete
622
+
623
+ Delete a device group. Devices in the group move to the default group.
624
+
625
+ **OpenAPI:** `POST /delete_group?group_uuid=<uuid>`
626
+
627
+ **Write operation** — L2: separate chat confirm, then `--yes`. The default group cannot be deleted.
628
+
629
+ ### Flags
630
+
631
+ | Flag | Required | Default | Description |
632
+ |------|----------|---------|-------------|
633
+ | `--group-uuid` | **Yes** | — | Group UUID to delete |
634
+ | `--yes` | **Yes** | `false` | Confirm L2 delete |
635
+
636
+ ### Example
637
+
638
+ ```bash
639
+ sensecraft-cli group delete --group-uuid 80523B280630E611 --yes
640
+ ```
641
+
642
+ ### Response schema
643
+
644
+ ```json
645
+ {}
646
+ ```
647
+
648
+ ---
649
+
650
+ ## group move-devices
651
+
652
+ Move devices to a target group.
653
+
654
+ **OpenAPI:** `POST /move_devices_to_group`
655
+
656
+ **Write operation** — L2: separate chat confirm, then `--yes`.
657
+
658
+ ### Flags
659
+
660
+ | Flag | Required | Default | Description |
661
+ |------|----------|---------|-------------|
662
+ | `--group-uuid` | **Yes** | — | Target group UUID |
663
+ | `--eui` | **Yes** | — | Device EUI; repeat for multiple |
664
+ | `--yes` | **Yes** | `false` | Confirm L2 move |
665
+
666
+ ### Request body
667
+
668
+ ```json
669
+ {
670
+ "group_uuid": "<target-uuid>",
671
+ "devices": ["<eui1>", "<eui2>"]
672
+ }
673
+ ```
674
+
675
+ ### Example
676
+
677
+ ```bash
678
+ sensecraft-cli group move-devices \
679
+ --group-uuid 80523B280630E611 \
680
+ --eui 2CF7F12004100001 --eui 2CF7F12004100002 --yes
681
+ ```
682
+
683
+ ### Response schema
684
+
685
+ ```json
686
+ {}
687
+ ```
688
+
689
+ ---
690
+
691
+ ## data latest
692
+
693
+ Get the latest telemetry data for a device within the past year.
694
+ If `channel_index` is omitted, returns the latest point under each channel.
695
+
696
+ **OpenAPI:** `GET /view_latest_telemetry_data`
697
+
698
+ ### Flags
699
+
700
+ | Flag | Required | Default | Description |
701
+ |------|----------|---------|-------------|
702
+ | `--eui` | **Yes** | — | Device EUI |
703
+ | `--measurement-id` | No | — | Measurement ID (from `device channels`) |
704
+ | `--channel-index` | No | — | Channel index (from `device channels`) |
705
+
706
+ ### Query parameters sent to API
707
+
708
+ | Parameter | Source |
709
+ |-----------|--------|
710
+ | `device_eui` | `--eui` |
711
+ | `measurement_id` | `--measurement-id` (omitted if empty) |
712
+ | `channel_index` | `--channel-index` (omitted if empty) |
713
+
714
+ ### Examples
715
+
716
+ ```bash
717
+ sensecraft-cli data latest --eui 2CF7F12010700001
718
+ sensecraft-cli data latest --eui 2CF7F12010700001 --measurement-id 4104 --channel-index 32
719
+ ```
720
+
721
+ ### Response schema
722
+
723
+ | Field | Description |
724
+ |-------|-------------|
725
+ | `channel_index` | Channel number |
726
+ | `points` | Array of `{ measurement_value, measurement_id, time }` |
727
+
728
+ ---
729
+
730
+ ## data list
731
+
732
+ Get historical telemetry data for a device.
733
+
734
+ **OpenAPI:** `GET /list_telemetry_data`
735
+
736
+ ### Flags
737
+
738
+ | Flag | Required | Default | Description |
739
+ |------|----------|---------|-------------|
740
+ | `--eui` | **Yes** | — | Device EUI |
741
+ | `--measurement-id` | No | — | Measurement ID |
742
+ | `--channel-index` | No | — | Channel index |
743
+ | `--limit` | No | `0` | Number of records to return (`0` means API default) |
744
+ | `--time-start` | No | `0` | Start timestamp in **milliseconds** |
745
+ | `--time-end` | No | `0` | End timestamp in **milliseconds** |
746
+
747
+ ### Limits
748
+
749
+ - About **1 month** of data per request
750
+ - Only data within the last **three months** can be queried
751
+
752
+ ### Query parameters sent to API
753
+
754
+ | Parameter | Source |
755
+ |-----------|--------|
756
+ | `device_eui` | `--eui` |
757
+ | `measurement_id` | `--measurement-id` |
758
+ | `channel_index` | `--channel-index` |
759
+ | `limit` | `--limit` (only if > 0) |
760
+ | `time_start` | `--time-start` (only if > 0) |
761
+ | `time_end` | `--time-end` (only if > 0) |
762
+
763
+ ### Examples
764
+
765
+ ```bash
766
+ sensecraft-cli data list --eui 2CF7F12210400082 --limit 100
767
+ sensecraft-cli data list --eui 2CF7F12210400082 \
768
+ --measurement-id 4097 --channel-index 1 \
769
+ --time-start 1700000000000 --time-end 1700086400000 \
770
+ --limit 400
771
+ ```
772
+
773
+ ### Response schema
774
+
775
+ Columnar `list` structure: `list[0]` is `[channel_index, measurement_id]` pairs; `list[1]` is corresponding measurement series.
776
+
777
+ ---
778
+
779
+ ## data chart
780
+
781
+ Get aggregated telemetry chart points (interval averages).
782
+
783
+ **OpenAPI:** `GET /aggregate_chart_points`
784
+
785
+ ### Flags
786
+
787
+ | Flag | Required | Default | Description |
788
+ |------|----------|---------|-------------|
789
+ | `--eui` | **Yes** | — | Device EUI |
790
+ | `--measurement-id` | No | — | Measurement ID |
791
+ | `--channel-index` | No | — | Channel index |
792
+ | `--interval` | No | `60` | Interval length in **minutes** |
793
+ | `--time-start` | No | `0` | Start timestamp in **milliseconds** |
794
+ | `--time-end` | No | `0` | End timestamp in **milliseconds** |
795
+
796
+ ### Limits
797
+
798
+ - Time range: up to **1 year**
799
+ - Max **250** points per measurement (platform auto-rebins if exceeded)
800
+
801
+ ### Query parameters sent to API
802
+
803
+ | Parameter | Source |
804
+ |-----------|--------|
805
+ | `device_eui` | `--eui` |
806
+ | `measurement_id` | `--measurement-id` |
807
+ | `channel_index` | `--channel-index` |
808
+ | `interval` | `--interval` |
809
+ | `time_start` | `--time-start` (only if > 0) |
810
+ | `time_end` | `--time-end` (only if > 0) |
811
+
812
+ ### Examples
813
+
814
+ ```bash
815
+ sensecraft-cli data chart --eui 2CF7F12210400082
816
+ sensecraft-cli data chart --eui 2CF7F12210400082 \
817
+ --interval 60 --measurement-id 4106 --channel-index 1 \
818
+ --time-start 1700000000000 --time-end 1735689600000
819
+ ```
820
+
821
+ ### Response schema
822
+
823
+ | Field | Description |
824
+ |-------|-------------|
825
+ | `channel` | Channel number |
826
+ | `lists` | Array of `{ average_value, measurement_id, time }` |
827
+
828
+ ---
829
+
830
+ ## Common measurement IDs
831
+
832
+ Use with `--measurement-id`. Full list: SenseCAP appendix or `https://sensecap-statics.seeed.cn/refer/def/sensor.json`.
833
+
834
+ | ID | Measurement | Unit |
835
+ |----|-------------|------|
836
+ | `4097` | Air Temperature | ℃ |
837
+ | `4098` | Air Humidity | %RH |
838
+ | `4099` | Light Intensity | lux |
839
+ | `4100` | Barometric Pressure | hPa |
840
+ | `4101` | CO2 | ppm |
841
+ | `4104` | Soil Moisture | % |
842
+
843
+ Discover device-specific IDs via `device channels`.
844
+
845
+ ---
846
+
847
+ ## Error handling
848
+
849
+ | Scenario | Behavior |
850
+ |----------|----------|
851
+ | Missing config / Access Key | Error before API call; message mentions `sensecraft.json` |
852
+ | Missing required flag | Cobra validation error on stderr |
853
+ | API business error | `API error code=<code>: <msg>` |
854
+ | Invalid devkit SKU | Local validation error listing allowed SKUs |
855
+ | Invalid devkit EUI length | Local validation: must be 16 characters |
856
+ | Network failure | HTTP error on stderr |
857
+
858
+ SenseCAP error code list: https://sensecap-docs.seeed.cc/