@nebulahome/integration-sdk 1.8.0 → 1.10.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 +27 -0
- package/FILES.md +52 -10
- package/dist/chunks/node-dist.js +498 -165
- package/dist/chunks/node-index.d.ts +423 -50
- package/dist/chunks/node-project.js +1 -1
- package/dist/index.d.ts +280 -45
- package/dist/schemas.d.ts +165 -18
- package/dist/testing.d.ts +16 -1
- package/dist/testing.js +18 -0
- package/package.json +5 -5
- package/schemas/account.schema.json +167 -0
- package/schemas/profile.schema.json +10 -1
- package/schemas/setup.schema.json +334 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,33 @@
|
|
|
3
3
|
The SDK's version is the version of the integration contract the platform implements: a minor
|
|
4
4
|
version adds to the contract, a major one breaks it, and a patch leaves it as it is.
|
|
5
5
|
|
|
6
|
+
## 1.10.0
|
|
7
|
+
|
|
8
|
+
A device's past readings, imported when it is added.
|
|
9
|
+
|
|
10
|
+
- A code driver's `history` says how far back a device can tell its numeric readings (at most 28
|
|
11
|
+
days), the request asking for them, and how its answer reads as readings per entity. The hub
|
|
12
|
+
asks once, right after the device is first added, and writes the readings into the entities'
|
|
13
|
+
history and the charts' summaries, leaving their state alone.
|
|
14
|
+
- `driverHarness(...).importHistory(range, answer)` tests it.
|
|
15
|
+
|
|
16
|
+
Also in the contract since 1.9.0:
|
|
17
|
+
|
|
18
|
+
- The capabilities `effect`, `fan` and `location`, and the domains `fan`, `device_tracker` and
|
|
19
|
+
`geo_location`.
|
|
20
|
+
- `entity` and `icon` fields in `setup.json`: pick one of the house's entities, or an icon.
|
|
21
|
+
|
|
22
|
+
## 1.9.0
|
|
23
|
+
|
|
24
|
+
A device whose entities depend on how it is set up.
|
|
25
|
+
|
|
26
|
+
- A code driver's `deviceInfo` may say `descriptor`: what the device is now - the claim's own
|
|
27
|
+
descriptor while it still is that, a new one once it was set up differently (a Bot switched from
|
|
28
|
+
press to switch mode in its vendor's app). When the device still says the new one thirty seconds
|
|
29
|
+
later, the hub describes it again from it: an entity described both times stays with its
|
|
30
|
+
history, one no longer described is removed with its history, one described only now is added.
|
|
31
|
+
The device's Activity says so, and the readings of a linked device are linked again.
|
|
32
|
+
|
|
6
33
|
## 1.8.0
|
|
7
34
|
|
|
8
35
|
One device reached more than one way.
|
package/FILES.md
CHANGED
|
@@ -359,16 +359,9 @@ A command's request carries values out of the command as **references** -
|
|
|
359
359
|
`{ "$": "command.level" }`. A device that counts in other units says so: `scale`
|
|
360
360
|
multiplies a number, `decimals` rounds it, `min` and `max` clamp it, in that order, and
|
|
361
361
|
`"optional": true` leaves the key out of the request when the command does not carry the value,
|
|
362
|
-
instead of sending `null`. That is how a
|
|
363
|
-
`"
|
|
364
|
-
|
|
365
|
-
literal.
|
|
366
|
-
|
|
367
|
-
A light that can **fade** says so on each capability that can: `"on_off": { "hasTransition":
|
|
368
|
-
true }`, and the same on `level`, `color_hs` and `color_temp`. The
|
|
369
|
-
platform drops `transitionMs` from a command to a capability that does not say so, and the editor
|
|
370
|
-
offers no Transition field for it, so a lamp that changes at once is never promised a fade. A
|
|
371
|
-
device added before its driver said so keeps what it was added with until it is added again.
|
|
362
|
+
instead of sending `null`. That is how a level reaches a lamp that counts brightness from 0 to 255:
|
|
363
|
+
`"brightness": { "$": "command.level", "scale": 2.55, "decimals": 0, "max": 255 }`. A reference
|
|
364
|
+
is still a path and nothing more; anything it does not name is a literal.
|
|
372
365
|
|
|
373
366
|
### Firmware updates
|
|
374
367
|
|
|
@@ -394,6 +387,20 @@ A profile may also say where its reports carry the firmware the device runs now
|
|
|
394
387
|
device's row as it hears it, so the device page follows an update without the device being added
|
|
395
388
|
again.
|
|
396
389
|
|
|
390
|
+
A device whose entities depend on how it is set up - a Bot that is a switch in switch mode and a
|
|
391
|
+
button in press mode, a relay that is two switches or one cover - says so through a code driver's
|
|
392
|
+
`deviceInfo(message, context)`: `descriptor` is what the device is now. Return the claim's own
|
|
393
|
+
descriptor (`context.claim.descriptor`) while the message shows it is still set up that way, a new
|
|
394
|
+
descriptor once it shows otherwise, and leave `descriptor` out when the message does not say. A
|
|
395
|
+
new one is taken when the device still says it thirty seconds later; one message saying the
|
|
396
|
+
claim's own again drops it, so a misread advertisement changes nothing. The hub then describes
|
|
397
|
+
the device again from the new descriptor and keeps it as the claim: entities described both times
|
|
398
|
+
stay, with their history and the owner's names; one no longer described is removed, with its
|
|
399
|
+
history, and an automation using it says so; one described only now is added. The device's
|
|
400
|
+
Activity says what was removed and added, and on a linked device the readings of the same `key`
|
|
401
|
+
are linked again. Keep an entity's `objectId` the same in every setup where it is the same thing
|
|
402
|
+
(a battery), so it is never removed for nothing.
|
|
403
|
+
|
|
397
404
|
The logo rides inside the catalogue the hub serves, as a data URL, so it must be an `.svg` or a
|
|
398
405
|
`.png` and at most 64 KiB; anything else fails the vendor at startup. Draw a monogram in the
|
|
399
406
|
vendor's colour - nobody's trademark -; the interface draws the same monogram itself for a vendor
|
|
@@ -1098,3 +1105,38 @@ goes in as a `data:` URI. `sdk.images.png` makes one out of cells and a palette,
|
|
|
1098
1105
|
**A command may be several messages.** On the `mqtt` transport, `"payloads": [ … ]` in place of
|
|
1099
1106
|
`"payload"` publishes each in order on the one topic - a device whose one switch is two nodes to
|
|
1100
1107
|
its firmware, like a Bambu H2's two chamber lights, is switched by one command.
|
|
1108
|
+
|
|
1109
|
+
## A device's past
|
|
1110
|
+
|
|
1111
|
+
A device that can tell its past numeric readings - prices already published, a meter's stored
|
|
1112
|
+
records - hands them over when it is added, so its charts do not start empty. A code driver says
|
|
1113
|
+
how, with `history`:
|
|
1114
|
+
|
|
1115
|
+
```ts
|
|
1116
|
+
history: {
|
|
1117
|
+
days: 28,
|
|
1118
|
+
request: (range, context) => ({
|
|
1119
|
+
deviceKey: context.claim.deviceKey,
|
|
1120
|
+
op: 'history',
|
|
1121
|
+
args: { from: range.from, to: range.to },
|
|
1122
|
+
}),
|
|
1123
|
+
toReadings: (answer, context) => [
|
|
1124
|
+
{ entityId: context.entities.get('price_hourly')!, readings: [{ at: '2026-11-02T13:00:00.000Z', value: 0.21 }] },
|
|
1125
|
+
],
|
|
1126
|
+
},
|
|
1127
|
+
```
|
|
1128
|
+
|
|
1129
|
+
Right after the device is added for the first time, the hub sends `request` once through the
|
|
1130
|
+
transport, as it sends a command - so the transport's `send` answers the op - with `range.to` the
|
|
1131
|
+
moment the device was added and `range.from` `days` before it. What `toReadings` reads from the
|
|
1132
|
+
answer goes into the entities' history, never into their state: the current value, the state
|
|
1133
|
+
history and the automations see nothing of it. The charts show it a minute later, once the hub's
|
|
1134
|
+
summaries are brought up to date.
|
|
1135
|
+
|
|
1136
|
+
- At most 28 days: the hub keeps raw readings 30 days, and summarises only what it still keeps.
|
|
1137
|
+
- Only numeric sensors (`sensor_numeric`) keep past readings; readings for another entity, at or
|
|
1138
|
+
after the moment the device was added, or older than `days`, are left out.
|
|
1139
|
+
- It is asked once. A device that was not reachable then, or a hub that stopped meanwhile, does
|
|
1140
|
+
not ask again, and a device set up differently later does not either.
|
|
1141
|
+
|
|
1142
|
+
`driverHarness(...).importHistory(range, answer)` gives the request and the readings, to test both.
|