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