@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/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.