@cutos/core 4.0.7 → 4.0.9

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.md CHANGED
@@ -49,9 +49,11 @@ Hardware Device/Driver APIs remain available as the compatibility layer, but new
49
49
  5. [Notification API](#notification-api)
50
50
  6. [Logger API](#logger-api)
51
51
  7. [Error Model](#error-model)
52
- 8. [Capability Contract](#capability-contract)
53
- 9. [Mock Dev](#mock-dev)
54
- 10. [Documentation](#documentation)
52
+ 8. [Device Capability Base](#device-capability-base)
53
+ 9. [Device Provider Base](#device-provider-base)
54
+ 10. [Capability Contract](#capability-contract)
55
+ 11. [Core Simulator](#core-simulator)
56
+ 12. [Documentation](#documentation)
55
57
 
56
58
  # Quick Start
57
59
 
@@ -93,15 +95,47 @@ import { CoreAPI, CutosMock } from "@cutos/core"
93
95
 
94
96
  CutosMock.install({
95
97
  capabilities: {
96
- "hello-device": {
98
+ demo: {
97
99
  methods: {
98
- echo: params => params
100
+ echo: params => ({ message: params.message })
99
101
  }
100
102
  }
101
103
  }
102
104
  })
103
105
 
104
106
  await CoreAPI.init("mock")
107
+
108
+ const demo = new CoreClass.Capability("demo")
109
+ const result = await demo.call("echo", { message: "hello" })
110
+ ```
111
+
112
+ `CutosMock.install()` connects the existing `Capability`, `Provider`, `DeviceCapabilityBase`, and `DeviceProviderBase` classes to an in-memory transport. Capability names must match exactly. Device Base classes derive `capability.device.<deviceType>` automatically.
113
+
114
+ ```ts
115
+ CutosMock.install()
116
+ await CoreAPI.init("mock")
117
+
118
+ class HelloProvider extends DeviceProviderBase {
119
+ connect() {
120
+ this.setStatus("online")
121
+ return { connected: true }
122
+ }
123
+
124
+ disconnect() {
125
+ this.setStatus("offline")
126
+ return { connected: false }
127
+ }
128
+
129
+ readDeviceInfo() {
130
+ return { deviceType: this.deviceType }
131
+ }
132
+ }
133
+
134
+ const provider = new HelloProvider("hello")
135
+ const device = new DeviceCapabilityBase("hello")
136
+
137
+ await device.init()
138
+ await device.connect()
105
139
  ```
106
140
 
107
141
  For simple UI development, set the CUTOS host to `mock` and keep application code unchanged:
@@ -414,6 +448,47 @@ The third argument is optional and defaults to `LWA`.
414
448
  logger.info("hello-provider", "started", "Provider")
415
449
  ```
416
450
 
451
+ # Device Capability Base
452
+
453
+ `DeviceCapabilityBase` is the consumer-side base used by a Device Capability SDK. It derives the Capability identity from the raw `deviceType` and supplies the standard Device API:
454
+
455
+ - `init()`
456
+ - `connect()`
457
+ - `disconnect()`
458
+ - `readDeviceInfo()`
459
+ - `onData()`
460
+ - `onStatus()`
461
+ - `onError()`
462
+
463
+ Concrete SDK classes add only device-specific extension methods:
464
+
465
+ ```ts
466
+ class PrinterCapability extends DeviceCapabilityBase {
467
+ constructor(options = {}) {
468
+ super("printer", options)
469
+ }
470
+
471
+ printText(params) {
472
+ return this.call("printText", params)
473
+ }
474
+ }
475
+
476
+ const printer = new PrinterCapability()
477
+ await printer.init()
478
+ await printer.connect()
479
+
480
+ const info = await printer.readDeviceInfo()
481
+ const offData = printer.onData(data => console.log(data))
482
+ const offStatus = printer.onStatus(status => console.log(status))
483
+ const offError = printer.onError(error => console.error(error))
484
+
485
+ offData()
486
+ offStatus()
487
+ offError()
488
+ ```
489
+
490
+ `onStatus()` receives both Provider status events and Runtime heartbeat status. Consumers should inspect the received payload rather than assuming every heartbeat message is a Device state transition.
491
+
417
492
  # Device Provider Base
418
493
 
419
494
  `DeviceProviderBase` automatically registers the standard `connect`, `disconnect`, and `readDeviceInfo` Capability methods. A concrete device Provider overrides those methods and registers only its device-specific extensions:
@@ -450,6 +525,22 @@ class PrinterProvider extends DeviceProviderBase {
450
525
 
451
526
  The Base implementations throw `DEVICE_CONNECT_NOT_IMPLEMENTED`, `DEVICE_DISCONNECT_NOT_IMPLEMENTED`, and `DEVICE_INFO_NOT_IMPLEMENTED`. This makes an incomplete Provider fail explicitly instead of leaving a standard method unregistered.
452
527
 
528
+ Provider helpers map directly to Device Capability events and Runtime health reporting:
529
+
530
+ ```ts
531
+ this.emitData({ paper: "ready" })
532
+ this.setStatus("online", { port: "COM3" })
533
+ this.emitError(new CutosError("PRINTER_ERROR", "Printer failed"))
534
+
535
+ this.setBeatInterval(3000)
536
+ this.startBeat()
537
+ ```
538
+
539
+ - `emitData(data)` emits the standard `data` event.
540
+ - `setStatus(status, info)` emits the standard `status` event and updates heartbeat state.
541
+ - `emitError(error)` normalizes the error, emits `error`, and marks heartbeat state as failed.
542
+ - `startBeat()` registers and starts the Provider heartbeat. Calling it more than once is safe.
543
+
453
544
  # Error Model
454
545
 
455
546
  CUTOS 4.0 normalizes SDK errors to `CutosError`.
@@ -484,8 +575,8 @@ Capabilities should be described by `capability.contract.json`.
484
575
  ```json
485
576
  {
486
577
  "schemaVersion": "0.1",
487
- "name": "hello-device",
488
- "version": "1.0.0",
578
+ "name": "capability.device.hello",
579
+ "version": "4.0.0",
489
580
  "type": "device",
490
581
  "methods": {},
491
582
  "events": {},
@@ -496,6 +587,20 @@ Capabilities should be described by `capability.contract.json`.
496
587
 
497
588
  Contracts are the source of truth for future SDK generation, Provider stubs, documentation, tests, permissions, and AI tool schemas.
498
589
 
590
+ # Core Simulator
591
+
592
+ `CoreSimulator` is a lightweight compatibility helper for testing legacy Driver initialization against an MQTT broker. It connects to `ws://localhost:<port>` and handles the default Device `init` command:
593
+
594
+ ```ts
595
+ CoreSimulator.start({
596
+ init(args) {
597
+ console.log("Driver init", args)
598
+ }
599
+ }, 1883)
600
+ ```
601
+
602
+ Use `CutosMock` for normal LWA and Capability UI development. `CoreSimulator` requires a compatible MQTT broker and is not a replacement for full CUTOS Runtime verification.
603
+
499
604
  # Documentation
500
605
 
501
606
  Full CUTOS 4.0 SDK API guide: