@nebulahome/integration-sdk 0.0.0-stage → 1.1.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 +703 -0
- package/LICENSE +21 -0
- package/README.md +128 -2
- package/dist/chunks/node-dist.js +9253 -0
- package/dist/chunks/node-index.d.ts +2090 -0
- package/dist/chunks/node-project.js +545 -0
- package/dist/chunks/node-rolldown-runtime.js +24 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +3783 -0
- package/dist/index.d.ts +1427 -0
- package/dist/index.js +53 -0
- package/dist/schemas.d.ts +741 -0
- package/dist/schemas.js +53 -0
- package/dist/testing.d.ts +286 -0
- package/dist/testing.js +271 -0
- package/package.json +76 -3
- package/schemas/account.schema.json +595 -0
- package/schemas/discovery.schema.json +613 -0
- package/schemas/driver.schema.json +119 -0
- package/schemas/manifest.schema.json +557 -0
- package/schemas/profile.schema.json +1480 -0
- package/schemas/setup.schema.json +1166 -0
package/FILES.md
ADDED
|
@@ -0,0 +1,703 @@
|
|
|
1
|
+
# The vendor directory, file by file
|
|
2
|
+
|
|
3
|
+
What every file of an integration's `src/` says, in full: the grammar the hub's loader holds a
|
|
4
|
+
vendor to, with the reasons behind its limits. `README.md` is the short version and the commands;
|
|
5
|
+
`schemas/*.schema.json` are the same rules for an editor. Examples come from the vendors written
|
|
6
|
+
with the platform - Shelly, Bambu Lab, Sonoff, Zigbee2MQTT, ECOVACS, SolaX Power - each now in
|
|
7
|
+
its repository `integration-<vendor>`.
|
|
8
|
+
|
|
9
|
+
Loaded means present and offering to connect to devices; nothing is connected until somebody
|
|
10
|
+
adds one. Adding one is the whole of it: a device added from the vendor's page is an instance of its
|
|
11
|
+
driver and a row in the registry under one id, and the hub identifies the hardware behind it
|
|
12
|
+
by itself. A vendor with a `discovery.json` is also **found**: the hub listens for its devices
|
|
13
|
+
announcing themselves and the integrations page offers each one it hears to adopt - which is
|
|
14
|
+
adding it, with the driver, the model and the address already filled in. Nothing is added
|
|
15
|
+
until the owner says so.
|
|
16
|
+
|
|
17
|
+
A bundle is a **vendor directory** - an integration repository's `src/` - holding one **driver
|
|
18
|
+
directory** per profile or entry point:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
src/ the vendor shelly
|
|
22
|
+
├── manifest.json who the vendor is ← always
|
|
23
|
+
├── logo.svg the mark the interface shows (.svg or .png) ← optional
|
|
24
|
+
├── setup.json what every device of the vendor shares ← optional
|
|
25
|
+
├── discovery.json how its devices are found unasked ← optional
|
|
26
|
+
├── rpc/transport.ts a transport of the vendor's own ← optional
|
|
27
|
+
└── dimmer-pm/
|
|
28
|
+
├── driver.json transport, models, which file holds it ← always
|
|
29
|
+
├── setup.json what adding one device asks ← always
|
|
30
|
+
└── profile.json the declarative mapping (or index.ts, code) ← one of the two
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The repository's `README.md` says what the devices are and what is unverified; it stays out of
|
|
34
|
+
`src/`, which the build packs whole.
|
|
35
|
+
|
|
36
|
+
The directory names are the ids: `shelly` must say `"id": "shelly"` in its manifest and
|
|
37
|
+
`dimmer-pm` must say `"id": "dimmer-pm"` in its driver file, or the loader refuses the directory
|
|
38
|
+
and says which two names disagree. Together they make the driver's **kind**, `shelly/dimmer-pm`,
|
|
39
|
+
which is what a device row references.
|
|
40
|
+
|
|
41
|
+
`manifest.json` says who the vendor is. Which transports a vendor speaks is derived from its
|
|
42
|
+
drivers, so it cannot be declared wrongly; what the manifest may add is a transport the vendor
|
|
43
|
+
**ships** - see below:
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{
|
|
47
|
+
"id": "shelly",
|
|
48
|
+
"name": "Shelly",
|
|
49
|
+
"description": "Shelly devices of every generation on your own network: Gen2, Gen3 and Gen4 spoken to over their RPC interface, Gen1 over its HTTP API and the CoIoT packets it sends on every change.",
|
|
50
|
+
"url": "https://shelly.com",
|
|
51
|
+
"color": "#3B9DFF",
|
|
52
|
+
"logo": { "path": "./logo.svg", "padding": 4 },
|
|
53
|
+
"internetRequired": false,
|
|
54
|
+
"transports": {
|
|
55
|
+
"rpc": { "module": "./rpc/transport.js", "wires": ["http"] },
|
|
56
|
+
"gen1": { "module": "./gen1/transport.js", "wires": ["http"] }
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`logo` is a path relative to the bundle, either bare - `"logo": "./logo.svg"` - or, as above,
|
|
62
|
+
with `padding` (0 to 16, default 0): extra room, in pixels, the interface leaves around the logo
|
|
63
|
+
inside its tile. Every logo already gets a small margin; this is on top of it, for a mark drawn
|
|
64
|
+
to the very edge of its file. It cannot ask for less than the margin, only for more.
|
|
65
|
+
|
|
66
|
+
`requires` says what the vendor's devices need besides the hub, in the grammar a
|
|
67
|
+
package's manifest uses (PACKAGES.md §8, Dependencies):
|
|
68
|
+
`{ "services": ["mqtt-broker"] }` for Zigbee2MQTT, which talks through the house's broker, or a
|
|
69
|
+
package by id and range. Until what it needs runs, the vendor waits: its instances fail with the
|
|
70
|
+
sentence that names the package, `api` refuses its devices with `409 needs-package`, and its page
|
|
71
|
+
says so first. The hub follows the packages at every `pkg.*` event and starts only that vendor's
|
|
72
|
+
instances again when its standing changes. A container that speaks to the broker names its topics
|
|
73
|
+
in `mqttTopics`, and is given a username of its own held to them.
|
|
74
|
+
|
|
75
|
+
`driver.json` says how one profile is loaded and **which models it drives**. The list is what the
|
|
76
|
+
owner picks from when adding a device: Bambu Lab's `printer-p1-a1` driver lists five printers, so
|
|
77
|
+
the form offers five choices and the row remembers the one picked, though all five run the same
|
|
78
|
+
profile. A driver that lists no model offers its own name. Strict, and without the vendor's
|
|
79
|
+
fields on purpose - a driver repeating the vendor's name would be a second copy to keep in step:
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{
|
|
83
|
+
"id": "dimmer-pm",
|
|
84
|
+
"name": "Dimmer with power metering",
|
|
85
|
+
"transport": "shelly/rpc",
|
|
86
|
+
"models": ["Dimmer 0/1-10V PM Gen3", "Dimmer 0/1-10V PM Gen4", "Dimmer Gen3", "Dimmer Gen4"],
|
|
87
|
+
"modelCodes": {
|
|
88
|
+
"S3DM-0010WW": "Dimmer 0/1-10V PM Gen3",
|
|
89
|
+
"S4DM-0010WW": "Dimmer 0/1-10V PM Gen4",
|
|
90
|
+
"S3DM-0A101WWL": "Dimmer Gen3",
|
|
91
|
+
"S4DM-0A101WWL": "Dimmer Gen4"
|
|
92
|
+
},
|
|
93
|
+
"defaultIcon": "light",
|
|
94
|
+
"webPagePort": 80,
|
|
95
|
+
"kind": "declarative",
|
|
96
|
+
"profile": "./profile.json",
|
|
97
|
+
"setup": "./setup.json"
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`webPagePort` says the device serves a web page of its own, and on which port: a device of a
|
|
102
|
+
driver that names one gets a **Web page** link in the header of its page, to
|
|
103
|
+
`http://<host>:<port><webPagePath>`. `webPagePath` is optional and starts with `/` - Plex Web is at
|
|
104
|
+
`/web`. When the address the owner typed carries a port, that port wins: the device answers the
|
|
105
|
+
platform and the browser from the same server. A driver whose devices have no page to look at -
|
|
106
|
+
an API port answering JSON, a UDP protocol - names no port and gets no link.
|
|
107
|
+
|
|
108
|
+
`modelCodes` maps what the hardware calls itself onto the model on the box, and it is how
|
|
109
|
+
discovery knows which driver a device it heard belongs to and which model to adopt it as. A code
|
|
110
|
+
may name a list when the hardware says its family but not which of it it is - a Sonoff in DIY mode
|
|
111
|
+
announces `diy_plug` whether it is a BASICR3 or a MINI - and the owner then picks among those.
|
|
112
|
+
Every model named must be in `models`, and a driver that lists none maps no codes.
|
|
113
|
+
|
|
114
|
+
`modelSeries` puts each model in the series the vendor sells it as, for a vendor whose
|
|
115
|
+
drivers follow what the hardware needs rather than how the owner knows it: Bambu Lab's X1C and
|
|
116
|
+
X2D are both `"X series"`, run by two drivers because their entities differ. The form then groups
|
|
117
|
+
the vendor's models by series, across its drivers - the series by name, the models in each in
|
|
118
|
+
counting order - and a device's page says its series where it would say the driver's name. A
|
|
119
|
+
model given no series is grouped under its driver. Every model named must be in `models`.
|
|
120
|
+
|
|
121
|
+
`transport` is a platform transport - `http`, `mqtt`, `matter` - or one the driver's own vendor
|
|
122
|
+
ships, named after the vendor: `shelly/rpc`. Never another vendor's: vendors load in no particular
|
|
123
|
+
order, and a driver leaning on another's transport would load or not by luck.
|
|
124
|
+
|
|
125
|
+
A driver of the vendor's **Matter devices** is `"transport": "matter"` with `"kind": "matter"` and
|
|
126
|
+
neither a profile nor an entry: the platform's own Matter mapping runs it - lights, switches,
|
|
127
|
+
covers, locks, thermostats, the usual sensors, power and energy, the firmware - so the vendor's
|
|
128
|
+
Matter devices are its own, on its page, without code. Which devices those are its
|
|
129
|
+
`discovery.json` says (below), and `modelCodes` maps what they call their model - their product id,
|
|
130
|
+
unless the vendor says another field - onto the models it lists.
|
|
131
|
+
|
|
132
|
+
`defaultIcon` names the icon a device of this driver starts with, by its id in the platform's
|
|
133
|
+
icon catalogue (`packages/icons/catalogue.json` lists the platform's own ids - `light`,
|
|
134
|
+
`relay`, `printer`, `sensor`… - and every lucide icon is there under its own name). The owner
|
|
135
|
+
may pick another per device. The hub does not check the id; the API does when a device is
|
|
136
|
+
added, and falls back to no icon with a warning rather than refusing the device, so a typo in
|
|
137
|
+
somebody's bundle costs a blank tile and not the device.
|
|
138
|
+
|
|
139
|
+
Each entity in `profile.json` may name its own `icon` the same way - `"icon": "thermometer"` on
|
|
140
|
+
a temperature sensor - and it is the bundle's first word only: the owner may rename an entity
|
|
141
|
+
or pick another icon from the devices page, and identifying the hardware again does not put the
|
|
142
|
+
bundle's back. An entity that names none shows a blank tile until the owner picks one.
|
|
143
|
+
|
|
144
|
+
The format is `packages/package-runtime` and the ceiling it enforces is deliberate: every object
|
|
145
|
+
is strict and every expression is a path, so a profile cannot become a program one feature at a
|
|
146
|
+
time. A device whose entities are not known in advance needs a code driver instead. Two forms go
|
|
147
|
+
as far as the ceiling allows, and no further: a claim may ask that a path be **one of** a list of
|
|
148
|
+
values - `{ "path": "model", "oneOf": ["S3DM-0010WW", "S4DM-0010WW"] }`, which is how one driver
|
|
149
|
+
serves a family of models - and a state may be **looked up in a table** -
|
|
150
|
+
`{ "path": "'cover:0'.state", "map": { "opening": "opening" }, "default": "stopped" }`, which
|
|
151
|
+
renames what a device says into what a capability accepts. A list is membership, not an `or`
|
|
152
|
+
between paths; a table renames and cannot compute.
|
|
153
|
+
|
|
154
|
+
A condition, in a claim or a `discovery.json`, may also ask that a text **start** or **end** with
|
|
155
|
+
something (`startsWith`, `endsWith`, without regard to case - a MAC address's maker is its first
|
|
156
|
+
three bytes), that a text or a list **contain** something (`contains`: a part of a text, without
|
|
157
|
+
regard to case, or one item of a list - `{ "path": "deviceTypes", "contains": 266 }`), or that a
|
|
158
|
+
number lie **in a range** (`{ "path": "softwareVersion", "min": 10 }`, both ends included). There
|
|
159
|
+
is no regular expression, on purpose: one written badly holds the hub's thread for as long as it
|
|
160
|
+
backtracks, and the grammar is what keeps a bundle of data from doing that.
|
|
161
|
+
|
|
162
|
+
A third form reads whether something is **there** -
|
|
163
|
+
`{ "path": "sys.available_updates.stable", "present": true }` - true when the path names a value,
|
|
164
|
+
false when the object that would hold it is there without it. It is the one read that turns an
|
|
165
|
+
absence into an answer, and only where the report carries the holder: a report without `sys` at
|
|
166
|
+
all still says nothing.
|
|
167
|
+
|
|
168
|
+
A fourth reads **part of a number** - `{ "path": "device.bed.info.temp", "bits": [16, 16] }`, the
|
|
169
|
+
bits from the 16th, 16 of them - for firmware that packs two readings into one integer or a set
|
|
170
|
+
of flags into one word, and may be compared or looked up like any value:
|
|
171
|
+
`{ "path": "stat", "bits": [23, 1], "base": 16, "equals": 1 }` is a door, read out of a flags word
|
|
172
|
+
the printer writes as hexadecimal text. `base` alone reads a number written as text -
|
|
173
|
+
`{ "path": "humidity_raw", "base": 10 }` - and text that is no number yields nothing. It is
|
|
174
|
+
indexing into a number, as a path indexes into a list, and nothing more.
|
|
175
|
+
|
|
176
|
+
Finally a field may name **up to four places**, tried in order, the first that yields a value
|
|
177
|
+
being the one read - `[{ "path": "device.bed.info.temp", "bits": [0, 16] }, "bed_temper"]` -
|
|
178
|
+
for firmware that moved a reading and still sends it in either place.
|
|
179
|
+
|
|
180
|
+
An entity with the **`button`** capability (domain `button`) holds no state: it is reported, empty,
|
|
181
|
+
on anything its device says, so it is available exactly when the device is, and its one command is
|
|
182
|
+
`button.press`. A profile gives it `"state": {}` and the request pressing it sends. With
|
|
183
|
+
`"deviceClass": "restart"` the interface asks before pressing, since the device goes away for a
|
|
184
|
+
while.
|
|
185
|
+
|
|
186
|
+
An entity may report **attributes** beside its state: `"attributes": { "endsAt":
|
|
187
|
+
"pairing.endsAt" }`, each a camelCase key read the way a state field is, into a scalar. They are
|
|
188
|
+
for what a page needs of the entity and the entity itself is not - the Zigbee2MQTT bridge's
|
|
189
|
+
_Pairing_ sensor says `enabled` and carries when pairing closes as `endsAt`, which the vendor's
|
|
190
|
+
page counts down. Every report carries all of them, and one whose source names nothing is left
|
|
191
|
+
out, so an attribute that stopped being said is gone rather than stale.
|
|
192
|
+
|
|
193
|
+
A command's request carries values out of the command as **references** -
|
|
194
|
+
`{ "$": "command.level" }`. A device that counts in other units says so: `scale`
|
|
195
|
+
multiplies a number, `decimals` rounds it, `min` and `max` clamp it, in that order, and
|
|
196
|
+
`"optional": true` leaves the key out of the request when the command does not carry the value,
|
|
197
|
+
instead of sending `null`. That is how a fade reaches a Shelly dimmer, which takes seconds:
|
|
198
|
+
`"transition_duration": { "$": "command.transitionMs", "scale": 0.001, "decimals": 1,
|
|
199
|
+
"optional": true }`. A reference is still a path and nothing more; anything it does not name is a
|
|
200
|
+
literal.
|
|
201
|
+
|
|
202
|
+
A light that can **fade** says so on each capability that can: `"on_off": { "hasTransition":
|
|
203
|
+
true }`, and the same on `level`, `color_hs` and `color_temp`. The
|
|
204
|
+
platform drops `transitionMs` from a command to a capability that does not say so, and the editor
|
|
205
|
+
offers no Transition field for it, so a lamp that changes at once is never promised a fade. A
|
|
206
|
+
device added before its driver said so keeps what it was added with until it is added again.
|
|
207
|
+
|
|
208
|
+
### Firmware updates
|
|
209
|
+
|
|
210
|
+
A driver whose devices say which firmware they run and what is on offer exposes one entity of domain
|
|
211
|
+
`update` with the `update` capability: `installedVersion`, `latestVersion` (absent - null - when
|
|
212
|
+
nothing newer is offered), `isInstalling` and, for a device that says, `progress`; its one command
|
|
213
|
+
is `update.install`. `canInstall: false` in its params says the platform cannot install it, only
|
|
214
|
+
tell. The hub refuses an install while the entity reads `isInstalling`, for every vendor: a device
|
|
215
|
+
fetching its firmware still offers it until it reboots, and an automation installing whatever is
|
|
216
|
+
offered must not start it again.
|
|
217
|
+
|
|
218
|
+
The Shelly drivers read `device_info.ver` (the transport asks `Shelly.GetDeviceInfo` on every
|
|
219
|
+
connection and lays it beside the status), `sys.available_updates.stable.version`, and
|
|
220
|
+
`ota.isInstalling` / `ota.progress`, which the transport keeps from the device's `NotifyEvent`s
|
|
221
|
+
(`ota_begin`, `ota_progress`, `ota_success`, `ota_error`) and from the moment `Shelly.Update` was
|
|
222
|
+
accepted, until the device is back on another version; a second `Shelly.Update` meanwhile is not
|
|
223
|
+
sent. The Gen1 drivers read `update.old_version`, `update.new_version` and `update.status`
|
|
224
|
+
(`updating`) and install through `/ota?update=true`. The device checks for updates itself, over
|
|
225
|
+
the internet; one that cannot reach the internet never offers one.
|
|
226
|
+
|
|
227
|
+
A profile may also say where its reports carry the firmware the device runs now -
|
|
228
|
+
`"device": { "swVersion": "device_info.ver" }` - and the hub then writes a changed version on the
|
|
229
|
+
device's row as it hears it, so the device page follows an update without the device being added
|
|
230
|
+
again.
|
|
231
|
+
|
|
232
|
+
The logo rides inside the catalogue the hub serves, as a data URL, so it must be an `.svg` or a
|
|
233
|
+
`.png` and at most 64 KiB; anything else fails the vendor at startup. Draw a monogram in the
|
|
234
|
+
vendor's colour - nobody's trademark -; the interface draws the same monogram itself for a vendor
|
|
235
|
+
that ships no logo at all.
|
|
236
|
+
|
|
237
|
+
## `discovery.json` - how the devices are found
|
|
238
|
+
|
|
239
|
+
A vendor whose devices announce themselves says how in `discovery.json`, and the hub does the same
|
|
240
|
+
six steps for every vendor that has one: **listen**, **match**, **probe**, **identify**, then the
|
|
241
|
+
two that are the hub's - **associate** the model with a driver through its `modelCodes`, and
|
|
242
|
+
**propose** the device on the integrations page. No address is swept and no port scanned: the
|
|
243
|
+
hub hears announcements, asks the question the protocol exists for, and probes an address only
|
|
244
|
+
because a device announced it there.
|
|
245
|
+
|
|
246
|
+
```json
|
|
247
|
+
{
|
|
248
|
+
"listen": [{ "mdns": "_shelly._tcp" }, { "mdns": "_http._tcp" }],
|
|
249
|
+
"match": [{ "path": "instance", "startsWith": "shelly" }],
|
|
250
|
+
"probe": { "transport": "http", "op": "get", "args": { "path": "/shelly" }, "timeoutMs": 10000 },
|
|
251
|
+
"identity": {
|
|
252
|
+
"externalId": ["id", "mac"],
|
|
253
|
+
"name": "name",
|
|
254
|
+
"model": ["model", "type"],
|
|
255
|
+
"swVersion": ["ver", "fw"]
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
- `listen` - up to four sources: `{ "mdns": "_name._tcp" }`, a service the platform browses for,
|
|
261
|
+
or `{ "module": "./lan/discovery.js" }`, a listener of the vendor's own (below). An mDNS
|
|
262
|
+
announcement is read as `{ service, instance, host, address, port, txt: { … } }`, and the device
|
|
263
|
+
is reached at `address`, with `:port` when it is not 80.
|
|
264
|
+
- `match` - conditions in the claim's grammar, all of which must hold of the announcement: for a
|
|
265
|
+
service other vendors announce too. `startsWith` is a prefix compared without regard to case -
|
|
266
|
+
what Shelly needs on `_http._tcp`, which every printer and NAS announces as well.
|
|
267
|
+
- `probe` - optional: a request, in a transport's words - the vendor's own or a platform one -
|
|
268
|
+
asked of the announced address with the vendor's saved settings beneath it. Its answer is what
|
|
269
|
+
`identity` reads, and it should be the same question the drivers' `discovery.probe` asks, so the
|
|
270
|
+
id discovery finds is the id identification then insists on. Without one, `identity` reads the
|
|
271
|
+
announcement, and must then say where the model is: without a probe the drivers' own claims have
|
|
272
|
+
nothing to read. `timeoutMs` (0.5 to 30 s, four when absent) gives slow devices longer and is
|
|
273
|
+
handed to the transport as its own `timeoutMs`: a Shelly on a weak Wi-Fi link took eight seconds
|
|
274
|
+
to answer its first request after a silence.
|
|
275
|
+
- `identity` - paths to the model code, the id, the name and the firmware version. Only the model
|
|
276
|
+
is ever required. A field may be a list of paths, tried in order, for generations that answer
|
|
277
|
+
in different words: a Shelly Gen1 says `type`, `mac` and `fw` where later ones say `model`,
|
|
278
|
+
`id` and `ver`.
|
|
279
|
+
- `adopt` - who adds a device found: `owner` (the default) proposes it on the vendor's
|
|
280
|
+
page to adopt; `automatic` has `api` add it as soon as the hub proposes it, named as it named
|
|
281
|
+
itself, with the id the add form would have offered - for devices the owner already chose
|
|
282
|
+
somewhere else: a Zigbee device paired with Zigbee2MQTT, a mower bound to an ECOVACS account.
|
|
283
|
+
Such a vendor's page has no **Add device**, no **Discover devices** and nothing to adopt, and a
|
|
284
|
+
device removed there comes back while the vendor still lists it.
|
|
285
|
+
- `pairing` - `{ "driver": "bridge", "open": "permit_join", "close":
|
|
286
|
+
"permit_join_stop", "state": "pairing" }`: the entities of one of the
|
|
287
|
+
vendor's drivers pairing is run by, by object id - the button that opens it, the one that closes
|
|
288
|
+
it, and the text sensor saying `enabled` while it is open, with when it closes in its `endsAt`
|
|
289
|
+
attribute. The vendor's page offers them as **Pair devices** / **Stop**, read live, in place of
|
|
290
|
+
looking for devices.
|
|
291
|
+
|
|
292
|
+
The hub asks mDNS from every network interface of the machine, one question a packet, when it
|
|
293
|
+
starts - at 0, 1, 3, 8, 15, 30 and 60 seconds, since a question over multicast is easily lost - and
|
|
294
|
+
again every `HUB_DISCOVERY_QUERY_INTERVAL_MS`; an answer that names a device without its SRV, TXT
|
|
295
|
+
or A record is completed by asking for that record by name. An address that did not answer its
|
|
296
|
+
probe is asked again on a timer - after five seconds, then thirty, then sixty - rather than at the
|
|
297
|
+
next announcement, and an address already added is not probed at all. An owner can have it look
|
|
298
|
+
**now**: **Discover devices** on a vendor's page asks that vendor again every second or two for
|
|
299
|
+
thirty seconds (`POST /api/v1/discovery/scan`, the hub's `discover` method, which answers how long
|
|
300
|
+
it looks), and the page then says what it found. A vendor with no `discovery.json` offers no
|
|
301
|
+
button, and its devices are added by address. What is found is shown on the vendor's own page,
|
|
302
|
+
above its devices.
|
|
303
|
+
|
|
304
|
+
The model code is looked up in every driver's `modelCodes`; with a probe, the driver's own claim
|
|
305
|
+
must also take what the probe returned - a Pro 3EM reports one code in both its profiles and only
|
|
306
|
+
the triphase one is the `3em` driver's - and when no driver maps the code, the drivers' own claims
|
|
307
|
+
decide, in load order. Two drivers may map one code only when the vendor probes - a Shelly 2PM
|
|
308
|
+
reports one code as relays or as a cover, and each driver's claim reads its profile. A device no
|
|
309
|
+
driver takes is not proposed, and the hub logs its model once at info: it is the answer to "why is
|
|
310
|
+
my device not found". A `discovery.json` that does not load leaves the vendor loaded without discovery, and the
|
|
311
|
+
failure names the file.
|
|
312
|
+
|
|
313
|
+
**Matter devices.** The house's Matter devices are commissioned on the platform's Brokers page,
|
|
314
|
+
with the code the maker's app - or Google Home, Apple Home, Alexa - shares, and each is then added
|
|
315
|
+
at once to the vendor whose `matter` rules take it:
|
|
316
|
+
|
|
317
|
+
```json
|
|
318
|
+
{
|
|
319
|
+
"matter": {
|
|
320
|
+
"match": [{ "path": "vendorId", "equals": 5264 }],
|
|
321
|
+
"model": "productId"
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
- `match` - at least one condition, all of which must hold of who the device says it is: its
|
|
327
|
+
`vendorId` and `productId` (numbers), `vendorName`, `productName`, `productLabel`, `nodeLabel`,
|
|
328
|
+
`serialNumber`, `uniqueId`, `hardwareVersion`, `softwareVersion` (numbers) and their `…String`
|
|
329
|
+
texts, `macAddresses` (a list of `aa:bb:cc:dd:ee:ff`), `deviceTypes` and `clusters` (lists of
|
|
330
|
+
numbers), `isBridge` and `isBridged`. A field the device does not say is `null`. The vendor id is
|
|
331
|
+
the one to rule on: the CSA assigns it to the maker, and it does not change with a name.
|
|
332
|
+
- `model` - where the device says its model, looked up in the `modelCodes` of the vendor's drivers
|
|
333
|
+
that say `"kind": "matter"`; `productId` when absent. A model no driver maps goes to the vendor's
|
|
334
|
+
Matter driver when it has only one. Matter devices are added on their own, with no one to pick a
|
|
335
|
+
model: a Matter driver that lists models must map every product in `modelCodes`, or a product
|
|
336
|
+
it misses is never added. A driver that lists none takes them all, under its own name.
|
|
337
|
+
|
|
338
|
+
A vendor may have `matter` alone, with no `listen`. A device behind a Matter bridge is a device of
|
|
339
|
+
its own, ruled on by what the bridge says of it. A device that more than one vendor's rules take,
|
|
340
|
+
and one that none takes, is added as the platform's own Matter device, and the Brokers page says
|
|
341
|
+
which vendors want it. Removing a Matter device from the house takes it off the house's fabric; it
|
|
342
|
+
stays in the other apps it was shared from.
|
|
343
|
+
|
|
344
|
+
**A listener of the vendor's own** is a module - plain JavaScript, like a transport, handed the
|
|
345
|
+
same SDK - whose default export returns `{ listen(signal, context), scan?() }`: an async iterable
|
|
346
|
+
of sightings, `{ config: { host }, payload }`, reported as they happen until the signal ends it,
|
|
347
|
+
and, optionally, a way to ask the network again now, which the owner's scan calls - its answers
|
|
348
|
+
arrive through `listen` like every other. `context.settings()` reads what the owner saved
|
|
349
|
+
for the vendor, secrets opened, for a listener that asks a cloud which devices an account has; read
|
|
350
|
+
it at every pass and a change is heard without the listener being started again. It listens and
|
|
351
|
+
reports; which driver a device belongs to stays the business of `discovery.json`. A sighting at a
|
|
352
|
+
public address is not followed.
|
|
353
|
+
|
|
354
|
+
The context also takes two things the vendor's page shows, both optional for the hub to
|
|
355
|
+
offer, so a listener calls them as `context.status?.(…)`:
|
|
356
|
+
|
|
357
|
+
- `status({ level, message })` - how listening goes: `ok`, `warning` (listening, and hearing
|
|
358
|
+
nothing it should - Zigbee2MQTT silent on the broker), `error` (it cannot listen - the broker
|
|
359
|
+
refuses). The last one said stands; anything but `ok` is a callout on the vendor's page, with the
|
|
360
|
+
way to the vendor's container log.
|
|
361
|
+
- `passedOver([{ id, name, model, reason }])` - every device it heard and does not report, the
|
|
362
|
+
whole list each time: one still being paired, one its program does not support. The page lists
|
|
363
|
+
them under **Seen but not added**, with the reason, beside the devices the hub heard that no
|
|
364
|
+
driver takes, which the hub adds on its own.
|
|
365
|
+
|
|
366
|
+
## `account.json` - the account the devices are reached through
|
|
367
|
+
|
|
368
|
+
A vendor whose devices are reached through an account - a cloud's, an app's - names an
|
|
369
|
+
`account.json` in its manifest (`"account": "./account.json"`) instead of asking for an email and
|
|
370
|
+
a password in its `setup.json`:
|
|
371
|
+
|
|
372
|
+
```json
|
|
373
|
+
{
|
|
374
|
+
"name": "ECOVACS HOME account",
|
|
375
|
+
"help": "The account the ECOVACS HOME app signs in with.",
|
|
376
|
+
"fields": {
|
|
377
|
+
"fields": [
|
|
378
|
+
{ "key": "email", "type": "text", "label": "Email", "isRequired": true },
|
|
379
|
+
{ "key": "password", "type": "secret", "label": "Password", "isRequired": true }
|
|
380
|
+
]
|
|
381
|
+
},
|
|
382
|
+
"identity": "email",
|
|
383
|
+
"module": "./cloud/sign-in.js"
|
|
384
|
+
}
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
`fields` is a setup group - constants and fields, `shownWhen` and all - and `identity` the field
|
|
388
|
+
the account's card is named by, which may not be a secret. The vendor's page shows an **Account**
|
|
389
|
+
card: each account signed in to, where it stands, **Sign in again** and **Remove**, and **Add
|
|
390
|
+
account** - a vendor holds as many as the house has. There is no Configure for an account.
|
|
391
|
+
|
|
392
|
+
The module default-exports a function of the SDK returning `sdk.defineAccount({ signIn, answer,
|
|
393
|
+
poll?, signOut? })`. Each is handed a `{ signal }` it must honour - a step has a minute - and
|
|
394
|
+
answers a step:
|
|
395
|
+
|
|
396
|
+
- `{ kind: 'connected', identity: { id, label }, session }` - signed in: `id` is the account's own
|
|
397
|
+
at its cloud, the one a device names; `session` what to keep for the next start - tokens, a user
|
|
398
|
+
id - sealed by the hub;
|
|
399
|
+
- `{ kind: 'ask', message, fields, pending }` - the cloud wants more: a code it emailed, a second
|
|
400
|
+
factor. `fields` are setup fields; `pending` is anything the module needs to carry on, handed
|
|
401
|
+
back to `answer(pending, answers)` - kept in the hub's memory only, for fifteen minutes;
|
|
402
|
+
- `{ kind: 'link', message, url, code?, pollMs, pending }` - the owner approves on the cloud's
|
|
403
|
+
page; `poll(pending)` is called every `pollMs` until it answers something else;
|
|
404
|
+
- `{ kind: 'failed', message, field? }` - it did not work; `field` names the one to correct.
|
|
405
|
+
|
|
406
|
+
A throw is a `failed` step with the error's message. What the owner typed reaches `signIn` with
|
|
407
|
+
its secrets opened; the hub keeps it sealed with the account, so a transport can sign in again
|
|
408
|
+
when the session expires.
|
|
409
|
+
|
|
410
|
+
**At run time**, a device of the account names it in its configuration (`transportConfig.account`
|
|
411
|
+
|
|
412
|
+
- the listener's sighting says so), and its transport is handed `context.account`: `{ id, label,
|
|
413
|
+
status, credentials, session, update(session), needsSignIn(message) }`. Keep a renewed session
|
|
414
|
+
with `update`; when the cloud wants the owner again - a new code - call `needsSignIn` with a
|
|
415
|
+
sentence, and the card asks. A listener gets `context.accounts()`, every account signed in to,
|
|
416
|
+
read at every pass. Signing in or out starts the vendor's instances again and asks its listener
|
|
417
|
+
to look now (`scan`), so an `automatic` vendor's devices appear the moment the account is
|
|
418
|
+
connected.
|
|
419
|
+
|
|
420
|
+
## `setup.json` - what adding a device asks
|
|
421
|
+
|
|
422
|
+
`driver.json` says what a driver is and `profile.json` says how it maps a device; the driver's
|
|
423
|
+
`setup.json` says what the form asks when an owner adds a device by hand. The interface builds
|
|
424
|
+
the form from it, the API checks what was typed against it, and the hub never reads it for
|
|
425
|
+
anything else - so a driver that needs a new field adds a line here and nothing else changes.
|
|
426
|
+
|
|
427
|
+
A **vendor** may ship a `setup.json` of its own, in exactly the same grammar, for what every
|
|
428
|
+
device of theirs shares - a cloud API key, an account: Govee asks for its optional cloud account
|
|
429
|
+
there, Zigbee2MQTT for its coordinator. When one does, the interface asks for it once, from the
|
|
430
|
+
vendor's page, and refuses to add a device until it has been given; the hub then puts the vendor's answers under every instance it starts, lowest first:
|
|
431
|
+
the vendor's settings, then the driver's constants, then what the owner typed for that device.
|
|
432
|
+
A vendor-level field must therefore be a key the transport understands, the same as a
|
|
433
|
+
driver-level one.
|
|
434
|
+
|
|
435
|
+
```json
|
|
436
|
+
{
|
|
437
|
+
"transport": {
|
|
438
|
+
"constants": { "username": "bblp", "shouldVerifyCertificate": false },
|
|
439
|
+
"fields": [
|
|
440
|
+
{
|
|
441
|
+
"key": "url",
|
|
442
|
+
"type": "text",
|
|
443
|
+
"label": "Printer address",
|
|
444
|
+
"isRequired": true,
|
|
445
|
+
"placeholder": "mqtts://192.168.1.60:8883",
|
|
446
|
+
"pattern": "^mqtts://[^/ ]+$",
|
|
447
|
+
"patternMessage": "Must start with mqtts://, the printer only speaks TLS.",
|
|
448
|
+
"help": "The printer's LAN address on port 8883."
|
|
449
|
+
},
|
|
450
|
+
{
|
|
451
|
+
"key": "password",
|
|
452
|
+
"type": "secret",
|
|
453
|
+
"label": "Access code",
|
|
454
|
+
"isRequired": true,
|
|
455
|
+
"minLength": 8,
|
|
456
|
+
"maxLength": 8
|
|
457
|
+
}
|
|
458
|
+
]
|
|
459
|
+
},
|
|
460
|
+
"options": { "fields": [] }
|
|
461
|
+
}
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
Two groups, one per column of `registry.integrations` (or of `registry.integration_vendors`,
|
|
465
|
+
for a vendor's own): `transport` becomes `transport_config`, the settings the transport opens a
|
|
466
|
+
connection with, and `options` becomes `options`, whatever the integration itself takes (it may
|
|
467
|
+
be left out). Each group has:
|
|
468
|
+
|
|
469
|
+
- `constants` - values the bundle fixes and the form never shows. They are written into the row
|
|
470
|
+
by the API beside what the owner typed, and refused if a client sends them: a printer that only
|
|
471
|
+
ever logs in as `bblp` says so here, and nobody can turn certificate checking back on for it.
|
|
472
|
+
- `fields` - what the form asks, in this order. Every field has a `key` (a camelCase
|
|
473
|
+
identifier, the JSON key it is stored under), a `label`, an optional `help` line and
|
|
474
|
+
`isRequired`. The `type` decides the control and the checks:
|
|
475
|
+
|
|
476
|
+
| Type | Control | Checks |
|
|
477
|
+
| --------- | -------------------- | ------------------------------------------------------------------------------------- |
|
|
478
|
+
| `text` | text field | `minLength`, `maxLength` (512), `pattern`, `patternMessage`, `default`, `placeholder` |
|
|
479
|
+
| `secret` | password field | as `text`; **sealed** before it is stored, never served back |
|
|
480
|
+
| `number` | number field | `min`, `max`, `isInteger`, `unit`, `default`, `warnBelow` + `warning` |
|
|
481
|
+
| `boolean` | on/off switch | `default` |
|
|
482
|
+
| `choice` | select | `choices: [{ value, label }]`, `default` |
|
|
483
|
+
| `list` | comma-separated text | `minItems`, `maxItems` (64), `pattern` and `patternMessage` per item |
|
|
484
|
+
|
|
485
|
+
A `number` with `warnBelow` accepts a smaller value but says, under the field, what it costs - the
|
|
486
|
+
bundle's `warning`, or that it is below what is advised.
|
|
487
|
+
|
|
488
|
+
**A field asked only after a choice.** `shownWhen: { "key": "connection", "equals": ["dongle"] }`
|
|
489
|
+
shows a field only while an earlier `choice` or `boolean` of the same group holds one of the
|
|
490
|
+
values - the choice's `default` counting when nothing was picked. The field it names must come
|
|
491
|
+
first, must itself be always asked, and must be able to hold every value listed; the bundle fails
|
|
492
|
+
to load otherwise. A field a choice hides is neither shown, required, defaulted nor sent, and the
|
|
493
|
+
API drops its value from a new configuration, so a SolaX inverter read over Modbus is never asked
|
|
494
|
+
for its dongle's password:
|
|
495
|
+
|
|
496
|
+
```json
|
|
497
|
+
{
|
|
498
|
+
"fields": [
|
|
499
|
+
{
|
|
500
|
+
"key": "connection",
|
|
501
|
+
"type": "choice",
|
|
502
|
+
"label": "Connection",
|
|
503
|
+
"choices": [
|
|
504
|
+
{ "value": "modbus", "label": "Modbus TCP" },
|
|
505
|
+
{ "value": "dongle", "label": "Web API" }
|
|
506
|
+
],
|
|
507
|
+
"default": "modbus"
|
|
508
|
+
},
|
|
509
|
+
{
|
|
510
|
+
"key": "unitId",
|
|
511
|
+
"type": "number",
|
|
512
|
+
"label": "Modbus unit ID",
|
|
513
|
+
"default": 1,
|
|
514
|
+
"shownWhen": { "key": "connection", "equals": ["modbus"] }
|
|
515
|
+
},
|
|
516
|
+
{
|
|
517
|
+
"key": "password",
|
|
518
|
+
"type": "secret",
|
|
519
|
+
"label": "Web page password",
|
|
520
|
+
"shownWhen": { "key": "connection", "equals": ["dongle"] }
|
|
521
|
+
}
|
|
522
|
+
]
|
|
523
|
+
}
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
When discovery filled the choice, the adopt dialog does not ask it, nor the fields its answer
|
|
527
|
+
hides.
|
|
528
|
+
|
|
529
|
+
**How often a polled device is read** is the owner's choice. A driver whose profile reads the
|
|
530
|
+
device on a timer - a subscription with `op: "poll"` and `everyMs` - declares `polling`, in whole
|
|
531
|
+
seconds:
|
|
532
|
+
|
|
533
|
+
```json
|
|
534
|
+
{
|
|
535
|
+
"transport": { "fields": [] },
|
|
536
|
+
"polling": { "default": 30, "min": 5, "warnBelow": 10 }
|
|
537
|
+
}
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
The hub turns it into the option `pollInterval`, "Update every … s": required, never 0 (`min` is
|
|
541
|
+
at least 1), up to `max` (a day when absent), filled with `default`, and warning below
|
|
542
|
+
`warnBelow`. The API stores and changes it like any option, and a change restarts the instance. At
|
|
543
|
+
runtime the chosen interval replaces `everyMs` in every subscription of the profile that has one; a
|
|
544
|
+
subscription without `everyMs` - a topic, a push - is left alone, and the transport's own floor
|
|
545
|
+
still holds. `default × 1000` must be the profile's `everyMs` (what a device added before the option
|
|
546
|
+
existed is read at), and a driver that does not poll must not declare it - a vendor's tests should
|
|
547
|
+
check both, as every vendor written with the platform does. Never declare a field called `pollInterval` yourself. A push transport's periodic full
|
|
548
|
+
re-read (Shelly's `status`) is a safety net, not a poll, and has no `polling`.
|
|
549
|
+
|
|
550
|
+
A `secret` value is encrypted with `NEBULA_SECRETS_KEY` by the API before it reaches the
|
|
551
|
+
database and decrypted by the hub when the instance starts; the interface only ever learns that
|
|
552
|
+
one is kept. A `pattern` is a regular expression source and must compile, or the bundle fails to
|
|
553
|
+
load - which is the point: a typo here is found at startup rather than on somebody's form. Give
|
|
554
|
+
it a `patternMessage` whenever the pattern encodes a fact about the device: the form shows that
|
|
555
|
+
sentence under the field, where the pattern itself would tell a person nothing.
|
|
556
|
+
|
|
557
|
+
**Test** in the interface opens the bundle's transport once with what was typed and closes it
|
|
558
|
+
again, keeping nothing: for MQTT that is one session, for HTTP one request to the address. The
|
|
559
|
+
verdict is a sentence in the transport's own words, so `Not authorized` and `ECONNREFUSED` send
|
|
560
|
+
an owner to different places. When the vendor's `discovery.json` probes, the Test asks the device
|
|
561
|
+
that question too, and the form preselects the model it says it is.
|
|
562
|
+
|
|
563
|
+
**What the `http` transport takes.** A request template's `op` is the verb - `get`, `post`,
|
|
564
|
+
`put`, `patch`, `delete` - with `path`, `query` and a `body` sent as JSON; a `poll` names its verb
|
|
565
|
+
in `method`. Beyond `host`, `isSecure`, `timeoutMs` and basic auth (`username`, `password`), the
|
|
566
|
+
transport configuration takes what a setup fills and the profile never sees: a `token` (a secret
|
|
567
|
+
field), sent in the header `tokenHeader` names (with `tokenPrefix` in front, `Bearer ` for one) or
|
|
568
|
+
put into the path by `pathPrefix`, where `{token}` stands for it - `/api/v1/{token}` - and
|
|
569
|
+
`shouldVerifyCertificate: false` for a device that signs its own certificate. The bundle fixes
|
|
570
|
+
the header, the prefix and the certificate check as constants; the owner types the token.
|
|
571
|
+
|
|
572
|
+
**Save** creates the device and starts it. The hub has no claim for a device it has never heard
|
|
573
|
+
from, so it reports the instance `identifying` and listens with the driver's `discovery` -
|
|
574
|
+
the MQTT subscription, the probe of the address - until the driver claims what answers; then it
|
|
575
|
+
asks `core` to complete the device's row with the serial, the claim and the entities, and the
|
|
576
|
+
instance is `running`. The claim stays on the row, so the next start binds the device without
|
|
577
|
+
listening again. A device that stays `identifying` is one the hub cannot hear, or one no driver
|
|
578
|
+
claims: the hub logs what answered and what it said of itself, and each bundle below says what
|
|
579
|
+
to look at.
|
|
580
|
+
|
|
581
|
+
## A transport of the vendor's own
|
|
582
|
+
|
|
583
|
+
A vendor whose devices speak a protocol the hub does not may ship the transport itself. The
|
|
584
|
+
manifest names it - `"transports": { "rpc": "./rpc/transport.js" }` - and the hub loads the
|
|
585
|
+
module when it loads the vendor, before the drivers, and registers what it builds as
|
|
586
|
+
`<vendor>/<name>`: `shelly/rpc`. Its drivers then say `"transport": "shelly/rpc"`, and nothing
|
|
587
|
+
else about them changes: they stay declarative, and the profile's requests are in the new
|
|
588
|
+
transport's own words.
|
|
589
|
+
|
|
590
|
+
A transport of the vendor's own is named nowhere a person would recognise - `shelly/rpc` means
|
|
591
|
+
nothing on the vendor's card - so the manifest may say which **wires** it goes over, in the long
|
|
592
|
+
form of the entry: `{ "module": "./rpc/transport.js", "wires": ["http"] }`. The card shows one mark
|
|
593
|
+
per wire, beside the marks of the platform's own transports the drivers speak (`http`, `mqtt`,
|
|
594
|
+
`ble`, `zigbee`). The wires are `http`, `mqtt`, `ble`, `zigbee`, `udp` (a protocol of the
|
|
595
|
+
device's own in plain datagrams on the network, as Govee's LAN API) and `modbus` (Modbus TCP).
|
|
596
|
+
zigbee2mqtt's transport says `["mqtt", "zigbee"]`: it listens on the broker, and its devices are
|
|
597
|
+
Zigbee. A bare path declares none, and the card shows no mark for that transport.
|
|
598
|
+
|
|
599
|
+
The module is TypeScript in `src/`, built by `nebulahome-integration build` into the JavaScript
|
|
600
|
+
the manifest names, and its default export - typed with `defineTransportModule` - is a function
|
|
601
|
+
the hub calls with the **SDK**, the runtime's pieces a transport needs, since the bundle cannot
|
|
602
|
+
import them:
|
|
603
|
+
|
|
604
|
+
| `sdk.` | What |
|
|
605
|
+
| -------------------- | ---------------------------------------------------------------------------------- |
|
|
606
|
+
| `version` | the runtime version, the one `manifest.sdk` was matched against |
|
|
607
|
+
| `z` | the runtime's zod, so the transport's settings validate as the hub's do |
|
|
608
|
+
| `defineTransport` | the contract the platform's own transports are written against |
|
|
609
|
+
| `openWebSocket` | a WebSocket the hub keeps open: reconnection with a doubling pause, resets |
|
|
610
|
+
| `openUdpSocket` | a UDP socket the hub binds, joins to a multicast group, and closes with the vendor |
|
|
611
|
+
| `openMqtt` | an MQTT session with a client certificate, for a vendor's own broker |
|
|
612
|
+
| `defineStreamSource` | the contract a camera's stream source is written against |
|
|
613
|
+
| `openRtsp` | an RTSP(S) session over TCP, yielding a camera's H.264 as it comes |
|
|
614
|
+
| `platform.mqtt` | the platform's own MQTT broker, or null on an installation without one |
|
|
615
|
+
| `defineAccount` | the contract an account's sign-in module is written against |
|
|
616
|
+
| `codecs.lzma` | unpacks an LZMA stream in the alone format, as some clouds pack maps |
|
|
617
|
+
| `images.png` | encodes a picture of a palette as a PNG, for an image entity |
|
|
618
|
+
| `logger` | the hub's logger, for what happens outside a connection |
|
|
619
|
+
|
|
620
|
+
`openWebSocket` also takes `headers` - sent on every handshake and never logged, or a
|
|
621
|
+
function called before each attempt, for a token that expires - `ping: { everyMs, timeoutMs }`,
|
|
622
|
+
which drops and reopens a socket whose peer stopped answering, and `tls: { rejectUnauthorized }`;
|
|
623
|
+
and `onClose` is told the close code and, for a handshake the server refused, its HTTP `status`,
|
|
624
|
+
so a vendor whose credentials are turned down can close the socket and ask for a new sign-in
|
|
625
|
+
rather than retry for ever.
|
|
626
|
+
|
|
627
|
+
The transport it returns is the one the platform's `http` and `mqtt` are:
|
|
628
|
+
`connectionKey`, `connect`, `scan`, `probe`, and a `configSchema` for what the driver's
|
|
629
|
+
`setup.json` asks. `scan` and `probe` take a last argument, `{ account }`: the account
|
|
630
|
+
the configuration names, as `connect` is handed it in `context.account`. Its `id` must be `<vendor>/<name>`, or the loader refuses the vendor naming
|
|
631
|
+
both. It is **code**, so the vendor sits at the tier a code driver does - reviewed before a
|
|
632
|
+
catalogue carries it; `verifyVendor` is where the hub asks. Its types come from
|
|
633
|
+
`@nebulahome/integration-sdk`, and `pnpm typecheck` holds it to them.
|
|
634
|
+
|
|
635
|
+
## A camera's picture
|
|
636
|
+
|
|
637
|
+
A camera's live picture is not state and goes through no transport: it is frames, for as long
|
|
638
|
+
as somebody watches, over a connection of its own. So a vendor with cameras ships a **stream
|
|
639
|
+
source** beside its transports - `"streams": { "camera": "./camera/stream.js" }` in the
|
|
640
|
+
manifest, registered as `<vendor>/<name>` - and a profile's camera entity names it and says what
|
|
641
|
+
to read:
|
|
642
|
+
|
|
643
|
+
```json
|
|
644
|
+
{
|
|
645
|
+
"domain": "camera",
|
|
646
|
+
"objectId": "chamber_camera",
|
|
647
|
+
"capabilities": { "camera": { "hasSnapshot": false, "hasStream": true } },
|
|
648
|
+
"state": {
|
|
649
|
+
"camera": {
|
|
650
|
+
"isStreamAvailable": {
|
|
651
|
+
"path": "ipcam.rtsp_url",
|
|
652
|
+
"map": { "disable": false },
|
|
653
|
+
"default": true
|
|
654
|
+
}
|
|
655
|
+
}
|
|
656
|
+
},
|
|
657
|
+
"stream": { "source": "bambulab/camera", "args": { "kind": "rtsp" } }
|
|
658
|
+
}
|
|
659
|
+
```
|
|
660
|
+
|
|
661
|
+
The module's default export takes the SDK and returns `sdk.defineStreamSource({ id,
|
|
662
|
+
configSchema, open })`. `open(config, args, sink, signal)` is handed the instance's transport
|
|
663
|
+
settings, secrets opened, and the profile's `args`; it says once what the stream carries -
|
|
664
|
+
`sink.describe({ kind: "jpeg" })` or `{ kind: "h264", codec: "avc1.640028" }` - then hands
|
|
665
|
+
over each frame with `sink.frame({ data, isKey, timestampUs })`: a JPEG, or an H.264 access unit
|
|
666
|
+
in Annex B with its parameter sets before a key frame. `sdk.openRtsp` does the RTSP for a camera
|
|
667
|
+
that speaks it. Nothing is decoded or transcoded on the hub: the frames go to the browser, which
|
|
668
|
+
decodes them (WebCodecs for H.264), and a stream runs only while a viewer keeps asking for it.
|
|
669
|
+
|
|
670
|
+
## A picture that changes
|
|
671
|
+
|
|
672
|
+
A robot's map, a printer's plate: a picture the device's state carries, drawn again
|
|
673
|
+
when it changes. A profile's `image` entity says where in the payload it is and what it is:
|
|
674
|
+
|
|
675
|
+
```json
|
|
676
|
+
{
|
|
677
|
+
"domain": "image",
|
|
678
|
+
"objectId": "map",
|
|
679
|
+
"capabilities": { "image": {} },
|
|
680
|
+
"state": {},
|
|
681
|
+
"image": {
|
|
682
|
+
"path": "mapSvg",
|
|
683
|
+
"contentType": "image/svg+xml",
|
|
684
|
+
"encoding": "utf8",
|
|
685
|
+
"minIntervalMs": 5000
|
|
686
|
+
}
|
|
687
|
+
}
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
`contentType` is `image/svg+xml`, `image/png` or `image/jpeg`; `encoding` is `utf8` for an SVG's
|
|
691
|
+
text or `base64` for bytes. The hub keeps the picture in memory - at most 700 KB - and publishes
|
|
692
|
+
only which one it is, `{ contentType, revision }`, the revision a digest of the bytes, at most
|
|
693
|
+
every `minIntervalMs` (2 s when not said) however often the payload changes. The interface reads
|
|
694
|
+
the bytes from `GET /api/v1/entities/:id/image`, and draws them again when the revision moves. A
|
|
695
|
+
picture's changes are not written to the state history.
|
|
696
|
+
|
|
697
|
+
An SVG is shown in an `<img>`: nothing in it runs, and nothing outside it is fetched - a raster
|
|
698
|
+
goes in as a `data:` URI. `sdk.images.png` makes one out of cells and a palette, and
|
|
699
|
+
`sdk.codecs.lzma` unpacks what a cloud packed; ECOVACS's `src/cloud/map.ts` does both.
|
|
700
|
+
|
|
701
|
+
**A command may be several messages.** On the `mqtt` transport, `"payloads": [ … ]` in place of
|
|
702
|
+
`"payload"` publishes each in order on the one topic - a device whose one switch is two nodes to
|
|
703
|
+
its firmware, like a Bambu H2's two chamber lights, is switched by one command.
|