@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 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 fade reaches a Shelly dimmer, which takes seconds:
363
- `"transition_duration": { "$": "command.transitionMs", "scale": 0.001, "decimals": 1,
364
- "optional": true }`. A reference is still a path and nothing more; anything it does not name is a
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.