Skip to content

docs(spec): separate host emit keys from the wire model #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
frahlg merged 1 commit into from
Oct 4, 2026
Merged

docs(spec): separate host emit keys from the wire model #153

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 45 additions & 25 deletions spec/host-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,31 +58,51 @@ Use it for evidence an operator needs when a device misbehaves, not for
telemetry that belongs in `host.emit()`.

### `host.emit(der_type, data)`
Emit telemetry for a DER type: `"pv"`, `"battery"`, `"inverter"`, `"meter"` or
`"v2x_charger"`.

Key names are a contract, not a convention. Blixt reads each table by exact key
and silently drops a key whose case is wrong, so a mistyped key loses data
without an error. These names match `@srcful/data-models` verbatim:

**Meter:** `W`, `Hz`, `L1_V`/`L1_A`/`L1_W` (… `L2_`, `L3_`), `total_import_Wh`, `total_export_Wh`

**Inverter:** `W`, `VA`, `Hz`, `L1_V`/`L1_A`/`L1_W` (… `L2_`, `L3_`), `rated_W`

**PV:** `W`, `total_generation_Wh`, `mppts`

**Battery:** `W`, `V`, `A`, `SoC_nom_fract` (0-1 fraction), `temperature_C`, `total_charge_Wh`, `total_discharge_Wh`, `available_charge_Wh`, `available_discharge_Wh`

A repeating structure is a plural-named array, never numbered keys. `pv.mppts`
is a list of `{V, A, W}` as long as the device physically has. The catalog's
`mppt1_v`/`mppt2_v` cannot describe a four-MPPT inverter at all.

Emit keys follow the same two dialects: FTW's drivers use `w`, `soc`,
`import_wh`, Blixt's use `W`, `SoC_nom_fract`, `total_import_Wh`. FTW accepts
both since v1.11.4-beta.7. Use whichever your target speaks and do not convert
a working driver to change the spelling of what it already reports correctly.

**V2X Charger:** `w`, `a`, `v`, `hz`, `l1_a`..`l3_a`, `l1_v`..`l3_v`, `l1_w`..`l3_w`, `dc_w`, `dc_a`, `dc_v`, `vehicle_soc_fract`, `ev_max_energy_req_wh`, `ev_min_energy_req_wh`, `session_charge_wh`, `session_discharge_wh`, `total_charge_wh`, `total_discharge_wh`, `capacity_wh`, `rated_power_w`
Emit telemetry for one DER. `der_type` is the host's DER kind: `"pv"`,
`"battery"`, `"inverter"`, `"meter"` or `"v2x_charger"`.

Use the field names your target host accepts. The host maps its Lua keys to
its telemetry model; a catalog or signed artifact does not change that map.
Key names and case are exact: a host can silently drop an unknown key.

[Sourceful data models](https://github.com/srcfl/srcful-data-models) owns
Sourceful's wire field names, units and sign rules. Its published
[`docs/REFERENCE.md`](https://github.com/srcfl/srcful-data-models/blob/main/docs/REFERENCE.md)
is the source for those fields. DER and device types come from the
device-support API (`GET /der-types`, `GET /device-types`). The host kinds
map to those DER types as follows:

| `der_type` | device-support DER type |
|---|---|
| `pv` | `solar` |
| `battery` | `battery` |
| `meter` | `meter` |
| `v2x_charger` | `ev_charger_port` |
| `inverter` | Proposed in data-models v3.0.0; 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
keeps those keys until its host changes. FTW drivers use keys such as `w`,
`soc` and `import_wh`; FTW also accepts the Blixt spelling since
v1.11.4-beta.7. Use the spelling your target speaks and keep a working
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

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

Those proposed 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.

## Modbus

Expand Down
Loading