From 64c01561bc6f98b4c5b20d9b8b9e10a901628a7a Mon Sep 17 00:00:00 2001 From: David Mozart Date: Tue, 6 Oct 2026 10:40:21 +0200 Subject: [PATCH 1/3] docs(spec): note data-models v3.0.0 is merged srcful-data-models#10 merged v3.0.0 on main, so the host.emit migration note no longer describes it as open or says main is v2.0.0. NovaCore's change (srcful-novacore#174) is still open, and host emit keys stay separate from the wire model as before. Co-Authored-By: Claude Opus 5.5 Signed-off-by: David Mozart --- spec/host-api.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/spec/host-api.md b/spec/host-api.md index fab21df..a706242 100644 --- a/spec/host-api.md +++ b/spec/host-api.md @@ -78,7 +78,7 @@ map to those DER types as follows: | `battery` | `battery` | | `meter` | `meter` | | `v2x_charger` | `ev_charger_port` | -| `inverter` | Proposed in data-models v3.0.0; see the migration below | +| `inverter` | Added in data-models v3.0.0; NovaCore registration pending, see the migration below | Blixt L1 reads host keys such as `W`, `V`, `A`, `total_import_Wh` and `rated_W`, and PV inputs as `pv.mppts`, a list of `{V, A, W}`. A Blixt driver @@ -90,16 +90,18 @@ driver's keys when they already report the right values. Leave out a value that was not read (`nil`). Never send a made-up zero. Follow the target host's wire rules for absent values. -#### Proposed data-models v3.0.0 migration +#### Data-models v3.0.0 migration -[srcful-data-models#10](https://github.com/srcfl/srcful-data-models/pull/10) -proposes the `inverter` DER type, lowercase non-unit names, and `_ac` / `_dc` -postfixes for quantities that can describe either side. NovaCore's matching -change is [srcful-novacore#174](https://github.com/srcfl/srcful-novacore/pull/174). -These changes are still open. The reference on `main` currently describes -v2.0.0. +srcful-data-models v3.0.0 is merged +([srcful-data-models#10](https://github.com/srcfl/srcful-data-models/pull/10)), +and the [reference on `main`](https://github.com/srcfl/srcful-data-models/blob/main/docs/REFERENCE.md) +describes it. It adds the `inverter` DER type, lowercase non-unit names, and an +`_ac` / `_dc` postfix on every W, V, A and Wh field; only `Hz`, `VA` and `var` +have none. NovaCore's matching change, +[srcful-novacore#174](https://github.com/srcfl/srcful-novacore/pull/174), is +still open. -Those proposed wire names do not change `host.emit` yet. Before a driver +Those wire names do not change `host.emit` yet. Before a driver uses them, its host must accept or map them, and any receiving API must support them. Keep the current host keys until that work lands; a link to a newer data model does not add host support. From 37584a46ec4dcb258098acbf25fc658416cc22c1 Mon Sep 17 00:00:00 2001 From: David Mozart Date: Tue, 6 Oct 2026 14:41:52 +0200 Subject: [PATCH 2/3] docs(spec): describe srcful-data-models v2 in the migration note The data model is published as v2 (package 2.0.0) on main, not v3. Update the migration note: json.v2 subjects next to the legacy json.v1 with no translation between them, the DER type as the default topic segment (solar, was pv) with NovaCore's temporary pv fallback, the inverter DER as the AC output stage only, an _ac/_dc postfix on every W/V/A/VA/Wh field with only Hz bare, and null for unread values. The split between host emit keys and the wire model is unchanged. Co-Authored-By: Claude Opus 5.5 Signed-off-by: David Mozart --- spec/host-api.md | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/spec/host-api.md b/spec/host-api.md index a706242..0764831 100644 --- a/spec/host-api.md +++ b/spec/host-api.md @@ -78,7 +78,7 @@ map to those DER types as follows: | `battery` | `battery` | | `meter` | `meter` | | `v2x_charger` | `ev_charger_port` | -| `inverter` | Added in data-models v3.0.0; NovaCore registration pending, see the migration below | +| `inverter` | Added in data-models v2; NovaCore registers it in srcful-novacore#174 (open), see the migration below | Blixt L1 reads host keys such as `W`, `V`, `A`, `total_import_Wh` and `rated_W`, and PV inputs as `pv.mppts`, a list of `{V, A, W}`. A Blixt driver @@ -90,16 +90,27 @@ driver's keys when they already report the right values. Leave out a value that was not read (`nil`). Never send a made-up zero. Follow the target host's wire rules for absent values. -#### Data-models v3.0.0 migration - -srcful-data-models v3.0.0 is merged -([srcful-data-models#10](https://github.com/srcfl/srcful-data-models/pull/10)), -and the [reference on `main`](https://github.com/srcfl/srcful-data-models/blob/main/docs/REFERENCE.md) -describes it. It adds the `inverter` DER type, lowercase non-unit names, and an -`_ac` / `_dc` postfix on every W, V, A and Wh field; only `Hz`, `VA` and `var` -have none. NovaCore's matching change, -[srcful-novacore#174](https://github.com/srcfl/srcful-novacore/pull/174), is -still open. +#### Data-models v2 migration + +srcful-data-models v2 (package 2.0.0) is on `main`. Its +[README](https://github.com/srcfl/srcful-data-models/blob/main/README.md) has +the wire rules and its +[reference](https://github.com/srcfl/srcful-data-models/blob/main/docs/REFERENCE.md) +every field. v2 payloads are published on +`…ders.{der_name}.telemetry.json.v2`; `json.v1` keeps the legacy format side +by side. Nothing translates between the two, so a consumer opts in to v2. In +v2 the `der_name` segment defaults to the DER type: `solar` (it was `pv`), +`battery`, `inverter`, `meter`. NovaCore temporarily resolves a v2 `solar` +segment to a DER provisioned as `pv`, until +[srcful-novacore#185](https://github.com/srcfl/srcful-novacore/issues/185) +removes that fallback. + +v2 adds the `inverter` DER type (the AC output stage only; its DC side is the +`solar` and `battery` DERs), lowercase non-unit names, and an `_ac` / `_dc` +postfix on every W, V, A, VA and Wh field; only `Hz` has none. Every field is +always present, and a value that was not read is `null`. NovaCore's matching +change, [srcful-novacore#174](https://github.com/srcfl/srcful-novacore/pull/174), +is still open. Those wire names do not change `host.emit` yet. Before a driver uses them, its host must accept or map them, and any receiving API must From 8bb28a58603f79782eb06735836266e9d8bbfdf5 Mon Sep 17 00:00:00 2001 From: David Mozart Date: Wed, 7 Oct 2026 07:49:30 +0200 Subject: [PATCH 3/3] docs(spec): host API follows srcful-data-models 2.3.0 set_make takes the brand, which v2 hosts write lowercase with `_`; the SoC window rule; NovaCore's v2 path (#174) is merged and on devnet. Co-Authored-By: Claude Opus 5.5 Signed-off-by: David Mozart --- spec/host-api.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/spec/host-api.md b/spec/host-api.md index 0764831..df67724 100644 --- a/spec/host-api.md +++ b/spec/host-api.md @@ -25,6 +25,9 @@ writes; the host owns scheduling, so a driver must not use it to pace polling. ### `host.set_make(brand_name)` Set the device brand name used in telemetry payloads. Call in `driver_init()`. +Pass the brand, not the model (`"Eastron"`, not `"SDM630"`). For data-models +v2 the host writes it lowercase with words joined by `_` (`"Konja Power"` → +`konja_power`). ### `host.set_model(model)` Set the device model. Call in `driver_init()` once the model is known from the @@ -78,7 +81,7 @@ map to those DER types as follows: | `battery` | `battery` | | `meter` | `meter` | | `v2x_charger` | `ev_charger_port` | -| `inverter` | Added in data-models v2; NovaCore registers it in srcful-novacore#174 (open), see the migration below | +| `inverter` | Added in data-models v2; see the migration below | Blixt L1 reads host keys such as `W`, `V`, `A`, `total_import_Wh` and `rated_W`, and PV inputs as `pv.mppts`, a list of `{V, A, W}`. A Blixt driver @@ -92,7 +95,7 @@ Follow the target host's wire rules for absent values. #### Data-models v2 migration -srcful-data-models v2 (package 2.0.0) is on `main`. Its +srcful-data-models v2 (package 2.3.0) is on `main`. Its [README](https://github.com/srcfl/srcful-data-models/blob/main/README.md) has the wire rules and its [reference](https://github.com/srcfl/srcful-data-models/blob/main/docs/REFERENCE.md) @@ -108,9 +111,11 @@ removes that fallback. v2 adds the `inverter` DER type (the AC output stage only; its DC side is the `solar` and `battery` DERs), lowercase non-unit names, and an `_ac` / `_dc` postfix on every W, V, A, VA and Wh field; only `Hz` has none. Every field is -always present, and a value that was not read is `null`. NovaCore's matching -change, [srcful-novacore#174](https://github.com/srcfl/srcful-novacore/pull/174), -is still open. +always present, and a value that was not read is `null`. A battery's SoC +window is the device's own min/max SoC, or 5–100 % when the device does not +report one. NovaCore's v2 path +([srcful-novacore#174](https://github.com/srcfl/srcful-novacore/pull/174)) is +merged and runs on devnet. Those wire names do not change `host.emit` yet. Before a driver uses them, its host must accept or map them, and any receiving API must