@nebulahome/integration-sdk 1.9.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 +16 -0
- package/FILES.md +38 -10
- package/dist/chunks/node-dist.js +476 -163
- package/dist/chunks/node-index.d.ts +409 -48
- package/dist/chunks/node-project.js +1 -1
- package/dist/index.d.ts +266 -43
- package/dist/schemas.d.ts +164 -17
- 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,22 @@
|
|
|
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
|
+
|
|
6
22
|
## 1.9.0
|
|
7
23
|
|
|
8
24
|
A device whose entities depend on how it is set up.
|
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
|
|
|
@@ -1112,3 +1105,38 @@ goes in as a `data:` URI. `sdk.images.png` makes one out of cells and a palette,
|
|
|
1112
1105
|
**A command may be several messages.** On the `mqtt` transport, `"payloads": [ … ]` in place of
|
|
1113
1106
|
`"payload"` publishes each in order on the one topic - a device whose one switch is two nodes to
|
|
1114
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.
|