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