@nebulahome/integration-sdk 1.4.0 → 1.6.0

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/CHANGELOG.md CHANGED
@@ -3,6 +3,41 @@
3
3
  The SDK's version is the version of the integration contract the platform implements: a minor
4
4
  version adds to the contract, a major one breaks it, and a patch leaves it as it is.
5
5
 
6
+ ## 1.6.0
7
+
8
+ Serial ports, Bluetooth, IR blasters and Bluetooth proxies.
9
+
10
+ - A driver may be `"kind": "serial"`: code on a transport of the vendor's own, with a `serial`
11
+ block saying how its port is spoken (`{ "baudRate": 2400 }`, 8N1 unless said). Adding a device
12
+ asks for the port, and `sdk.openSerial(portId, line)` opens it through the platform's Serial
13
+ broker, which gives every port one holder.
14
+ - A driver may be `"kind": "bluetooth"`: code on the platform's `bluetooth` transport, its devices
15
+ the addresses the house hears, added from the Bluetooth broker's Found or Nearby; its requests
16
+ are GATT on the server's own adapter (`BLUETOOTH_GATT_OPS`).
17
+ - `discovery.json` may say which serial ports (`serial`, rules on the USB adapter's strings) and
18
+ which Bluetooth devices (`bluetooth`, rules on an advertisement) are the vendor's; `listen` may
19
+ then be left out.
20
+ - A declarative profile may say its device is an IR blaster (`infrared: { signals, receives }`) or
21
+ a Bluetooth proxy (`bluetoothProxy: { modes }`), and the vendor's transport then answers the
22
+ reserved ops the brokers send over the device's connection: `INFRARED_OPS` and
23
+ `BLUETOOTH_PROXY_OPS`, exported with their arguments' and answers' types.
24
+ - `sdk.bluetooth.scanner({ key, deviceKey })` is a proxy's channel to the Bluetooth broker for the
25
+ advertisements it hears, and `sdk.codecs.infrared` is the platform's infrared codec: Broadlink,
26
+ Pronto, raw timings, Flipper Zero `.ir` files, and NEC, Samsung32, Sony SIRC and RC5.
27
+ - `identifySerial` and `identifyBluetooth` in `@nebulahome/integration-sdk/testing` say what the
28
+ vendor's rules take; `createFakeSdk()` opens serial ports a test feeds and reads
29
+ (`serialPorts`), keeps what a proxy's scanner reports (`bluetoothScanners`) and hands over the
30
+ real infrared codec.
31
+
32
+ ## 1.5.0
33
+
34
+ A Modbus template's entities say their icon, and its units are the platform's.
35
+
36
+ - An entity of a Modbus template may name its `icon`, a catalogue icon id; the domain's is used
37
+ when it does not.
38
+ - A read's `unit` must be one the platform knows - a unit of one of its sensor classes (`W`,
39
+ `kWh`, `°C`) - and a template with another is refused when it is checked.
40
+
6
41
  ## 1.4.0
7
42
 
8
43
  The house's Modbus client is the platform's.
package/FILES.md CHANGED
@@ -128,7 +128,7 @@ the vendor's models by series, across its drivers - the series by name, the mode
128
128
  counting order - and a device's page says its series where it would say the driver's name. A
129
129
  model given no series is grouped under its driver. Every model named must be in `models`.
130
130
 
131
- `transport` is a platform transport - `http`, `mqtt`, `matter`, `mqtt-house`, `modbus` - or one the driver's own vendor
131
+ `transport` is a platform transport - `http`, `mqtt`, `matter`, `mqtt-house`, `modbus`, `bluetooth` - or one the driver's own vendor
132
132
  ships, named after the vendor: `shelly/rpc`. Never another vendor's: vendors load in no particular
133
133
  order, and a driver leaning on another's transport would load or not by luck.
134
134
 
@@ -189,11 +189,13 @@ duplicate:
189
189
  - Each entity is a `domain` - `sensor`, `binary_sensor`, `switch`, `light`, `number`, `select`,
190
190
  `button` - and its capabilities: a sensor `sensor_numeric` or `sensor_text`, a binary sensor
191
191
  `sensor_binary`, a switch `on_off`, a light `on_off` and maybe `level`, the others their own.
192
- `id` is what the entity stays when it is renamed; give every one.
192
+ `id` is what the entity stays when it is renamed; give every one. `icon`, a catalogue icon id,
193
+ is the one it starts with - the domain's when left out.
193
194
  - `read`: `function` 1 (coils), 2 (discrete inputs), 3 (holding registers) or 4 (input registers);
