diff --git a/spec/host-api.md b/spec/host-api.md index a30b7a9..fab21df 100644 --- a/spec/host-api.md +++ b/spec/host-api.md @@ -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