@nebulahome/integration-sdk 1.0.0 → 1.2.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 +29 -0
- package/FILES.md +73 -3
- package/README.md +3 -2
- package/dist/chunks/node-dist.js +1842 -100
- package/dist/chunks/node-index.d.ts +86 -10
- package/dist/chunks/node-project.js +2 -2
- package/dist/index.d.ts +19 -0
- package/dist/schemas.d.ts +71 -6
- package/dist/schemas.js +1 -1
- package/dist/testing.d.ts +20 -1
- package/dist/testing.js +22 -2
- package/package.json +3 -3
- package/schemas/discovery.schema.json +327 -5
- package/schemas/driver.schema.json +2 -1
- package/schemas/manifest.schema.json +16 -3
- package/schemas/profile.schema.json +114 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,35 @@
|
|
|
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.2.0
|
|
7
|
+
|
|
8
|
+
One device reached two ways.
|
|
9
|
+
|
|
10
|
+
- The manifest may say what makes two of the vendor's devices one, `"twins": ["mac"]` (or
|
|
11
|
+
`["mac", "serial"]`): a device added over the vendor's own transport and again through the
|
|
12
|
+
Matter broker is then offered to the owner to link, and becomes one device with two ways in.
|
|
13
|
+
- A profile's `identity` and `discovery.json`'s `identity` take `mac` and `serialNumber`, written
|
|
14
|
+
any way the device writes them; `discovery.json`'s `identity` also takes `auth`, where the device
|
|
15
|
+
says it is behind a password, which its row on the Found tab shows.
|
|
16
|
+
- An entity of a profile may carry `link`: its key in the transport's terms (`"switch:0"`), shown
|
|
17
|
+
beside the transport's name, and where the same reading sits in Matter
|
|
18
|
+
(`{ "endpoint": 1, "cluster": 6, "attribute": 0 }`), which links the two at once when the device
|
|
19
|
+
is linked.
|
|
20
|
+
|
|
21
|
+
## 1.1.0
|
|
22
|
+
|
|
23
|
+
Matter, and a wider grammar for conditions.
|
|
24
|
+
|
|
25
|
+
- A driver may run on the platform's `matter` transport with `"kind": "matter"`: the platform's
|
|
26
|
+
Matter mapping is its driver, with neither a profile nor code.
|
|
27
|
+
- `discovery.json` may say which of the house's Matter devices are the vendor's, in a `matter`
|
|
28
|
+
block of conditions on who each device says it is; `listen` may then be left out.
|
|
29
|
+
- Conditions, in claims and in `discovery.json`, take `endsWith`, `contains` (a part of a text, or
|
|
30
|
+
an item of a list) and `min` / `max` (a number in a range) beside `equals`, `exists`, `oneOf`
|
|
31
|
+
and `startsWith`.
|
|
32
|
+
- `identifyMatter(vendor, identity)` in `@nebulahome/integration-sdk/testing` says whether the
|
|
33
|
+
vendor's `matter` rules take a Matter device, and as which driver and model.
|
|
34
|
+
|
|
6
35
|
## 1.0.0
|
|
7
36
|
|
|
8
37
|
The first public release.
|
package/FILES.md
CHANGED
|
@@ -63,6 +63,15 @@ with `padding` (0 to 16, default 0): extra room, in pixels, the interface leaves
|
|
|
63
63
|
inside its tile. Every logo already gets a small margin; this is on top of it, for a mark drawn
|
|
64
64
|
to the very edge of its file. It cannot ask for less than the margin, only for more.
|
|
65
65
|
|
|
66
|
+
`twins` says what makes two of the vendor's devices **one device reached two ways**: `["mac"]`,
|
|
67
|
+
or `["mac", "serial"]` for both to agree. A Shelly added over its RPC and again through the Matter
|
|
68
|
+
broker is the same plug; with `twins`, the house compares what each said - the MAC and the serial
|
|
69
|
+
its `identity` reads, and its Matter identity's - and offers the owner to link them, when the
|
|
70
|
+
Matter node is added and as a suggestion on the vendor's page. Linked, it is one device with two
|
|
71
|
+
ways in: its readings come the way the owner prefers, and the other way carries them while that
|
|
72
|
+
one is silent. A vendor without `twins` is never offered a link. Each entity's `link` (below) says
|
|
73
|
+
which of its readings is which in Matter.
|
|
74
|
+
|
|
66
75
|
`requires` says what the vendor's devices need besides the hub, in the grammar a
|
|
67
76
|
package's manifest uses (PACKAGES.md §8, Dependencies):
|
|
68
77
|
`{ "services": ["mqtt-broker"] }` for Zigbee2MQTT, which talks through the house's broker, or a
|
|
@@ -118,10 +127,17 @@ the vendor's models by series, across its drivers - the series by name, the mode
|
|
|
118
127
|
counting order - and a device's page says its series where it would say the driver's name. A
|
|
119
128
|
model given no series is grouped under its driver. Every model named must be in `models`.
|
|
120
129
|
|
|
121
|
-
`transport` is a platform transport - `http`, `mqtt` - or one the driver's own vendor
|
|
122
|
-
named after the vendor: `shelly/rpc`. Never another vendor's: vendors load in no particular
|
|
130
|
+
`transport` is a platform transport - `http`, `mqtt`, `matter` - or one the driver's own vendor
|
|
131
|
+
ships, named after the vendor: `shelly/rpc`. Never another vendor's: vendors load in no particular
|
|
123
132
|
order, and a driver leaning on another's transport would load or not by luck.
|
|
124
133
|
|
|
134
|
+
A driver of the vendor's **Matter devices** is `"transport": "matter"` with `"kind": "matter"` and
|
|
135
|
+
neither a profile nor an entry: the platform's own Matter mapping runs it - lights, switches,
|
|
136
|
+
covers, locks, thermostats, the usual sensors, power and energy, the firmware - so the vendor's
|
|
137
|
+
Matter devices are its own, on its page, without code. Which devices those are its
|
|
138
|
+
`discovery.json` says (below), and `modelCodes` maps what they call their model - their product id,
|
|
139
|
+
unless the vendor says another field - onto the models it lists.
|
|
140
|
+
|
|
125
141
|
`defaultIcon` names the icon a device of this driver starts with, by its id in the platform's
|
|
126
142
|
icon catalogue (`packages/icons/catalogue.json` lists the platform's own ids - `light`,
|
|
127
143
|
`relay`, `printer`, `sensor`… - and every lucide icon is there under its own name). The owner
|
|
@@ -144,6 +160,14 @@ serves a family of models - and a state may be **looked up in a table** -
|
|
|
144
160
|
renames what a device says into what a capability accepts. A list is membership, not an `or`
|
|
145
161
|
between paths; a table renames and cannot compute.
|
|
146
162
|
|
|
163
|
+
A condition, in a claim or a `discovery.json`, may also ask that a text **start** or **end** with
|
|
164
|
+
something (`startsWith`, `endsWith`, without regard to case - a MAC address's maker is its first
|
|
165
|
+
three bytes), that a text or a list **contain** something (`contains`: a part of a text, without
|
|
166
|
+
regard to case, or one item of a list - `{ "path": "deviceTypes", "contains": 266 }`), or that a
|
|
167
|
+
number lie **in a range** (`{ "path": "softwareVersion", "min": 10 }`, both ends included). There
|
|
168
|
+
is no regular expression, on purpose: one written badly holds the hub's thread for as long as it
|
|
169
|
+
backtracks, and the grammar is what keeps a bundle of data from doing that.
|
|
170
|
+
|
|
147
171
|
A third form reads whether something is **there** -
|
|
148
172
|
`{ "path": "sys.available_updates.stable", "present": true }` - true when the path names a value,
|
|
149
173
|
false when the object that would hold it is there without it. It is the one read that turns an
|
|
@@ -168,6 +192,18 @@ on anything its device says, so it is available exactly when the device is, and
|
|
|
168
192
|
`"deviceClass": "restart"` the interface asks before pressing, since the device goes away for a
|
|
169
193
|
while.
|
|
170
194
|
|
|
195
|
+
An entity may carry **`link`**, for a vendor whose devices the house may also reach through the
|
|
196
|
+
Matter broker (`twins`, above): `"link": { "key": "switch:0", "matter": { "endpoint": 1,
|
|
197
|
+
"cluster": 6, "attribute": 0 } }`. `key` is the entity's name in the transport's terms, shown on
|
|
198
|
+
its page beside the transport's name; `matter` is where the same reading sits in Matter - the
|
|
199
|
+
endpoint, the cluster and the attribute the platform's Matter mapping reads it from (the first
|
|
200
|
+
cluster and attribute of an entity it reads from several: 0 for a light). When the device is
|
|
201
|
+
linked, an entity whose `matter` names a Matter entity of the twin is linked to it at once,
|
|
202
|
+
whatever it is; a sensor without one is linked when exactly one Matter sensor reads the same
|
|
203
|
+
thing, and a control never without one. The identity's `mac` and `serialNumber` are what the twin
|
|
204
|
+
is found by: `"identity": { "externalId": "id", "mac": "mac" }`, written any way the device writes
|
|
205
|
+
it.
|
|
206
|
+
|
|
171
207
|
An entity may report **attributes** beside its state: `"attributes": { "endsAt":
|
|
172
208
|
"pairing.endsAt" }`, each a camelCase key read the way a state field is, into a scalar. They are
|
|
173
209
|
for what a page needs of the entity and the entity itself is not - the Zigbee2MQTT bridge's
|
|
@@ -260,7 +296,9 @@ because a device announced it there.
|
|
|
260
296
|
- `identity` - paths to the model code, the id, the name and the firmware version. Only the model
|
|
261
297
|
is ever required. A field may be a list of paths, tried in order, for generations that answer
|
|
262
298
|
in different words: a Shelly Gen1 says `type`, `mac` and `fw` where later ones say `model`,
|
|
263
|
-
`id` and `ver`.
|
|
299
|
+
`id` and `ver`. `mac` and `serialNumber` are what the Found tab shows and a twin is told by
|
|
300
|
+
(`twins`), and `auth` is where the device says it is behind a password - `["auth_en", "auth"]`
|
|
301
|
+
on a Shelly - which its row shows before anyone tries to add it.
|
|
264
302
|
- `adopt` - who adds a device found: `owner` (the default) proposes it on the vendor's
|
|
265
303
|
page to adopt; `automatic` has `api` add it as soon as the hub proposes it, named as it named
|
|
266
304
|
itself, with the id the add form would have offered - for devices the owner already chose
|
|
@@ -295,6 +333,38 @@ driver takes is not proposed, and the hub logs its model once at info: it is the
|
|
|
295
333
|
my device not found". A `discovery.json` that does not load leaves the vendor loaded without discovery, and the
|
|
296
334
|
failure names the file.
|
|
297
335
|
|
|
336
|
+
**Matter devices.** The house's Matter devices are commissioned on the platform's Brokers page,
|
|
337
|
+
with the code the maker's app - or Google Home, Apple Home, Alexa - shares, and each is then added
|
|
338
|
+
at once to the vendor whose `matter` rules take it:
|
|
339
|
+
|
|
340
|
+
```json
|
|
341
|
+
{
|
|
342
|
+
"matter": {
|
|
343
|
+
"match": [{ "path": "vendorId", "equals": 5264 }],
|
|
344
|
+
"model": "productId"
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
- `match` - at least one condition, all of which must hold of who the device says it is: its
|
|
350
|
+
`vendorId` and `productId` (numbers), `vendorName`, `productName`, `productLabel`, `nodeLabel`,
|
|
351
|
+
`serialNumber`, `uniqueId`, `hardwareVersion`, `softwareVersion` (numbers) and their `…String`
|
|
352
|
+
texts, `macAddresses` (a list of `aa:bb:cc:dd:ee:ff`), `deviceTypes` and `clusters` (lists of
|
|
353
|
+
numbers), `isBridge` and `isBridged`. A field the device does not say is `null`. The vendor id is
|
|
354
|
+
the one to rule on: the CSA assigns it to the maker, and it does not change with a name.
|
|
355
|
+
- `model` - where the device says its model, looked up in the `modelCodes` of the vendor's drivers
|
|
356
|
+
that say `"kind": "matter"`; `productId` when absent. A model no driver maps goes to the vendor's
|
|
357
|
+
Matter driver when it has only one. Matter devices are added on their own, with no one to pick a
|
|
358
|
+
model: a Matter driver that lists models must map every product in `modelCodes`, or a product
|
|
359
|
+
it misses is never added. A driver that lists none takes them all, under its own name.
|
|
360
|
+
|
|
361
|
+
A vendor may have `matter` alone, with no `listen`. A device behind a Matter bridge is a device of
|
|
362
|
+
its own, ruled on by what the bridge says of it. A device that more than one vendor's rules take,
|
|
363
|
+
and one that none takes, is added as the platform's own Matter device, and the Brokers page says
|
|
364
|
+
which vendors want it. One added as the platform's before the vendor was installed becomes the
|
|
365
|
+
vendor's once it is, with its entities. Removing a Matter device from the house takes it off the
|
|
366
|
+
house's fabric; it stays in the other apps it was shared from.
|
|
367
|
+
|
|
298
368
|
**A listener of the vendor's own** is a module - plain JavaScript, like a transport, handed the
|
|
299
369
|
same SDK - whose default export returns `{ listen(signal, context), scan?() }`: an async iterable
|
|
300
370
|
of sightings, `{ config: { host }, payload }`, reported as they happen until the signal ends it,
|
package/README.md
CHANGED
|
@@ -85,7 +85,8 @@ light.receive(stateJson); // → state reports
|
|
|
85
85
|
light.command('light.device', 'on_off', { command: 'turn_on' }); // → the HTTP request
|
|
86
86
|
```
|
|
87
87
|
|
|
88
|
-
`identify` says what discovery makes of a device heard,
|
|
88
|
+
`identify` says what discovery makes of a device heard, `identifyMatter` what the vendor's `matter`
|
|
89
|
+
rules make of one of the house's Matter devices, and `createFakeSdk` is the SDK handed to
|
|
89
90
|
the code, recording what it logged and sent: its UDP sockets and WebSockets connect to nothing, and
|
|
90
91
|
a test opens, delivers to and drops them.
|
|
91
92
|
|
|
@@ -103,7 +104,7 @@ built with it declares `^<major>.<minor>.0`. The full guide is `INTEGRATIONS_DOC
|
|
|
103
104
|
## Releasing the SDK
|
|
104
105
|
|
|
105
106
|
For the platform's maintainers. The hub reads the contract's version from this `package.json`, so
|
|
106
|
-
the version is raised by hand
|
|
107
|
+
the version is raised by hand:
|
|
107
108
|
|
|
108
109
|
- **patch** - a fix, or a change to the command, the tests' helpers or the documentation that
|
|
109
110
|
leaves what a bundle can use as it is. Bundles keep declaring `^<major>.<minor>.0`, so it is
|