194
195
  `address`, a number or `"0x…"`; for registers a `type` - `u16` (the default), `s16`, `u32`, `s32`,
195
196
  `f32`, or `string` with a `count` of registers - a `bit` for an on/off value, a `scale` (`0.1`
196
- for tenths), a `unit`, and `options` naming what each raw number means (`{ "0": "Off" }`, which
197
+ for tenths), a `unit` the platform knows (`W`, `kWh`, `°C`: those of the sensor classes, an
198
+ unknown one is refused), and `options` naming what each raw number means (`{ "0": "Off" }`, which
197
199
  a select needs).
198
200
  - `write`: `function` 5 (one coil), 6 (one register), 15 (coils) or 16 (registers - a 32-bit value
199
201
  needs it); `address`, the read's when left out; `on` and `off` for a switch; `min`, `max` and
@@ -203,6 +205,54 @@ The rules that tie these together - a number is not read from coils, a coil is n
203
205
  06, a table read with 02 or 04 cannot be written back without an address - are checked when the
204
206
  bundle loads, with the words the editor uses.
205
207
 
208
+ A driver of the vendor's **serial devices** - a UPS on a USB cable, a meter on an RS485 adapter -
209
+ is code (`"kind": "serial"` with an `entry`) on a transport of the vendor's own, and says how its
210
+ port is spoken:
211
+
212
+ ```json
213
+ {
214
+ "id": "ups",
215
+ "name": "UPS",
216
+ "transport": "acme/line",
217
+ "kind": "serial",
218
+ "serial": { "baudRate": 2400 },
219
+ "entry": "./index.js",
220
+ "setup": "./setup.json"
221
+ }
222
+ ```
223
+
224
+ - `serial` - `baudRate`, then `dataBits` (5 to 8, 8 unless said), `parity` (`none`, `even`, `odd`,
225
+ `mark`, `space`; `none`), `stopBits` (1, 1.5 or 2; 1) and `flowControl` (`none`, `rtscts`,
226
+ `xonxoff`; `none`): `9600 8N1` is `{ "baudRate": 9600 }`. Required of a serial driver, refused on
227
+ any other.
228
+ - Adding a device asks for the port - the free ones, those the vendor's `serial` rules recognise
229
+ first (below) - and the line, the driver's preselected, before the driver's own fields. The
230
+ device's transport configuration then carries `serial: { portId, line }` beside what its
231
+ `setup.json` asks: the transport's `configSchema` takes it, its `connectionKey` is the port, and
232
+ it opens it with `sdk.openSerial(config.serial.portId, config.serial.line)`.
233
+ - A port has one holder - a device, the Thread broker, the owner's console, a container - and the
234
+ hub gives the device its port when its instance starts. One another holder has stays with it:
235
+ `openSerial` rejects with an error named `SerialPortHeld`, and the Brokers page shows the two as
236
+ a conflict. No such port, or one unplugged, is `SerialPortMissing`. A port is open once:
237
+ opening it again while it is open is `SerialPortHeld` too.
238
+ - The session hands over bytes as the port reads them - a chunk is not a message, so a protocol
239
+ framed by lines or lengths puts them together itself - and `onClose` hears the port go,
240
+ unplugged or taken back; a write after that rejects with `SerialClosed`. A port on the network
241
+ (raw TCP, RFC 2217) is opened the same way.
242
+
243
+ A driver of the vendor's **Bluetooth devices** is code (`"kind": "bluetooth"` with an `entry`) on
244
+ the platform's `bluetooth` transport, `"transport": "bluetooth"`. Its devices are never added by
245
+ address: the owner adds one from the Bluetooth broker's Found or Nearby, and its device key is its
246
+ address, upper case. Its claim reads `{ deviceKey, kind, name, advert }`, the advertisement it was
247
+ recognised from; it follows its address with the subscription `{ "op": "follow", "args": {
248
+ "address": "…" } }` and is delivered each advertisement heard from it, by the server's adapter or
249
+ any proxy - one carrying the same name, maker's and service data at most once a minute. Its
250
+ requests are GATT on the server's own adapter: `gatt.read { service, characteristic }` answers `{
251
+ data }`, `gatt.write { service, characteristic, data, withResponse }`, `gatt.notify { service,
252
+ characteristic, isOn }`, whose values are delivered as `{ service, characteristic, data }` - hex
253
+ throughout. They are refused when the server has no usable adapter, or only proxies hear the
254
+ device: proxies listen and never connect. `BLUETOOTH_GATT_OPS` names them.
255
+
206
256
  `defaultIcon` names the icon a device of this driver starts with, by its id in the platform's
207
257
  icon catalogue (`packages/icons/catalogue.json` lists the platform's own ids - `light`,
208
258
  `relay`, `printer`, `sensor`… - and every lucide icon is there under its own name). The owner
@@ -472,6 +522,54 @@ removed, the servers found are asked again.
472
522
  - `model` - where the server says its model, looked up in the `modelCodes` of the vendor's drivers
473
523
  that say `"kind": "modbus"`; `values.model` when absent.
474
524
 
525
+ **Serial ports.** The server sees every serial port plugged into it - by the strings its USB
526
+ adapter gives - and every port on the network the owner added. A port is the vendor's when its
527
+ `serial` rules take it, and the Serial broker's page then suggests it, "Use with …?": the owner adds
528
+ the device, nothing is taken on its own. A port recognised as a Thread radio is suggested as one by
529
+ the platform.
530
+
531
+ ```json
532
+ {
533
+ "serial": {
534
+ "match": [
535
+ { "path": "vendorId", "equals": "0665" },
536
+ { "path": "product", "startsWith": "USB to Serial" }
537
+ ],
538
+ "model": "product"
539
+ }
540
+ }
541
+ ```
542
+
543
+ - `match` - at least one condition, all of which must hold of the adapter: `vendorId` and
544
+ `productId` (four lower-case hex digits, `10c4`), `manufacturer`, `product` and `serialNumber`
545
+ (`null` when the adapter does not say).
546
+ - `model` - where the adapter says its model, looked up in the `modelCodes` of the vendor's drivers
547
+ that say `"kind": "serial"`; `product` when absent.
548
+
549
+ **Bluetooth devices.** The house hears every device advertising near the server's adapter and its
550
+ Bluetooth proxies. One is the vendor's when its `bluetooth` rules take an advertisement of it, and
551
+ it is listed for the vendor on the Bluetooth broker's Found tab; the owner adds it - a neighbour's
552
+ sensor is heard as well as the house's own. The platform recognises BTHome sensors itself.
553
+
554
+ ```json
555
+ {
556
+ "bluetooth": {
557
+ "match": [{ "path": "manufacturerData.'2985'", "startsWith": "0a" }],
558
+ "model": "name"
559
+ }
560
+ }
561
+ ```
562
+
563
+ - `match` - at least one condition, all of which must hold of one advertisement: `address` (upper
564
+ case), `addressType` (`public`, `random`), `rssi`, `name`, `manufacturerData.'<company id>'` -
565
+ the id in decimal, the bytes after it in lower-case hex, read with `startsWith` or `exists` -
566
+ `serviceUuids` (a list, read with `contains`) and `serviceData.'<uuid>'` (read with `exists`).
567
+ UUIDs are lower case, a 16-bit one short: `fcd2`.
568
+ - `model` - where the advertisement says its model, looked up in the `modelCodes` of the vendor's
569
+ drivers on the `bluetooth` transport; `name` when absent.
570
+
571
+ A vendor may have `serial` or `bluetooth` alone, with no `listen`.
572
+
475
573
  A vendor may have `mqtt` alone, with no `listen`. A device that more than one vendor's rules take,
476
574
  and one that none takes, is added as the platform's own MQTT device, and one added so before the
477
575
  vendor was installed becomes the vendor's once it is.
@@ -752,11 +850,14 @@ import them:
752
850
  | `openUdpSocket` | a UDP socket the hub binds, joins to a multicast group, and closes with the vendor |
753
851
  | `openMqtt` | an MQTT session with a client certificate, for a vendor's own broker |
754
852
  | `openModbus` | a Modbus session through the hub's one connection to a server, closed with the vendor |
853
+ | `openSerial` | a serial port a device of the vendor holds, through the Serial broker |
854
+ | `bluetooth.scanner` | a Bluetooth proxy's channel to the Bluetooth broker, for what it hears |
755
855
  | `defineStreamSource` | the contract a camera's stream source is written against |
756
856
  | `openRtsp` | an RTSP(S) session over TCP, yielding a camera's H.264 as it comes |
757
857
  | `platform.mqtt` | the house's MQTT broker the hub runs, with the hub's username; null if it cannot |
758
858
  | `defineAccount` | the contract an account's sign-in module is written against |
759
859
  | `codecs.lzma` | unpacks an LZMA stream in the alone format, as some clouds pack maps |
860
+ | `codecs.infrared` | infrared and radio codes: Broadlink, Pronto, raw timings, Flipper `.ir`, protocols |
760
861
  | `images.png` | encodes a picture of a palette as a PNG, for an image entity |
761
862
  | `logger` | the hub's logger, for what happens outside a connection |
762
863
 
@@ -775,6 +876,97 @@ both. It is **code**, so the vendor sits at the tier a code driver does - review
775
876
  catalogue carries it; `verifyVendor` is where the hub asks. Its types come from
776
877
  `@nebulahome/integration-sdk`, and `pnpm typecheck` holds it to them.
777
878
 
879
+ ## A device that plays a broker's role
880
+
881
+ A device of the vendor may work for one of the platform's brokers: an **IR blaster** sends the
882
+ codes of the remotes the Infrared broker keeps, a **Bluetooth proxy** listens for the Bluetooth
883
+ broker. Its driver's profile says so - only a declarative profile can - and the vendor's page shows
884
+ the role:
885
+
886
+ ```json
887
+ {
888
+ "entities": [ … ],
889
+ "infrared": { "signals": ["ir", "rf"], "receives": true },
890
+ "bluetoothProxy": { "modes": ["passive", "active"] }
891
+ }
892
+ ```
893
+
894
+ The broker then sends the device **reserved ops** over its instance's own connection, as a command
895
+ would go: `connection.send({ deviceKey, op, args }, signal)`, `deviceKey` the instance's first bound
896
+ claim's and `signal` aborted at the op's timeout. The vendor's transport answers them in `send`:
897
+ it resolves with the answer, or throws an error whose message is a sentence the page shows. The
898
+ names are reserved - a vendor uses them for nothing else - and exported as `INFRARED_OPS` and
899
+ `BLUETOOTH_PROXY_OPS`, their arguments' types beside them:
900
+
901
+ ```ts
902
+ send: async (request, signal) => {
903
+ switch (request.op) {
904
+ case BLUETOOTH_PROXY_OPS.state:
905
+ return proxyState(request.deviceKey, signal); // BluetoothProxyState
906
+ case BLUETOOTH_PROXY_OPS.filter:
907
+ return forward(request.deviceKey, request.args as BluetoothProxyFilterArgs);
908
+ // … the device's own requests
909
+ }
910
+ },
911
+ ```
912
+
913
+ **An IR blaster** declares `infrared: { signals: ["ir"] | ["ir", "rf"], receives }` - the signals it
914
+ sends, and whether it can learn. It is online while its instance is running. Codes cross the ops in
915
+ the platform's shape, `InfraredCode` - `{ signal, carrierHz, frequencyHz?, pulses, protocol? }`, the
916
+ pulses in microseconds, a mark then a space in turn, starting with a mark; an RF code's `carrierHz`
917
+ is 0 and its `frequencyHz` says the band - and the vendor converts to and from its own format with
918
+ `sdk.codecs.infrared`: `decodeBroadlink` / `encodeBroadlink`, `decodePronto` / `encodePronto`
919
+ (learned Pronto hex; `null` for RF), `decodeRawTimings` / `encodeRawTimings`, `parseFlipperIr` (a
920
+ Flipper Zero `.ir` file, its parsed and raw entries), `decodeInfraredProtocol`,
921
+ `encodeInfraredProtocol` and `withInfraredProtocol` (NEC and its extended form, Samsung32, Sony SIRC
922
+ 12/15/20, RC5). A code that does not hold throws a `ValidationError`.
923
+
924
+ | Op | Arguments | The hub waits | Answer |
925
+ | ----------------- | ----------------------- | ----------------- | ----------------------------------------------------- |
926
+ | `infrared.send` | `{ code }` | 10 s | resolve once sent |
927
+ | `infrared.learn` | `{ signal, timeoutMs }` | `timeoutMs` + 5 s | a code of that signal; reject when nothing came |
928
+ | `infrared.sweep` | `{ timeoutMs }` | `timeoutMs` + 5 s | `{ frequencyHz }`, RF only, asked before an RF learn |
929
+ | `infrared.cancel` | `{}` | 10 s | stop the learn or sweep under way, which then rejects |
930
+
931
+ A learned code needs no protocol, nor an RF one its frequency: the hub adds what it recognises and
932
+ what the sweep found. A learn that rejects with an error named `TimeoutError` or `AbortError`, or
933
+ at or after `timeoutMs`, reads "Nothing reached the blaster in 30 s." on the page; any other shows
934
+ its message.
935
+
936
+ **A Bluetooth proxy** declares `bluetoothProxy: { modes }`, the scan modes it can run, `passive`
937
+ and `active`, each once.
938
+
939
+ | Op | Arguments | The hub waits | Answer |
940
+ | ------------------------- | --------------- | ------------- | --------------------------------------------------------- |
941
+ | `bluetooth-proxy.state` | `{}` | 10 s | `BluetoothProxyState`; anything else counts as no answer |
942
+ | `bluetooth-proxy.install` | `{ mode }` | 60 s | install the script, or update it, and run it in that mode |
943
+ | `bluetooth-proxy.remove` | `{}` | 10 s | stop the script and remove it; throw to refuse |
944
+ | `bluetooth-proxy.filter` | `{ addresses }` | 10 s | forward those addresses from now on |
945
+
946
+ - `state` answers `{ eligible: true, installed, version?, shipped, running }` - the script on the
947
+ device, the one the vendor ships now, whether it runs - or `{ eligible: false, reason, update? }`,
948
+ the reason `gen1`, `battery`, `firmware` or `no-bluetooth`, and `update` whether a firmware update
949
+ the device offers would make it eligible. The hub asks it for the list of devices that could be
950
+ proxies, when the device's scanner opens, and after an install, a second apart until it says
951
+ `running`. The script is outdated when `version` and `shipped` are both strict semver and
952
+ `version` is the lower, otherwise whenever they differ.
953
+ - `install` is also how the owner changes the mode and updates the script; a throw fails the job
954
+ with its message.
955
+ - `filter` is `"all"` while somebody has Nearby open, otherwise the house's devices, those being
956
+ added and those a rule recognises - upper case, sorted, 4096 at most. It comes at the hub's
957
+ start, when the scanner opens, on every change and again every five minutes. Keep only the last
958
+ one; a script that restarted forwards nothing until it is told again.
959
+
960
+ What the proxy hears reaches the house through `sdk.bluetooth.scanner({ key, deviceKey })`: `key`
961
+ is the instance connection's key and `deviceKey` the device's on it, or the hub cannot tell which
962
+ proxy reports. Open it when the connection comes up, close it with the connection; opening it again
963
+ replaces the first. `report(adverts)` takes 1024 `BluetoothAdvertInput`s at most a call, each `{
964
+ address, addressType, rssi, name?, manufacturerData?, serviceData?, serviceUuids?, at }` - the
965
+ address in either case, `rssi` a whole number of dBm, the company ids in decimal, hex in either
966
+ case, a 128-bit UUID on the Bluetooth base shortened by the hub. One that does not hold is dropped.
967
+ `report([])` says the proxy is alive: report at least every two minutes, or it shows offline. A
968
+ device the owner did not make a proxy is not listened to.
969
+
778
970
  ## A camera's picture
779
971
 
780
972
  A camera's live picture is not state and goes through no transport: it is frames, for as long
package/README.md CHANGED
@@ -33,7 +33,8 @@ Every JSON file names its schema, so the editor checks it as it is typed:
33
33
  ```
