@nebulahome/integration-sdk 1.7.0 → 1.9.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 +33 -0
- package/FILES.md +75 -9
- package/dist/chunks/node-dist.js +122 -8
- package/dist/chunks/node-index.d.ts +183 -8
- package/dist/chunks/node-project.js +1 -1
- package/dist/index.d.ts +40 -4
- package/dist/index.js +3 -1
- package/dist/schemas.d.ts +150 -9
- package/dist/testing.d.ts +12 -0
- package/dist/testing.js +47 -2
- package/package.json +5 -5
- package/schemas/discovery.schema.json +558 -180
- package/schemas/manifest.schema.json +10 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,39 @@
|
|
|
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.9.0
|
|
7
|
+
|
|
8
|
+
A device whose entities depend on how it is set up.
|
|
9
|
+
|
|
10
|
+
- A code driver's `deviceInfo` may say `descriptor`: what the device is now - the claim's own
|
|
11
|
+
descriptor while it still is that, a new one once it was set up differently (a Bot switched from
|
|
12
|
+
press to switch mode in its vendor's app). When the device still says the new one thirty seconds
|
|
13
|
+
later, the hub describes it again from it: an entity described both times stays with its
|
|
14
|
+
history, one no longer described is removed with its history, one described only now is added.
|
|
15
|
+
The device's Activity says so, and the readings of a linked device are linked again.
|
|
16
|
+
|
|
17
|
+
## 1.8.0
|
|
18
|
+
|
|
19
|
+
One device reached more than one way.
|
|
20
|
+
|
|
21
|
+
- The twins of a vendor - its devices on different transports with the same `mac` or serial - link
|
|
22
|
+
their entities of the same `link.key` and domain when the owner links them, whichever ways they
|
|
23
|
+
are; until now an entity was linked by key only to a Matter one.
|
|
24
|
+
- `manifest.json` may say `twinsPrefer`: transports in order, the first the linked device is read
|
|
25
|
+
and commanded through while it answers - `["matter", "bluetooth", "acme/cloud"]`.
|
|
26
|
+
- A command on a linked entity that cannot reach the device one way - its transport down, the
|
|
27
|
+
device out of reach - goes the next way. One that timed out is not sent again: it may have been
|
|
28
|
+
done.
|
|
29
|
+
- The `bluetooth` transport answers `gatt.exchange`: a write, then the first notification on
|
|
30
|
+
another characteristic, for devices that answer each command.
|
|
31
|
+
- A code driver's `continueCommand(target, step, context)` carries a command through a
|
|
32
|
+
conversation with the device: handed each answer (`CommandStep`), it returns the next request, or
|
|
33
|
+
null when done; at most 8 steps in the command's one deadline. `driverHarness(...).converse()`
|
|
34
|
+
plays one against answers a test gives.
|
|
35
|
+
- `discovery.json` `bluetooth` may list up to four rule sets, the first that holds read; a model may
|
|
36
|
+
be some bytes of the advertisement's data - `{ "path", "bytes": [start, length], "mask" }` - and
|
|
37
|
+
of several places for it the first that reads a code the drivers map is the model.
|
|
38
|
+
|
|
6
39
|
## 1.7.0
|
|
7
40
|
|
|
8
41
|
Bluetooth proxies scan as the hub decides.
|
package/FILES.md
CHANGED
|
@@ -70,7 +70,16 @@ its `identity` reads, and its Matter identity's - and offers the owner to link t
|
|
|
70
70
|
Matter node is added and as a suggestion on the vendor's page. Linked, it is one device with two
|
|
71
71
|
ways in: its readings come the way the owner prefers, and the other way carries them while that
|
|
72
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
|
|
73
|
+
which of its readings is which in Matter, or, between two ways of the vendor's own - its cloud and
|
|
74
|
+
its Bluetooth, say - which of them read the same thing.
|
|
75
|
+
|
|
76
|
+
`twinsPrefer` says which way into a linked device is read first, by transport, best first:
|
|
77
|
+
`["matter", "bluetooth", "switchbot/cloud"]` reads a SwitchBot through Matter while Matter answers,
|
|
78
|
+
then through Bluetooth, and through the cloud last. When twins are linked, the way whose transport
|
|
79
|
+
comes earliest is the one preferred, and the dialog says so before the owner confirms; the owner may
|
|
80
|
+
pick another on the device's page. Without it, the device the house had first is read first.
|
|
81
|
+
Commands go the same way, and to the next way when one cannot reach the device - a Bluetooth device
|
|
82
|
+
only proxies hear, a cloud that does not answer.
|
|
74
83
|
|
|
75
84
|
`requires` says what the vendor's devices need besides the hub, in the grammar a
|
|
76
85
|
package's manifest uses (PACKAGES.md §8, Dependencies):
|
|
@@ -251,10 +260,24 @@ that says some of what it knows only when asked - in a scan response - adds `"ac
|
|
|
251
260
|
N` (1 to 1440): proxies rest passive, and every N minutes the hub asks the proxy hearing it best to
|
|
252
261
|
scan actively until it hears the device again, 30 s at most. Its
|
|
253
262
|
requests are GATT on the server's own adapter: `gatt.read { service, characteristic }` answers `{
|
|
254
|
-
data }`, `gatt.write { service, characteristic, data, withResponse }`, `gatt.
|
|
255
|
-
characteristic,
|
|
256
|
-
|
|
257
|
-
|
|
263
|
+
data }`, `gatt.write { service, characteristic, data, withResponse }`, `gatt.exchange { service,
|
|
264
|
+
characteristic, notify, data, withResponse, timeoutMs }` - a request written to `characteristic`,
|
|
265
|
+
answered `{ data }` with the first value `notify` notifies after it (`withResponse` false and 5 s
|
|
266
|
+
unless said, 10 s at most) - and `gatt.notify { service, characteristic, isOn }`, whose values are
|
|
267
|
+
delivered as `{ service, characteristic, data }` - hex throughout. They are refused when the server
|
|
268
|
+
has no usable adapter, or only proxies hear the device: proxies listen and never connect - a
|
|
269
|
+
command to a device linked to another way then goes that way (`twinsPrefer`, above).
|
|
270
|
+
`BLUETOOTH_GATT_OPS` names them.
|
|
271
|
+
|
|
272
|
+
A device spoken to in a **conversation** - a lock that hands out a session first and takes the
|
|
273
|
+
command sealed with it, a blind that wants two frames - is a code driver with `continueCommand(
|
|
274
|
+
target, { request, answer, index }, context)` beside `toCommand`: the hub sends the request
|
|
275
|
+
`toCommand` built, hands the driver what the transport answered, and sends the request it returns,
|
|
276
|
+
until it returns null - eight requests at most, all within the command's deadline. Each step is a
|
|
277
|
+
pure function of the answers, as `toCommand` is; a throw fails the command with its message. A
|
|
278
|
+
command whose deadline passes is reported unanswered, and is never sent another way, since the
|
|
279
|
+
device may still carry it out. `driverHarness(...).converse(entityId, capability, command,
|
|
280
|
+
answers)` runs one in a test.
|
|
258
281
|
|
|
259
282
|
`defaultIcon` names the icon a device of this driver starts with, by its id in the platform's
|
|
260
283
|
icon catalogue (`packages/icons/catalogue.json` lists the platform's own ids - `light`,
|
|
@@ -318,9 +341,12 @@ endpoint, the cluster and the attribute the platform's Matter mapping reads it f
|
|
|
318
341
|
cluster and attribute of an entity it reads from several: 0 for a light). When the device is
|
|
319
342
|
linked, an entity whose `matter` names a Matter entity of the twin is linked to it at once,
|
|
320
343
|
whatever it is; a sensor without one is linked when exactly one Matter sensor reads the same
|
|
321
|
-
thing, and a control never without one.
|
|
322
|
-
|
|
323
|
-
|
|
344
|
+
thing, and a control never without one. Between two ways of the vendor's own, neither of them
|
|
345
|
+
Matter, two entities with the same `key` in the same domain are linked at once - a cloud's `cover`
|
|
346
|
+
and the same device's Bluetooth `cover` - so a vendor reaching a device both ways gives each
|
|
347
|
+
reading the same key on both. The identity's `mac` and `serialNumber` are what the twin is found
|
|
348
|
+
by: `"identity": { "externalId": "id", "mac": "mac" }`, written any way the device writes it; a code
|
|
349
|
+
driver says them in its `describe`.
|
|
324
350
|
|
|
325
351
|
An entity may report **attributes** beside its state: `"attributes": { "endsAt":
|
|
326
352
|
"pairing.endsAt" }`, each a camelCase key read the way a state field is, into a scalar. They are
|
|
@@ -368,6 +394,20 @@ A profile may also say where its reports carry the firmware the device runs now
|
|
|
368
394
|
device's row as it hears it, so the device page follows an update without the device being added
|
|
369
395
|
again.
|
|
370
396
|
|
|
397
|
+
A device whose entities depend on how it is set up - a Bot that is a switch in switch mode and a
|
|
398
|
+
button in press mode, a relay that is two switches or one cover - says so through a code driver's
|
|
399
|
+
`deviceInfo(message, context)`: `descriptor` is what the device is now. Return the claim's own
|
|
400
|
+
descriptor (`context.claim.descriptor`) while the message shows it is still set up that way, a new
|
|
401
|
+
descriptor once it shows otherwise, and leave `descriptor` out when the message does not say. A
|
|
402
|
+
new one is taken when the device still says it thirty seconds later; one message saying the
|
|
403
|
+
claim's own again drops it, so a misread advertisement changes nothing. The hub then describes
|
|
404
|
+
the device again from the new descriptor and keeps it as the claim: entities described both times
|
|
405
|
+
stay, with their history and the owner's names; one no longer described is removed, with its
|
|
406
|
+
history, and an automation using it says so; one described only now is added. The device's
|
|
407
|
+
Activity says what was removed and added, and on a linked device the readings of the same `key`
|
|
408
|
+
are linked again. Keep an entity's `objectId` the same in every setup where it is the same thing
|
|
409
|
+
(a battery), so it is never removed for nothing.
|
|
410
|
+
|
|
371
411
|
The logo rides inside the catalogue the hub serves, as a data URL, so it must be an `.svg` or a
|
|
372
412
|
`.png` and at most 64 KiB; anything else fails the vendor at startup. Draw a monogram in the
|
|
373
413
|
vendor's colour - nobody's trademark -; the interface draws the same monogram itself for a vendor
|
|
@@ -569,7 +609,33 @@ sensor is heard as well as the house's own. The platform recognises BTHome senso
|
|
|
569
609
|
`serviceUuids` (a list, read with `contains`) and `serviceData.'<uuid>'` (read with `exists`).
|
|
570
610
|
UUIDs are lower case, a 16-bit one short: `fcd2`.
|
|
571
611
|
- `model` - where the advertisement says its model, looked up in the `modelCodes` of the vendor's
|
|
572
|
-
drivers on the `bluetooth` transport; `name` when absent.
|
|
612
|
+
drivers on the `bluetooth` transport; `name` when absent. A model kept in a byte of the data is
|
|
613
|
+
read as `{ "path", "bytes": [start, length], "mask" }`: the bytes from `start` - counted from the
|
|
614
|
+
end when below zero - each ANDed with `mask` (0-255) when given, written in lower-case hex: the
|
|
615
|
+
letter `H` with its top bit set reads `48` with `"mask": 127`. Data shorter than the bytes reads
|
|
616
|
+
nothing. A list of up to four places is tried in order, and the first that reads a code one of
|
|
617
|
+
the drivers maps is the model.
|
|
618
|
+
|
|
619
|
+
Devices that advertise in more than one way take a **list of up to four rule sets**; the first
|
|
620
|
+
whose `match` holds is the one whose `model` is read:
|
|
621
|
+
|
|
622
|
+
```json
|
|
623
|
+
{
|
|
624
|
+
"bluetooth": [
|
|
625
|
+
{
|
|
626
|
+
"match": [{ "path": "serviceData.'fd3d'", "exists": true }],
|
|
627
|
+
"model": [
|
|
628
|
+
{ "path": "serviceData.'fd3d'", "bytes": [-4, 4] },
|
|
629
|
+
{ "path": "serviceData.'fd3d'", "bytes": [0, 1], "mask": 127 }
|
|
630
|
+
]
|
|
631
|
+
},
|
|
632
|
+
{
|
|
633
|
+
"match": [{ "path": "serviceData.'0d00'", "exists": true }],
|
|
634
|
+
"model": { "path": "serviceData.'0d00'", "bytes": [0, 1], "mask": 127 }
|
|
635
|
+
}
|
|
636
|
+
]
|
|
637
|
+
}
|
|
638
|
+
```
|
|
573
639
|
|
|
574
640
|
A vendor may have `serial` or `bluetooth` alone, with no `listen`.
|
|
575
641
|
|
package/dist/chunks/node-dist.js
CHANGED
|
@@ -2073,6 +2073,8 @@ const integrationVendorSchema = z.object({
|
|
|
2073
2073
|
* as its manifest's `twins` says. Empty for a vendor that offers no links.
|
|
2074
2074
|
*/
|
|
2075
2075
|
twins: z.array(z.enum(TWIN_FACTS)).max(TWIN_FACTS.length).default([]),
|
|
2076
|
+
/** Which way into a linked device is read first, by transport, best first; empty when it says none. */
|
|
2077
|
+
twinsPrefer: z.array(z.string().min(1).max(64)).max(8).default([]),
|
|
2076
2078
|
/** The entities pairing is run by, for a vendor whose devices are paired through one of its own. */
|
|
2077
2079
|
pairing: vendorPairingSchema.nullable().default(null),
|
|
2078
2080
|
drivers: z.array(integrationKindSchema$1),
|
|
@@ -4340,7 +4342,13 @@ z.strictObject({
|
|
|
4340
4342
|
*/
|
|
4341
4343
|
config: jsonObjectSchema.default({}),
|
|
4342
4344
|
/** At least one: a device row nothing points at is a device the interface cannot explain. */
|
|
4343
|
-
entities: z.array(entityRegistrationSchema).min(1)
|
|
4345
|
+
entities: z.array(entityRegistrationSchema).min(1),
|
|
4346
|
+
/**
|
|
4347
|
+
* Whether these are all the entities the device has now - it was described again, set up
|
|
4348
|
+
* differently - so any other it had is removed, with its history. Left out, an entity is only
|
|
4349
|
+
* ever added or updated: a device heard again after a restart keeps what it had.
|
|
4350
|
+
*/
|
|
4351
|
+
replacesEntities: z.boolean().optional()
|
|
4344
4352
|
});
|
|
4345
4353
|
/** One device a package has, with its entities. */
|
|
4346
4354
|
const packageDeviceRegistrationSchema = z.object({
|
|
@@ -4408,7 +4416,21 @@ z.object({
|
|
|
4408
4416
|
/** The integration instance or package that owns it. */
|
|
4409
4417
|
source: sourceRefSchema,
|
|
4410
4418
|
name: z.string().min(1).max(128),
|
|
4411
|
-
entityIds: z.array(entityIdSchema)
|
|
4419
|
+
entityIds: z.array(entityIdSchema),
|
|
4420
|
+
/**
|
|
4421
|
+
* On `updated`, for a device described again because it was set up differently: the entities
|
|
4422
|
+
* removed and added, each by its address and its name then.
|
|
4423
|
+
*/
|
|
4424
|
+
described: z.object({
|
|
4425
|
+
added: z.array(z.object({
|
|
4426
|
+
entityId: entityIdSchema,
|
|
4427
|
+
name: z.string().max(128)
|
|
4428
|
+
})),
|
|
4429
|
+
removed: z.array(z.object({
|
|
4430
|
+
entityId: entityIdSchema,
|
|
4431
|
+
name: z.string().max(128)
|
|
4432
|
+
}))
|
|
4433
|
+
}).optional()
|
|
4412
4434
|
});
|
|
4413
4435
|
//#endregion
|
|
4414
4436
|
//#region ../contracts/dist/links.js
|
|
@@ -5147,6 +5169,13 @@ z.object({
|
|
|
5147
5169
|
data: bluetoothHexSchema,
|
|
5148
5170
|
withResponse: z.boolean().default(true)
|
|
5149
5171
|
});
|
|
5172
|
+
z.object({
|
|
5173
|
+
...gattTargetShape,
|
|
5174
|
+
notify: bluetoothUuidSchema,
|
|
5175
|
+
data: bluetoothHexSchema,
|
|
5176
|
+
withResponse: z.boolean().default(false),
|
|
5177
|
+
timeoutMs: z.int().min(100).max(1e4).default(5e3)
|
|
5178
|
+
});
|
|
5150
5179
|
z.object({
|
|
5151
5180
|
...gattTargetShape,
|
|
5152
5181
|
isOn: z.boolean()
|
|
@@ -6599,6 +6628,12 @@ const vendorManifestSchema = z.strictObject({
|
|
|
6599
6628
|
*/
|
|
6600
6629
|
twins: z.array(z.enum(TWIN_FACTS)).min(1).max(TWIN_FACTS.length).optional(),
|
|
6601
6630
|
/**
|
|
6631
|
+
* Which way into a linked device is read first, by transport, best first - `["matter",
|
|
6632
|
+
* "bluetooth", "acme/cloud"]`: the way whose transport comes earliest is preferred when twins
|
|
6633
|
+
* are linked, and the owner may pick another. Absent, the device the house had first is.
|
|
6634
|
+
*/
|
|
6635
|
+
twinsPrefer: z.array(z.string().min(1).max(64)).min(1).max(8).optional(),
|
|
6636
|
+
/**
|
|
6602
6637
|
* Path to a `setup.json` of settings every device of this vendor shares - a cloud API key,
|
|
6603
6638
|
* an account - relative to the bundle. Absent for the vendors whose devices are reached
|
|
6604
6639
|
* directly, which is most of them.
|
|
@@ -8149,17 +8184,43 @@ const modbusDiscoverySchema = brokerDiscoverySchema("values.model").extend({
|
|
|
8149
8184
|
* the owner says which device it is.
|
|
8150
8185
|
*/
|
|
8151
8186
|
const serialDiscoverySchema = brokerDiscoverySchema("product");
|
|
8187
|
+
/** How many rule sets a vendor's `bluetooth` block may list. */
|
|
8188
|
+
const MAXIMUM_RULE_SETS = 4;
|
|
8189
|
+
/**
|
|
8190
|
+
* Some bytes of the hex at a path, read as a model: `bytes` is `[start, length]`, a start below
|
|
8191
|
+
* zero counted from the end, and `mask` is ANDed with every byte. What it reads is the bytes in
|
|
8192
|
+
* lower-case hex - `48` for a model letter `H` - and nothing when the data is shorter.
|
|
8193
|
+
*/
|
|
8194
|
+
const bytePlaceSchema = z.strictObject({
|
|
8195
|
+
path: pathSchema,
|
|
8196
|
+
bytes: z.tuple([z.int().min(-32).max(31), z.int().min(1).max(8)]),
|
|
8197
|
+
mask: z.int().min(0).max(255).optional()
|
|
8198
|
+
});
|
|
8199
|
+
/** Where an advertisement says its model: a path, or some of the bytes at one. */
|
|
8200
|
+
const modelPlaceSchema = z.union([pathSchema, bytePlaceSchema]);
|
|
8201
|
+
/** One way a vendor's devices advertise: the rules on it, and where it says its model. */
|
|
8202
|
+
const bluetoothRulesSchema = z.strictObject({
|
|
8203
|
+
/** Every condition must hold. All-of, and at least one: a vendor does not take every device. */
|
|
8204
|
+
match: z.array(claimConditionSchema).min(1).max(MAXIMUM_MATCH),
|
|
8205
|
+
/** Where the device says its model; several are tried in order. */
|
|
8206
|
+
model: z.union([modelPlaceSchema, z.array(modelPlaceSchema).min(1).max(4)]).default("name")
|
|
8207
|
+
});
|
|
8152
8208
|
/**
|
|
8153
8209
|
* Which of the devices the house's Bluetooth hears are the vendor's: rules on one advertisement (a
|
|
8154
8210
|
* {@link BluetoothSighting}) - its `name`; `manufacturerData.'<company id>'`, the id in decimal,
|
|
8155
8211
|
* that `exists` or `startsWith` the data's first bytes in hex; `serviceUuids`, which `contains` a
|
|
8156
8212
|
* UUID in lower case; `serviceData.'<uuid>'`, that `exists`. The model is `name` unless said, in
|
|
8157
|
-
* the drivers on the `bluetooth` transport
|
|
8213
|
+
* the drivers on the `bluetooth` transport, or some bytes of the data: `{ "path", "bytes": [start,
|
|
8214
|
+
* length], "mask" }`.
|
|
8215
|
+
*
|
|
8216
|
+
* One rule set, or a list of up to four for a vendor whose devices advertise in more than one way:
|
|
8217
|
+
* the first whose rules hold is the one whose model is read. Of several places for the model, the
|
|
8218
|
+
* first that reads a code one of the vendor's drivers maps is the model.
|
|
8158
8219
|
*
|
|
8159
8220
|
* A device the rules take is listed as found for the vendor, and added only by the owner: what a
|
|
8160
8221
|
* neighbour's sensor advertises is heard as well as the house's own.
|
|
8161
8222
|
*/
|
|
8162
|
-
const bluetoothDiscoverySchema =
|
|
8223
|
+
const bluetoothDiscoverySchema = z.union([bluetoothRulesSchema, z.array(bluetoothRulesSchema).min(1).max(MAXIMUM_RULE_SETS)]).transform((rules) => Array.isArray(rules) ? rules : [rules]);
|
|
8163
8224
|
/**
|
|
8164
8225
|
* The platform's brokers a vendor may take devices of, and the transport each reaches them on.
|
|
8165
8226
|
* Serial has none of its own: its devices are reached over their vendor's transport, through the
|
|
@@ -8361,7 +8422,49 @@ function associateModel(plan, modelCode, claimedBy) {
|
|
|
8361
8422
|
* @returns True when the vendor has the broker's block and every one of its conditions holds.
|
|
8362
8423
|
*/
|
|
8363
8424
|
function matchesBroker(plan, broker, identity) {
|
|
8364
|
-
return plan
|
|
8425
|
+
return rulesOf(plan, broker).some((rules) => holds(rules, identity));
|
|
8426
|
+
}
|
|
8427
|
+
/**
|
|
8428
|
+
* The rule sets of the vendor's block for a broker.
|
|
8429
|
+
*
|
|
8430
|
+
* @param plan - The vendor's discovery.
|
|
8431
|
+
* @param broker - Which broker.
|
|
8432
|
+
* @returns Bluetooth's list, the one block of another broker, or none without a block.
|
|
8433
|
+
*/
|
|
8434
|
+
function rulesOf(plan, broker) {
|
|
8435
|
+
const block = plan.discovery[broker];
|
|
8436
|
+
return block === void 0 ? [] : Array.isArray(block) ? block : [block];
|
|
8437
|
+
}
|
|
8438
|
+
/**
|
|
8439
|
+
* Whether every condition of a rule set holds.
|
|
8440
|
+
*
|
|
8441
|
+
* @param rules - The rule set.
|
|
8442
|
+
* @param identity - Who the device says it is.
|
|
8443
|
+
* @returns True when they all hold.
|
|
8444
|
+
*/
|
|
8445
|
+
function holds(rules, identity) {
|
|
8446
|
+
return rules.match.every((condition) => conditionHolds(condition, identity));
|
|
8447
|
+
}
|
|
8448
|
+
/**
|
|
8449
|
+
* Reads a model from one place.
|
|
8450
|
+
*
|
|
8451
|
+
* @param identity - Who the device says it is.
|
|
8452
|
+
* @param place - A path, or some bytes of the hex at one.
|
|
8453
|
+
* @returns The text, the bytes in lower-case hex, or null when there is none.
|
|
8454
|
+
*/
|
|
8455
|
+
function modelAt(identity, place) {
|
|
8456
|
+
if (typeof place === "string") return textAt(identity, place);
|
|
8457
|
+
const hex = resolvePath(identity, place.path);
|
|
8458
|
+
if (typeof hex !== "string" || !/^(?:[0-9a-f]{2})+$/iu.test(hex)) return null;
|
|
8459
|
+
const [first, length] = place.bytes;
|
|
8460
|
+
const start = first < 0 ? hex.length / 2 + first : first;
|
|
8461
|
+
if (start < 0 || (start + length) * 2 > hex.length) return null;
|
|
8462
|
+
let text = "";
|
|
8463
|
+
for (let at = start * 2; at < (start + length) * 2; at += 2) {
|
|
8464
|
+
const byte = Number.parseInt(hex.slice(at, at + 2), 16) & (place.mask ?? 255);
|
|
8465
|
+
text += byte.toString(16).padStart(2, "0");
|
|
8466
|
+
}
|
|
8467
|
+
return text;
|
|
8365
8468
|
}
|
|
8366
8469
|
/**
|
|
8367
8470
|
* Finds the driver of the vendor's that runs a device of one of the platform's brokers, and its
|
|
@@ -8369,7 +8472,8 @@ function matchesBroker(plan, broker, identity) {
|
|
|
8369
8472
|
*
|
|
8370
8473
|
* The model the device says is looked up in the `modelCodes` of the vendor's drivers on that
|
|
8371
8474
|
* broker's transport - for serial, its drivers of kind `serial` - and one it does not map goes to
|
|
8372
|
-
* the vendor's driver there when it has only one.
|
|
8475
|
+
* the vendor's driver there when it has only one. Of several places for the model, the first that
|
|
8476
|
+
* reads a mapped code wins; Bluetooth reads the places of its first rule set that holds.
|
|
8373
8477
|
*
|
|
8374
8478
|
* @param plan - The vendor's discovery.
|
|
8375
8479
|
* @param broker - Which broker holds the device: `matter`, `mqtt`, `serial`.
|
|
@@ -8378,8 +8482,18 @@ function matchesBroker(plan, broker, identity) {
|
|
|
8378
8482
|
*/
|
|
8379
8483
|
function associateBroker(plan, broker, identity) {
|
|
8380
8484
|
const drivers = plan.drivers.filter((driver) => broker === "serial" ? driver.kind === "serial" : driver.transport === BROKER_TRANSPORTS[broker]);
|
|
8381
|
-
const
|
|
8382
|
-
const
|
|
8485
|
+
const sets = rulesOf(plan, broker);
|
|
8486
|
+
const places = (sets.find((rules) => holds(rules, identity)) ?? sets[0])?.model;
|
|
8487
|
+
/**
|
|
8488
|
+
* The vendor's drivers on the broker that map a code.
|
|
8489
|
+
*
|
|
8490
|
+
* @param code - What the device says its model is.
|
|
8491
|
+
* @returns Their entries.
|
|
8492
|
+
*/
|
|
8493
|
+
const codedOf = (code) => (plan.codes.get(code) ?? []).filter((entry) => drivers.some((driver) => driver.id === entry.driverId));
|
|
8494
|
+
const read = (Array.isArray(places) ? places : [places ?? BROKER_MODELS[broker]]).map((place) => modelAt(identity, place)).filter((code) => code !== null);
|
|
8495
|
+
const modelCode = read.find((code) => codedOf(code).length > 0) ?? read[0] ?? null;
|
|
8496
|
+
const [first] = modelCode === null ? [] : codedOf(modelCode);
|
|
8383
8497
|
if (first !== void 0) return {
|
|
8384
8498
|
driverId: first.driverId,
|
|
8385
8499
|
model: first.models.length === 1 ? first.models[0] ?? null : null,
|
|
@@ -234,9 +234,8 @@ type EntityStateClass = (typeof ENTITY_STATE_CLASSES)[number];
|
|
|
234
234
|
declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
|
|
235
235
|
number: "number";
|
|
236
236
|
custom: "custom";
|
|
237
|
-
image: "image";
|
|
238
|
-
level: "level";
|
|
239
237
|
on_off: "on_off";
|
|
238
|
+
level: "level";
|
|
240
239
|
color_hs: "color_hs";
|
|
241
240
|
color_temp: "color_temp";
|
|
242
241
|
cover: "cover";
|
|
@@ -252,6 +251,7 @@ declare const declaredCapabilitiesSchema: z.ZodRecord<z.ZodEnum<{
|
|
|
252
251
|
lawn_mower: "lawn_mower";
|
|
253
252
|
select: "select";
|
|
254
253
|
vacuum: "vacuum";
|
|
254
|
+
image: "image";
|
|
255
255
|
}> & z.core.$partial, z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
|
|
256
256
|
/** What an entity declares it can do, with the device's own limits for each. */
|
|
257
257
|
type DeclaredCapabilities = z.output<typeof declaredCapabilitiesSchema>;
|
|
@@ -1286,6 +1286,13 @@ type MappingContext = {
|
|
|
1286
1286
|
*/
|
|
1287
1287
|
lastState: (entityId: EntityId) => CapabilityState | undefined;
|
|
1288
1288
|
};
|
|
1289
|
+
/** One request of a command already sent, and what the transport answered. */
|
|
1290
|
+
type CommandStep = {
|
|
1291
|
+
readonly request: TransportRequest;
|
|
1292
|
+
readonly answer: unknown;
|
|
1293
|
+
/** Its place in the command: 0 for the request `toCommand` built. */
|
|
1294
|
+
readonly index: number;
|
|
1295
|
+
};
|
|
1289
1296
|
/** A command, resolved to the device and entity it is for. */
|
|
1290
1297
|
type CommandTarget = {
|
|
1291
1298
|
readonly entityId: EntityId;
|
|
@@ -1368,9 +1375,25 @@ type Integration<TOptions = JsonObject> = {
|
|
|
1368
1375
|
* @returns The request. Performing it is the transport's job.
|
|
1369
1376
|
*/
|
|
1370
1377
|
toCommand: (target: CommandTarget, context: MappingContext) => TransportRequest;
|
|
1378
|
+
/**
|
|
1379
|
+
* Carries a command on once the transport answered its last request - for a device spoken to in
|
|
1380
|
+
* a conversation: a Bluetooth lock asked for a session first, then sent the command sealed with
|
|
1381
|
+
* it. Each step is a pure function of what came back; the hub sends what it returns, at most
|
|
1382
|
+
* {@link MAX_COMMAND_STEPS} requests in all, and stops at null. A throw fails the command with
|
|
1383
|
+
* its message.
|
|
1384
|
+
*
|
|
1385
|
+
* Optional: without it a command is the one request `toCommand` builds.
|
|
1386
|
+
*
|
|
1387
|
+
* @param target - The entity, the capability and the command.
|
|
1388
|
+
* @param step - The request just sent, what the transport answered, and its place (0 first).
|
|
1389
|
+
* @param context - The claim, the settings and the last known state.
|
|
1390
|
+
* @returns The next request, or null when the command is done.
|
|
1391
|
+
*/
|
|
1392
|
+
continueCommand?: (target: CommandTarget, step: CommandStep, context: MappingContext) => TransportRequest | null;
|
|
1371
1393
|
/**
|
|
1372
1394
|
* Reads what a message says about the device itself, beyond its entities: the firmware it runs
|
|
1373
|
-
* now, which changes when it is updated and is otherwise only known from when it was found
|
|
1395
|
+
* now, which changes when it is updated and is otherwise only known from when it was found;
|
|
1396
|
+
* and how it is set up, when that decides its entities (`descriptor`).
|
|
1374
1397
|
*
|
|
1375
1398
|
* Optional: an integration whose messages say nothing of the kind leaves it out.
|
|
1376
1399
|
*
|
|
@@ -1400,6 +1423,17 @@ type StreamRequest = {
|
|
|
1400
1423
|
type DeviceInfo = {
|
|
1401
1424
|
readonly swVersion?: string;
|
|
1402
1425
|
readonly hwVersion?: string;
|
|
1426
|
+
/**
|
|
1427
|
+
* What the device is now, for a device whose entities depend on how it is set up - a Bot in
|
|
1428
|
+
* switch or in press mode: the claim's own descriptor while it is still that, a new one to
|
|
1429
|
+
* describe it from once it changed. Left out when the message does not say.
|
|
1430
|
+
*
|
|
1431
|
+
* A new one is taken when the device still says it thirty seconds later - a message saying
|
|
1432
|
+
* the claim's own again drops it. The device is then described again: an entity
|
|
1433
|
+
* described both times stays, with its history; one no longer described is removed, with its
|
|
1434
|
+
* history; one described only now is added.
|
|
1435
|
+
*/
|
|
1436
|
+
readonly descriptor?: unknown;
|
|
1403
1437
|
};
|
|
1404
1438
|
//#endregion
|
|
1405
1439
|
//#region ../package-runtime/dist/stream.d.ts
|
|
@@ -2124,13 +2158,14 @@ declare const vendorManifestSchema: z.ZodObject<{
|
|
|
2124
2158
|
serial: "serial";
|
|
2125
2159
|
mac: "mac";
|
|
2126
2160
|
}>>>;
|
|
2161
|
+
twinsPrefer: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
2127
2162
|
setup: z.ZodOptional<z.ZodString>;
|
|
2128
2163
|
account: z.ZodOptional<z.ZodString>;
|
|
2129
2164
|
transports: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
2130
2165
|
module: z.ZodString;
|
|
2131
2166
|
wires: z.ZodArray<z.ZodEnum<{
|
|
2132
|
-
udp: "udp";
|
|
2133
2167
|
matter: "matter";
|
|
2168
|
+
udp: "udp";
|
|
2134
2169
|
mqtt: "mqtt";
|
|
2135
2170
|
modbus: "modbus";
|
|
2136
2171
|
serial: "serial";
|
|
@@ -2227,9 +2262,9 @@ declare const bundleManifestSchema: z.ZodObject<{
|
|
|
2227
2262
|
modelCodes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
|
|
2228
2263
|
modelSeries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
2229
2264
|
kind: z.ZodEnum<{
|
|
2265
|
+
matter: "matter";
|
|
2230
2266
|
declarative: "declarative";
|
|
2231
2267
|
code: "code";
|
|
2232
|
-
matter: "matter";
|
|
2233
2268
|
mqtt: "mqtt";
|
|
2234
2269
|
modbus: "modbus";
|
|
2235
2270
|
infrared: "infrared";
|
|
@@ -2464,7 +2499,7 @@ declare const vendorDiscoverySchema: z.ZodObject<{
|
|
|
2464
2499
|
}, z.core.$strict>]>>;
|
|
2465
2500
|
model: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
|
|
2466
2501
|
}, z.core.$strict>>;
|
|
2467
|
-
bluetooth: z.ZodOptional<z.ZodObject<{
|
|
2502
|
+
bluetooth: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodObject<{
|
|
2468
2503
|
match: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
|
|
2469
2504
|
path: z.ZodString;
|
|
2470
2505
|
equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
|
|
@@ -2488,8 +2523,148 @@ declare const vendorDiscoverySchema: z.ZodObject<{
|
|
|
2488
2523
|
min: z.ZodOptional<z.ZodNumber>;
|
|
2489
2524
|
max: z.ZodOptional<z.ZodNumber>;
|
|
2490
2525
|
}, z.core.$strict>]>>;
|
|
2491
|
-
model: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.
|
|
2492
|
-
|
|
2526
|
+
model: z.ZodDefault<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
2527
|
+
path: z.ZodString;
|
|
2528
|
+
bytes: z.ZodTuple<[z.ZodInt, z.ZodInt], null>;
|
|
2529
|
+
mask: z.ZodOptional<z.ZodInt>;
|
|
2530
|
+
}, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
2531
|
+
path: z.ZodString;
|
|
2532
|
+
bytes: z.ZodTuple<[z.ZodInt, z.ZodInt], null>;
|
|
2533
|
+
mask: z.ZodOptional<z.ZodInt>;
|
|
2534
|
+
}, z.core.$strict>]>>]>>;
|
|
2535
|
+
}, z.core.$strict>, z.ZodArray<z.ZodObject<{
|
|
2536
|
+
match: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
|
|
2537
|
+
path: z.ZodString;
|
|
2538
|
+
equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
|
|
2539
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
2540
|
+
path: z.ZodString;
|
|
2541
|
+
exists: z.ZodLiteral<true>;
|
|
2542
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
2543
|
+
path: z.ZodString;
|
|
2544
|
+
oneOf: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
|
|
2545
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
2546
|
+
path: z.ZodString;
|
|
2547
|
+
startsWith: z.ZodString;
|
|
2548
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
2549
|
+
path: z.ZodString;
|
|
2550
|
+
endsWith: z.ZodString;
|
|
2551
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
2552
|
+
path: z.ZodString;
|
|
2553
|
+
contains: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
|
|
2554
|
+
}, z.core.$strict>, z.ZodObject<{
|
|
2555
|
+
path: z.ZodString;
|
|
2556
|
+
min: z.ZodOptional<z.ZodNumber>;
|
|
2557
|
+
max: z.ZodOptional<z.ZodNumber>;
|
|
2558
|
+
}, z.core.$strict>]>>;
|
|
2559
|
+
model: z.ZodDefault<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
2560
|
+
path: z.ZodString;
|
|
2561
|
+
bytes: z.ZodTuple<[z.ZodInt, z.ZodInt], null>;
|
|
2562
|
+
mask: z.ZodOptional<z.ZodInt>;
|
|
2563
|
+
}, z.core.$strict>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
|
|
2564
|
+
path: z.ZodString;
|
|
2565
|
+
bytes: z.ZodTuple<[z.ZodInt, z.ZodInt], null>;
|
|
2566
|
+
mask: z.ZodOptional<z.ZodInt>;
|
|
2567
|
+
}, z.core.$strict>]>>]>>;
|
|
2568
|
+
}, z.core.$strict>>]>, z.ZodTransform<{
|
|
2569
|
+
match: ({
|
|
2570
|
+
path: string;
|
|
2571
|
+
min?: number | undefined;
|
|
2572
|
+
max?: number | undefined;
|
|
2573
|
+
} | {
|
|
2574
|
+
path: string;
|
|
2575
|
+
equals: string | number | boolean;
|
|
2576
|
+
} | {
|
|
2577
|
+
path: string;
|
|
2578
|
+
exists: true;
|
|
2579
|
+
} | {
|
|
2580
|
+
path: string;
|
|
2581
|
+
oneOf: (string | number | boolean)[];
|
|
2582
|
+
} | {
|
|
2583
|
+
path: string;
|
|
2584
|
+
startsWith: string;
|
|
2585
|
+
} | {
|
|
2586
|
+
path: string;
|
|
2587
|
+
endsWith: string;
|
|
2588
|
+
} | {
|
|
2589
|
+
path: string;
|
|
2590
|
+
contains: string | number | boolean;
|
|
2591
|
+
})[];
|
|
2592
|
+
model: string | {
|
|
2593
|
+
path: string;
|
|
2594
|
+
bytes: [number, number];
|
|
2595
|
+
mask?: number | undefined;
|
|
2596
|
+
} | (string | {
|
|
2597
|
+
path: string;
|
|
2598
|
+
bytes: [number, number];
|
|
2599
|
+
mask?: number | undefined;
|
|
2600
|
+
})[];
|
|
2601
|
+
}[], {
|
|
2602
|
+
match: ({
|
|
2603
|
+
path: string;
|
|
2604
|
+
min?: number | undefined;
|
|
2605
|
+
max?: number | undefined;
|
|
2606
|
+
} | {
|
|
2607
|
+
path: string;
|
|
2608
|
+
equals: string | number | boolean;
|
|
2609
|
+
} | {
|
|
2610
|
+
path: string;
|
|
2611
|
+
exists: true;
|
|
2612
|
+
} | {
|
|
2613
|
+
path: string;
|
|
2614
|
+
oneOf: (string | number | boolean)[];
|
|
2615
|
+
} | {
|
|
2616
|
+
path: string;
|
|
2617
|
+
startsWith: string;
|
|
2618
|
+
} | {
|
|
2619
|
+
path: string;
|
|
2620
|
+
endsWith: string;
|
|
2621
|
+
} | {
|
|
2622
|
+
path: string;
|
|
2623
|
+
contains: string | number | boolean;
|
|
2624
|
+
})[];
|
|
2625
|
+
model: string | {
|
|
2626
|
+
path: string;
|
|
2627
|
+
bytes: [number, number];
|
|
2628
|
+
mask?: number | undefined;
|
|
2629
|
+
} | (string | {
|
|
2630
|
+
path: string;
|
|
2631
|
+
bytes: [number, number];
|
|
2632
|
+
mask?: number | undefined;
|
|
2633
|
+
})[];
|
|
2634
|
+
} | {
|
|
2635
|
+
match: ({
|
|
2636
|
+
path: string;
|
|
2637
|
+
min?: number | undefined;
|
|
2638
|
+
max?: number | undefined;
|
|
2639
|
+
} | {
|
|
2640
|
+
path: string;
|
|
2641
|
+
equals: string | number | boolean;
|
|
2642
|
+
} | {
|
|
2643
|
+
path: string;
|
|
2644
|
+
exists: true;
|
|
2645
|
+
} | {
|
|
2646
|
+
path: string;
|
|
2647
|
+
oneOf: (string | number | boolean)[];
|
|
2648
|
+
} | {
|
|
2649
|
+
path: string;
|
|
2650
|
+
startsWith: string;
|
|
2651
|
+
} | {
|
|
2652
|
+
path: string;
|
|
2653
|
+
endsWith: string;
|
|
2654
|
+
} | {
|
|
2655
|
+
path: string;
|
|
2656
|
+
contains: string | number | boolean;
|
|
2657
|
+
})[];
|
|
2658
|
+
model: string | {
|
|
2659
|
+
path: string;
|
|
2660
|
+
bytes: [number, number];
|
|
2661
|
+
mask?: number | undefined;
|
|
2662
|
+
} | (string | {
|
|
2663
|
+
path: string;
|
|
2664
|
+
bytes: [number, number];
|
|
2665
|
+
mask?: number | undefined;
|
|
2666
|
+
})[];
|
|
2667
|
+
}[]>>>;
|
|
2493
2668
|
adopt: z.ZodDefault<z.ZodEnum<{
|
|
2494
2669
|
owner: "owner";
|
|
2495
2670
|
automatic: "automatic";
|
|
@@ -830,7 +830,7 @@ function defineTransport(spec) {
|
|
|
830
830
|
* bundle built with this SDK says `^<major>.<minor>.0`.
|
|
831
831
|
*/
|
|
832
832
|
/** The SDK's own version: `1.0.0`, or a prerelease of it. */
|
|
833
|
-
const SDK_VERSION = "1.
|
|
833
|
+
const SDK_VERSION = "1.9.0";
|
|
834
834
|
/**
|
|
835
835
|
* The runtime range a bundle built with this SDK declares: this version's major and minor, so a
|
|
836
836
|
* platform with the same contract or a later one of the same major loads it.
|