@nebulahome/integration-sdk 1.6.1 → 1.8.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 +37 -0
- package/FILES.md +87 -25
- package/dist/chunks/node-dist.js +114 -20
- package/dist/chunks/node-index.d.ts +169 -6
- package/dist/chunks/node-project.js +1 -1
- package/dist/index.d.ts +33 -4
- package/dist/index.js +3 -1
- package/dist/schemas.d.ts +148 -7
- 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,43 @@
|
|
|
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.8.0
|
|
7
|
+
|
|
8
|
+
One device reached more than one way.
|
|
9
|
+
|
|
10
|
+
- The twins of a vendor - its devices on different transports with the same `mac` or serial - link
|
|
11
|
+
their entities of the same `link.key` and domain when the owner links them, whichever ways they
|
|
12
|
+
are; until now an entity was linked by key only to a Matter one.
|
|
13
|
+
- `manifest.json` may say `twinsPrefer`: transports in order, the first the linked device is read
|
|
14
|
+
and commanded through while it answers - `["matter", "bluetooth", "acme/cloud"]`.
|
|
15
|
+
- A command on a linked entity that cannot reach the device one way - its transport down, the
|
|
16
|
+
device out of reach - goes the next way. One that timed out is not sent again: it may have been
|
|
17
|
+
done.
|
|
18
|
+
- The `bluetooth` transport answers `gatt.exchange`: a write, then the first notification on
|
|
19
|
+
another characteristic, for devices that answer each command.
|
|
20
|
+
- A code driver's `continueCommand(target, step, context)` carries a command through a
|
|
21
|
+
conversation with the device: handed each answer (`CommandStep`), it returns the next request, or
|
|
22
|
+
null when done; at most 8 steps in the command's one deadline. `driverHarness(...).converse()`
|
|
23
|
+
plays one against answers a test gives.
|
|
24
|
+
- `discovery.json` `bluetooth` may list up to four rule sets, the first that holds read; a model may
|
|
25
|
+
be some bytes of the advertisement's data - `{ "path", "bytes": [start, length], "mask" }` - and
|
|
26
|
+
of several places for it the first that reads a code the drivers map is the model.
|
|
27
|
+
|
|
28
|
+
## 1.7.0
|
|
29
|
+
|
|
30
|
+
Bluetooth proxies scan as the hub decides.
|
|
31
|
+
|
|
32
|
+
- The owner no longer picks a proxy's scan mode. `bluetooth-proxy.install`'s `mode` is the one the
|
|
33
|
+
proxy rests in, which the hub picks: `passive` when the profile lists it, else `active`.
|
|
34
|
+
- `bluetooth-proxy.filter` carries `active`: the hub asks a proxy to scan actively while somebody
|
|
35
|
+
has Nearby open, while a device it hears is being added, and when a followed device's refresh
|
|
36
|
+
falls due; absent or false, the proxy goes back to rest.
|
|
37
|
+
- A Bluetooth driver's `follow` subscription may say `activeEveryMinutes` (1 to 1440): every so
|
|
38
|
+
often the proxy hearing the device best scans actively until it hears it again, 30 s at most, for
|
|
39
|
+
what the device says only in a scan response.
|
|
40
|
+
- `bluetooth-proxy.state` may answer the reason `unsupported`: a model that cannot run the script,
|
|
41
|
+
or whose radio is busy with something else.
|
|
42
|
+
|
|
6
43
|
## 1.6.1
|
|
7
44
|
|
|
8
45
|
- `sdk.codecs.infrared`: a Broadlink tick is 8192/269 µs, about 30.45 µs, as measured against real
|
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):
|
|
@@ -246,12 +255,29 @@ address: the owner adds one from the Bluetooth broker's Found or Nearby, and its
|
|
|
246
255
|
address, upper case. Its claim reads `{ deviceKey, kind, name, advert }`, the advertisement it was
|
|
247
256
|
recognised from; it follows its address with the subscription `{ "op": "follow", "args": {
|
|
248
257
|
"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.
|
|
258
|
+
any proxy - one carrying the same name, maker's and service data at most once a minute. A device
|
|
259
|
+
that says some of what it knows only when asked - in a scan response - adds `"activeEveryMinutes":
|
|
260
|
+
N` (1 to 1440): proxies rest passive, and every N minutes the hub asks the proxy hearing it best to
|
|
261
|
+
scan actively until it hears the device again, 30 s at most. Its
|
|
250
262
|
requests are GATT on the server's own adapter: `gatt.read { service, characteristic }` answers `{
|
|
251
|
-
data }`, `gatt.write { service, characteristic, data, withResponse }`, `gatt.
|
|
252
|
-
characteristic,
|
|
253
|
-
|
|
254
|
-
|
|
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.
|
|
255
281
|
|
|
256
282
|
`defaultIcon` names the icon a device of this driver starts with, by its id in the platform's
|
|
257
283
|
icon catalogue (`packages/icons/catalogue.json` lists the platform's own ids - `light`,
|
|
@@ -315,9 +341,12 @@ endpoint, the cluster and the attribute the platform's Matter mapping reads it f
|
|
|
315
341
|
cluster and attribute of an entity it reads from several: 0 for a light). When the device is
|
|
316
342
|
linked, an entity whose `matter` names a Matter entity of the twin is linked to it at once,
|
|
317
343
|
whatever it is; a sensor without one is linked when exactly one Matter sensor reads the same
|
|
318
|
-
thing, and a control never without one.
|
|
319
|
-
|
|
320
|
-
|
|
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`.
|
|
321
350
|
|
|
322
351
|
An entity may report **attributes** beside its state: `"attributes": { "endsAt":
|
|
323
352
|
"pairing.endsAt" }`, each a camelCase key read the way a state field is, into a scalar. They are
|
|
@@ -566,7 +595,33 @@ sensor is heard as well as the house's own. The platform recognises BTHome senso
|
|
|
566
595
|
`serviceUuids` (a list, read with `contains`) and `serviceData.'<uuid>'` (read with `exists`).
|
|
567
596
|
UUIDs are lower case, a 16-bit one short: `fcd2`.
|
|
568
597
|
- `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.
|
|
598
|
+
drivers on the `bluetooth` transport; `name` when absent. A model kept in a byte of the data is
|
|
599
|
+
read as `{ "path", "bytes": [start, length], "mask" }`: the bytes from `start` - counted from the
|
|
600
|
+
end when below zero - each ANDed with `mask` (0-255) when given, written in lower-case hex: the
|
|
601
|
+
letter `H` with its top bit set reads `48` with `"mask": 127`. Data shorter than the bytes reads
|
|
602
|
+
nothing. A list of up to four places is tried in order, and the first that reads a code one of
|
|
603
|
+
the drivers maps is the model.
|
|
604
|
+
|
|
605
|
+
Devices that advertise in more than one way take a **list of up to four rule sets**; the first
|
|
606
|
+
whose `match` holds is the one whose `model` is read:
|
|
607
|
+
|
|
608
|
+
```json
|
|
609
|
+
{
|
|
610
|
+
"bluetooth": [
|
|
611
|
+
{
|
|
612
|
+
"match": [{ "path": "serviceData.'fd3d'", "exists": true }],
|
|
613
|
+
"model": [
|
|
614
|
+
{ "path": "serviceData.'fd3d'", "bytes": [-4, 4] },
|
|
615
|
+
{ "path": "serviceData.'fd3d'", "bytes": [0, 1], "mask": 127 }
|
|
616
|
+
]
|
|
617
|
+
},
|
|
618
|
+
{
|
|
619
|
+
"match": [{ "path": "serviceData.'0d00'", "exists": true }],
|
|
620
|
+
"model": { "path": "serviceData.'0d00'", "bytes": [0, 1], "mask": 127 }
|
|
621
|
+
}
|
|
622
|
+
]
|
|
623
|
+
}
|
|
624
|
+
```
|
|
570
625
|
|
|
571
626
|
A vendor may have `serial` or `bluetooth` alone, with no `listen`.
|
|
572
627
|
|
|
@@ -933,29 +988,36 @@ what the sweep found. A learn that rejects with an error named `TimeoutError` or
|
|
|
933
988
|
at or after `timeoutMs`, reads "Nothing reached the blaster in 30 s." on the page; any other shows
|
|
934
989
|
its message.
|
|
935
990
|
|
|
936
|
-
**A Bluetooth proxy** declares `bluetoothProxy: { modes }`, the scan modes
|
|
937
|
-
and `active`, each once.
|
|
991
|
+
**A Bluetooth proxy** declares `bluetoothProxy: { modes }`, the scan modes its radio can run,
|
|
992
|
+
`passive` and `active`, each once. The owner does not choose one: the hub does. A proxy rests
|
|
993
|
+
passive when it can, and the hub asks it to scan actively only while the house needs more than
|
|
994
|
+
adverts - while somebody has Nearby open (every proxy), while a device is being added (the proxies
|
|
995
|
+
hearing it), and when a followed device's `activeEveryMinutes` falls due (the proxy hearing it
|
|
996
|
+
best).
|
|
938
997
|
|
|
939
|
-
| Op | Arguments
|
|
940
|
-
| ------------------------- |
|
|
941
|
-
| `bluetooth-proxy.state` | `{}`
|
|
942
|
-
| `bluetooth-proxy.install` | `{ mode }`
|
|
943
|
-
| `bluetooth-proxy.remove` | `{}`
|
|
944
|
-
| `bluetooth-proxy.filter` | `{ addresses }` | 10 s | forward those addresses
|
|
998
|
+
| Op | Arguments | The hub waits | Answer |
|
|
999
|
+
| ------------------------- | ------------------------ | ------------- | --------------------------------------------------------- |
|
|
1000
|
+
| `bluetooth-proxy.state` | `{}` | 10 s | `BluetoothProxyState`; anything else counts as no answer |
|
|
1001
|
+
| `bluetooth-proxy.install` | `{ mode }` | 60 s | install the script, or update it, resting in that mode |
|
|
1002
|
+
| `bluetooth-proxy.remove` | `{}` | 10 s | stop the script and remove it; throw to refuse |
|
|
1003
|
+
| `bluetooth-proxy.filter` | `{ addresses, active? }` | 10 s | forward those addresses, scanning actively while `active` |
|
|
945
1004
|
|
|
946
1005
|
- `state` answers `{ eligible: true, installed, version?, shipped, running }` - the script on the
|
|
947
1006
|
device, the one the vendor ships now, whether it runs - or `{ eligible: false, reason, update? }`,
|
|
948
|
-
the reason `gen1`, `battery`, `firmware
|
|
949
|
-
the
|
|
1007
|
+
the reason `gen1`, `battery`, `firmware`, `no-bluetooth` or `unsupported` - a model that cannot
|
|
1008
|
+
run the script, or whose radio is busy with something else - and `update` whether a firmware
|
|
1009
|
+
update the device offers would make it eligible. The hub asks it for the list of devices that could be
|
|
950
1010
|
proxies, when the device's scanner opens, and after an install, a second apart until it says
|
|
951
1011
|
`running`. The script is outdated when `version` and `shipped` are both strict semver and
|
|
952
1012
|
`version` is the lower, otherwise whenever they differ.
|
|
953
|
-
- `install` is also how the
|
|
954
|
-
with its message.
|
|
1013
|
+
- `install` is also how the script is updated. `mode` is the one it rests in, which the hub picks:
|
|
1014
|
+
`passive` when the profile lists it, else `active`. A throw fails the job with its message.
|
|
955
1015
|
- `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.
|
|
957
|
-
|
|
958
|
-
|
|
1016
|
+
added and those a rule recognises - upper case, sorted, 4096 at most. `active: true` asks it to
|
|
1017
|
+
scan actively until a filter says otherwise; absent or false, it goes back to the mode it rests
|
|
1018
|
+
in. A proxy whose profile does not list `active` is never asked. It comes at the hub's start,
|
|
1019
|
+
when the scanner opens, on every change and again every five minutes. Keep only the last one; a
|
|
1020
|
+
script that restarted forwards nothing, and rests, until it is told again.
|
|
959
1021
|
|
|
960
1022
|
What the proxy hears reaches the house through `sdk.bluetooth.scanner({ key, deviceKey })`: `key`
|
|
961
1023
|
is the instance connection's key and `deviceKey` the device's on it, or the hub cannot tell which
|
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),
|
|
@@ -5072,12 +5074,16 @@ const BLUETOOTH_ADAPTER_PROBLEMS = [
|
|
|
5072
5074
|
"powered-off",
|
|
5073
5075
|
"disabled"
|
|
5074
5076
|
];
|
|
5075
|
-
/**
|
|
5077
|
+
/**
|
|
5078
|
+
* Why a device cannot be a proxy: Gen1, battery powered, firmware too old, no Bluetooth, or a
|
|
5079
|
+
* model that cannot run the script (no scripts, or its radio busy with something else).
|
|
5080
|
+
*/
|
|
5076
5081
|
const BLUETOOTH_PROXY_INELIGIBLE_REASONS = [
|
|
5077
5082
|
"gen1",
|
|
5078
5083
|
"battery",
|
|
5079
5084
|
"firmware",
|
|
5080
|
-
"no-bluetooth"
|
|
5085
|
+
"no-bluetooth",
|
|
5086
|
+
"unsupported"
|
|
5081
5087
|
];
|
|
5082
5088
|
/** What a proxy forwards: the house's devices and what a rule recognises, or everything. */
|
|
5083
5089
|
const BLUETOOTH_FORWARDING = ["house", "everything"];
|
|
@@ -5107,12 +5113,16 @@ const bluetoothAdvertSchema = z.object({
|
|
|
5107
5113
|
});
|
|
5108
5114
|
z.array(bluetoothAdvertSchema).max(1024);
|
|
5109
5115
|
/**
|
|
5110
|
-
* What a device that can be a proxy declares in its profile: the scan modes
|
|
5116
|
+
* What a device that can be a proxy declares in its profile: the scan modes its radio can run.
|
|
5111
5117
|
*/
|
|
5112
5118
|
const bluetoothProxyProfileSchema = z.strictObject({ modes: z.array(z.enum(BLUETOOTH_SCAN_MODES)).min(1).max(BLUETOOTH_SCAN_MODES.length).refine((modes) => new Set(modes).size === modes.length, "Each mode once") });
|
|
5113
5119
|
z.object({});
|
|
5114
5120
|
z.object({ mode: z.enum(BLUETOOTH_SCAN_MODES) });
|
|
5115
|
-
z.object({
|
|
5121
|
+
z.object({
|
|
5122
|
+
addresses: z.union([z.literal("all"), z.array(bluetoothAddressSchema).max(4096)]),
|
|
5123
|
+
/** Whether to scan actively until the next filter; absent or false rests in the install's mode. */
|
|
5124
|
+
active: z.boolean().optional()
|
|
5125
|
+
});
|
|
5116
5126
|
/** What `bluetooth-proxy.state` answers: a device that can be a proxy, and whether it is one. */
|
|
5117
5127
|
const bluetoothProxyStateSchema = z.discriminatedUnion("eligible", [z.object({
|
|
5118
5128
|
eligible: z.literal(true),
|
|
@@ -5139,6 +5149,13 @@ z.object({
|
|
|
5139
5149
|
data: bluetoothHexSchema,
|
|
5140
5150
|
withResponse: z.boolean().default(true)
|
|
5141
5151
|
});
|
|
5152
|
+
z.object({
|
|
5153
|
+
...gattTargetShape,
|
|
5154
|
+
notify: bluetoothUuidSchema,
|
|
5155
|
+
data: bluetoothHexSchema,
|
|
5156
|
+
withResponse: z.boolean().default(false),
|
|
5157
|
+
timeoutMs: z.int().min(100).max(1e4).default(5e3)
|
|
5158
|
+
});
|
|
5142
5159
|
z.object({
|
|
5143
5160
|
...gattTargetShape,
|
|
5144
5161
|
isOn: z.boolean()
|
|
@@ -5151,8 +5168,6 @@ const bluetoothSettingsSchema = z.object({
|
|
|
5151
5168
|
/** Which adapter, `hci0`; null for the first BlueZ has. */
|
|
5152
5169
|
adapterId: z.string().regex(/^hci\d{1,3}$/u).nullable().default(null),
|
|
5153
5170
|
localScanMode: z.enum(BLUETOOTH_SCAN_MODES).default("active"),
|
|
5154
|
-
/** How a new proxy scans. */
|
|
5155
|
-
proxyScanMode: z.enum(BLUETOOTH_SCAN_MODES).default("passive"),
|
|
5156
5171
|
/** Addresses not heard for this long are dropped. */
|
|
5157
5172
|
forgetAfterDays: z.int().min(1).max(365).default(7),
|
|
5158
5173
|
/** Whether Nearby lists private addresses: phones and watches that change theirs. */
|
|
@@ -5341,6 +5356,7 @@ const bluetoothScannerSchema = z.object({
|
|
|
5341
5356
|
chip: z.string().max(128).nullable(),
|
|
5342
5357
|
isOnline: z.boolean(),
|
|
5343
5358
|
isEnabled: z.boolean(),
|
|
5359
|
+
/** The adapter's setting; for a proxy, how it scans right now, as the hub asks. */
|
|
5344
5360
|
scanMode: z.enum(BLUETOOTH_SCAN_MODES),
|
|
5345
5361
|
canPassive: z.boolean(),
|
|
5346
5362
|
advertsPerMinute: z.int().min(0),
|
|
@@ -5380,19 +5396,12 @@ const bluetoothProxyCandidateSchema = z.object({
|
|
|
5380
5396
|
modes: z.array(z.enum(BLUETOOTH_SCAN_MODES)).max(BLUETOOTH_SCAN_MODES.length)
|
|
5381
5397
|
});
|
|
5382
5398
|
z.object({ items: z.array(bluetoothProxyCandidateSchema) });
|
|
5383
|
-
z.object({
|
|
5384
|
-
deviceId: integrationIdSchema,
|
|
5385
|
-
mode: z.enum(BLUETOOTH_SCAN_MODES)
|
|
5386
|
-
});
|
|
5387
5399
|
z.object({ deviceId: integrationIdSchema });
|
|
5388
5400
|
brokerJobSchemaOf([
|
|
5389
5401
|
"installing",
|
|
5390
5402
|
"started",
|
|
5391
5403
|
"first-report"
|
|
5392
|
-
]).extend({
|
|
5393
|
-
deviceId: integrationIdSchema,
|
|
5394
|
-
mode: z.enum(BLUETOOTH_SCAN_MODES)
|
|
5395
|
-
});
|
|
5404
|
+
]).extend({ deviceId: integrationIdSchema });
|
|
5396
5405
|
z.object({ jobId: z.string().min(1).max(64) });
|
|
5397
5406
|
z.object({ isRemoved: z.boolean() });
|
|
5398
5407
|
//#endregion
|
|
@@ -6599,6 +6608,12 @@ const vendorManifestSchema = z.strictObject({
|
|
|
6599
6608
|
*/
|
|
6600
6609
|
twins: z.array(z.enum(TWIN_FACTS)).min(1).max(TWIN_FACTS.length).optional(),
|
|
6601
6610
|
/**
|
|
6611
|
+
* Which way into a linked device is read first, by transport, best first - `["matter",
|
|
6612
|
+
* "bluetooth", "acme/cloud"]`: the way whose transport comes earliest is preferred when twins
|
|
6613
|
+
* are linked, and the owner may pick another. Absent, the device the house had first is.
|
|
6614
|
+
*/
|
|
6615
|
+
twinsPrefer: z.array(z.string().min(1).max(64)).min(1).max(8).optional(),
|
|
6616
|
+
/**
|
|
6602
6617
|
* Path to a `setup.json` of settings every device of this vendor shares - a cloud API key,
|
|
6603
6618
|
* an account - relative to the bundle. Absent for the vendors whose devices are reached
|
|
6604
6619
|
* directly, which is most of them.
|
|
@@ -8149,17 +8164,43 @@ const modbusDiscoverySchema = brokerDiscoverySchema("values.model").extend({
|
|
|
8149
8164
|
* the owner says which device it is.
|
|
8150
8165
|
*/
|
|
8151
8166
|
const serialDiscoverySchema = brokerDiscoverySchema("product");
|
|
8167
|
+
/** How many rule sets a vendor's `bluetooth` block may list. */
|
|
8168
|
+
const MAXIMUM_RULE_SETS = 4;
|
|
8169
|
+
/**
|
|
8170
|
+
* Some bytes of the hex at a path, read as a model: `bytes` is `[start, length]`, a start below
|
|
8171
|
+
* zero counted from the end, and `mask` is ANDed with every byte. What it reads is the bytes in
|
|
8172
|
+
* lower-case hex - `48` for a model letter `H` - and nothing when the data is shorter.
|
|
8173
|
+
*/
|
|
8174
|
+
const bytePlaceSchema = z.strictObject({
|
|
8175
|
+
path: pathSchema,
|
|
8176
|
+
bytes: z.tuple([z.int().min(-32).max(31), z.int().min(1).max(8)]),
|
|
8177
|
+
mask: z.int().min(0).max(255).optional()
|
|
8178
|
+
});
|
|
8179
|
+
/** Where an advertisement says its model: a path, or some of the bytes at one. */
|
|
8180
|
+
const modelPlaceSchema = z.union([pathSchema, bytePlaceSchema]);
|
|
8181
|
+
/** One way a vendor's devices advertise: the rules on it, and where it says its model. */
|
|
8182
|
+
const bluetoothRulesSchema = z.strictObject({
|
|
8183
|
+
/** Every condition must hold. All-of, and at least one: a vendor does not take every device. */
|
|
8184
|
+
match: z.array(claimConditionSchema).min(1).max(MAXIMUM_MATCH),
|
|
8185
|
+
/** Where the device says its model; several are tried in order. */
|
|
8186
|
+
model: z.union([modelPlaceSchema, z.array(modelPlaceSchema).min(1).max(4)]).default("name")
|
|
8187
|
+
});
|
|
8152
8188
|
/**
|
|
8153
8189
|
* Which of the devices the house's Bluetooth hears are the vendor's: rules on one advertisement (a
|
|
8154
8190
|
* {@link BluetoothSighting}) - its `name`; `manufacturerData.'<company id>'`, the id in decimal,
|
|
8155
8191
|
* that `exists` or `startsWith` the data's first bytes in hex; `serviceUuids`, which `contains` a
|
|
8156
8192
|
* UUID in lower case; `serviceData.'<uuid>'`, that `exists`. The model is `name` unless said, in
|
|
8157
|
-
* the drivers on the `bluetooth` transport
|
|
8193
|
+
* the drivers on the `bluetooth` transport, or some bytes of the data: `{ "path", "bytes": [start,
|
|
8194
|
+
* length], "mask" }`.
|
|
8195
|
+
*
|
|
8196
|
+
* One rule set, or a list of up to four for a vendor whose devices advertise in more than one way:
|
|
8197
|
+
* the first whose rules hold is the one whose model is read. Of several places for the model, the
|
|
8198
|
+
* first that reads a code one of the vendor's drivers maps is the model.
|
|
8158
8199
|
*
|
|
8159
8200
|
* A device the rules take is listed as found for the vendor, and added only by the owner: what a
|
|
8160
8201
|
* neighbour's sensor advertises is heard as well as the house's own.
|
|
8161
8202
|
*/
|
|
8162
|
-
const bluetoothDiscoverySchema =
|
|
8203
|
+
const bluetoothDiscoverySchema = z.union([bluetoothRulesSchema, z.array(bluetoothRulesSchema).min(1).max(MAXIMUM_RULE_SETS)]).transform((rules) => Array.isArray(rules) ? rules : [rules]);
|
|
8163
8204
|
/**
|
|
8164
8205
|
* The platform's brokers a vendor may take devices of, and the transport each reaches them on.
|
|
8165
8206
|
* Serial has none of its own: its devices are reached over their vendor's transport, through the
|
|
@@ -8361,7 +8402,49 @@ function associateModel(plan, modelCode, claimedBy) {
|
|
|
8361
8402
|
* @returns True when the vendor has the broker's block and every one of its conditions holds.
|
|
8362
8403
|
*/
|
|
8363
8404
|
function matchesBroker(plan, broker, identity) {
|
|
8364
|
-
return plan
|
|
8405
|
+
return rulesOf(plan, broker).some((rules) => holds(rules, identity));
|
|
8406
|
+
}
|
|
8407
|
+
/**
|
|
8408
|
+
* The rule sets of the vendor's block for a broker.
|
|
8409
|
+
*
|
|
8410
|
+
* @param plan - The vendor's discovery.
|
|
8411
|
+
* @param broker - Which broker.
|
|
8412
|
+
* @returns Bluetooth's list, the one block of another broker, or none without a block.
|
|
8413
|
+
*/
|
|
8414
|
+
function rulesOf(plan, broker) {
|
|
8415
|
+
const block = plan.discovery[broker];
|
|
8416
|
+
return block === void 0 ? [] : Array.isArray(block) ? block : [block];
|
|
8417
|
+
}
|
|
8418
|
+
/**
|
|
8419
|
+
* Whether every condition of a rule set holds.
|
|
8420
|
+
*
|
|
8421
|
+
* @param rules - The rule set.
|
|
8422
|
+
* @param identity - Who the device says it is.
|
|
8423
|
+
* @returns True when they all hold.
|
|
8424
|
+
*/
|
|
8425
|
+
function holds(rules, identity) {
|
|
8426
|
+
return rules.match.every((condition) => conditionHolds(condition, identity));
|
|
8427
|
+
}
|
|
8428
|
+
/**
|
|
8429
|
+
* Reads a model from one place.
|
|
8430
|
+
*
|
|
8431
|
+
* @param identity - Who the device says it is.
|
|
8432
|
+
* @param place - A path, or some bytes of the hex at one.
|
|
8433
|
+
* @returns The text, the bytes in lower-case hex, or null when there is none.
|
|
8434
|
+
*/
|
|
8435
|
+
function modelAt(identity, place) {
|
|
8436
|
+
if (typeof place === "string") return textAt(identity, place);
|
|
8437
|
+
const hex = resolvePath(identity, place.path);
|
|
8438
|
+
if (typeof hex !== "string" || !/^(?:[0-9a-f]{2})+$/iu.test(hex)) return null;
|
|
8439
|
+
const [first, length] = place.bytes;
|
|
8440
|
+
const start = first < 0 ? hex.length / 2 + first : first;
|
|
8441
|
+
if (start < 0 || (start + length) * 2 > hex.length) return null;
|
|
8442
|
+
let text = "";
|
|
8443
|
+
for (let at = start * 2; at < (start + length) * 2; at += 2) {
|
|
8444
|
+
const byte = Number.parseInt(hex.slice(at, at + 2), 16) & (place.mask ?? 255);
|
|
8445
|
+
text += byte.toString(16).padStart(2, "0");
|
|
8446
|
+
}
|
|
8447
|
+
return text;
|
|
8365
8448
|
}
|
|
8366
8449
|
/**
|
|
8367
8450
|
* Finds the driver of the vendor's that runs a device of one of the platform's brokers, and its
|
|
@@ -8369,7 +8452,8 @@ function matchesBroker(plan, broker, identity) {
|
|
|
8369
8452
|
*
|
|
8370
8453
|
* The model the device says is looked up in the `modelCodes` of the vendor's drivers on that
|
|
8371
8454
|
* 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.
|
|
8455
|
+
* the vendor's driver there when it has only one. Of several places for the model, the first that
|
|
8456
|
+
* reads a mapped code wins; Bluetooth reads the places of its first rule set that holds.
|
|
8373
8457
|
*
|
|
8374
8458
|
* @param plan - The vendor's discovery.
|
|
8375
8459
|
* @param broker - Which broker holds the device: `matter`, `mqtt`, `serial`.
|
|
@@ -8378,8 +8462,18 @@ function matchesBroker(plan, broker, identity) {
|
|
|
8378
8462
|
*/
|
|
8379
8463
|
function associateBroker(plan, broker, identity) {
|
|
8380
8464
|
const drivers = plan.drivers.filter((driver) => broker === "serial" ? driver.kind === "serial" : driver.transport === BROKER_TRANSPORTS[broker]);
|
|
8381
|
-
const
|
|
8382
|
-
const
|
|
8465
|
+
const sets = rulesOf(plan, broker);
|
|
8466
|
+
const places = (sets.find((rules) => holds(rules, identity)) ?? sets[0])?.model;
|
|
8467
|
+
/**
|
|
8468
|
+
* The vendor's drivers on the broker that map a code.
|
|
8469
|
+
*
|
|
8470
|
+
* @param code - What the device says its model is.
|
|
8471
|
+
* @returns Their entries.
|
|
8472
|
+
*/
|
|
8473
|
+
const codedOf = (code) => (plan.codes.get(code) ?? []).filter((entry) => drivers.some((driver) => driver.id === entry.driverId));
|
|
8474
|
+
const read = (Array.isArray(places) ? places : [places ?? BROKER_MODELS[broker]]).map((place) => modelAt(identity, place)).filter((code) => code !== null);
|
|
8475
|
+
const modelCode = read.find((code) => codedOf(code).length > 0) ?? read[0] ?? null;
|
|
8476
|
+
const [first] = modelCode === null ? [] : codedOf(modelCode);
|
|
8383
8477
|
if (first !== void 0) return {
|
|
8384
8478
|
driverId: first.driverId,
|
|
8385
8479
|
model: first.models.length === 1 ? first.models[0] ?? null : null,
|