34
34
 
35
35
  `FILES.md`, beside this file, says what each of them holds in full - discovery, accounts, setup
36
- forms, the profile's grammar and its limits, firmware updates, cameras and pictures.
36
+ forms, the profile's grammar and its limits, firmware updates, serial and Bluetooth devices, IR
37
+ blasters and Bluetooth proxies, cameras and pictures.
37
38
 
38
39
  ## The command
39
40
 
@@ -87,9 +88,11 @@ light.command('light.device', 'on_off', { command: 'turn_on' }); // → the HTTP
87
88
 
88
89
  `identify` says what discovery makes of a device heard, `identifyMatter` what the vendor's `matter`
89
90
  rules make of one of the house's Matter devices, `identifyMqtt` what its `mqtt` rules make of a
90
- device the house's MQTT broker hears, and `createFakeSdk` is the SDK handed to
91
- the code, recording what it logged and sent: its UDP sockets and WebSockets connect to nothing, and
92
- a test opens, delivers to and drops them.
91
+ device the house's MQTT broker hears, `identifyModbus`, `identifySerial` and `identifyBluetooth` the
92
+ same of a Modbus server, a serial port and a Bluetooth advertisement, and `createFakeSdk` is the
93
+ SDK handed to the code, recording what it logged and sent: its UDP sockets, WebSockets and serial
94
+ ports connect to nothing, and a test opens, delivers to and drops them; a proxy's Bluetooth scanner
95
+ keeps what it reported.
93
96
 
94
97
  ## Releasing
95
98