@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 +112 -7
- package/dist/cutos.cjs.js +566 -38
- package/dist/cutos.esm.js +566 -38
- package/package.json +2 -2
- package/types/index.d.ts +2 -0
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
|
|
53
|
-
9. [
|
|
54
|
-
10. [
|
|
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
|
-
|
|
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
|
|
488
|
-
"version": "
|
|
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:
|