From ff15ae8d94ed0bef508d2a79f924b54fb711f031 Mon Sep 17 00:00:00 2001 From: Michal Budzon <98946120+BudzikM@users.noreply.github.com> Date: Sun, 19 Apr 2026 23:51:47 +0200 Subject: [PATCH] Energy Storage Service The numeric sensor service documentation has been replaced with energy storage service details. This includes service names, interfaces, and properties relevant to energy storage. --- device_services/generic/energy_storage.md | 71 +++++++++++++++++ device_services/generic/numeric_sensor.md | 95 ----------------------- 2 files changed, 71 insertions(+), 95 deletions(-) create mode 100644 device_services/generic/energy_storage.md delete mode 100644 device_services/generic/numeric_sensor.md diff --git a/device_services/generic/energy_storage.md b/device_services/generic/energy_storage.md new file mode 100644 index 0000000..e207012 --- /dev/null +++ b/device_services/generic/energy_storage.md @@ -0,0 +1,71 @@ +# Energy Storage Service + +An energy-storage service represents the battery bank of a hybrid inverter or a standalone home battery. State of charge is exposed through the dedicated `cmd.soc` / `evt.soc` pair; all other electrical measurements travel through the `meter_elec` extended-report interface so clients that already consume meter data need no extra schema. + +Field keys follow the [`meter_elec`](./meter.md#electricity-measurements) convention viewed from the storage unit's perspective: `i_import` / `p_import` while charging, `i_export` / `p_export` while discharging. + +## Service name + +| Service name | Description | +|------------------|--------------------------------------------------| +| `energy_storage` | Battery bank. | + +## Interfaces + +| Type | Interface | Value type | Description | +|------|------------------------------|--------------|-----------------------------------------------------------------------------------| +| in | `cmd.soc.get_report` | `null` | Request the state-of-charge report. | +| out | `evt.soc.report` | `int` | State of charge in percent (0..100). | +| in | `cmd.meter_ext.get_report` | `str_array` | Request selected extended values. Empty or null value requests all supported. | +| out | `evt.meter_ext.report` | `str_array` | Current measurements. | +| out | `evt.storage.report` | `float_map` | Electrical snapshot. Fields: `u`, `i_import`, `i_export`, `p_import`, `p_export`. | +| out | `evt.error.report` | `string` | Reports processing errors. | +| in | `cmd.storage.set_type` | `string` | Set battery chemistry. Allowed: LiFePo4, AGM. Affetcs SoC calculation. +| in | `cmd.storage.get_type` | `null` | Request current battery type. +| out | `evt.storage.type_report` | `string` | Current battery type. + +## Service properties + +| Name | Type | Value example | Description | +|-------------------------|-------------|---------------------------------------------------------|------------------------------------------------------------------------| +| `sup_extended_vals` | `str_array` | `["u","i_import","i_export","p_import","p_export"]` | List of supported `evt.storage.report` keys. | +| `nominal_voltage` | `float` | `48` | Rated battery-bank voltage, V. Omitted if not known. | +| `max_charge_current` | `float` | `60` | Maximum allowed charging current, A. Omitted if not known. | +| `max_discharge_current` | `float` | `60` | Maximum allowed discharging current, A. Omitted if not known. | +| `capacity_kwh` | `float` | `10.24` | Usable bank capacity, kWh. Omitted if not known. | + +Adapters MUST NOT set a rating property to 0 — omit it instead, so that clients can distinguish "unknown" from "zero". + + + +## Example — `evt.storage.report` + +```json +{ + "serv": "energy_storage", + "type": "evt.storage.report", + "val_t": "float_map", + "val": { + "u": 26.5, + "i_import": 0, + "i_export": 10, + "p_import": 0, + "p_export": 265 + }, + "src": "ess", + "ver": "1" +} +``` + +## Example — `evt.soc.report` + +```json +{ + "serv": "energy_storage", + "type": "evt.soc.report", + "val_t": "int", + "val": 100, + "src": "ess", + "ver": "1" +} +``` diff --git a/device_services/generic/numeric_sensor.md b/device_services/generic/numeric_sensor.md deleted file mode 100644 index bbb78fa..0000000 --- a/device_services/generic/numeric_sensor.md +++ /dev/null @@ -1,95 +0,0 @@ -# Numeric Sensor Services - -Numeric sensor services represent a device or device functionality capable of numeric measurements. -The most popular sensors measure temperature, air humidity, or light intensity. - -## Service names - -| Service name | Units | Description | -|----------------------|--------------------------|---------------------------------| -| `sensor_accelx` | m/s2 | Acceleration, X-axis | -| `sensor_accely` | m/s2 | Acceleration, Y-axis | -| `sensor_accelz` | m/s2 | Acceleration, Z-axis | -| `sensor_airflow` | m3/h, ft3/m | Air flow sensor | -| `sensor_airq` | pm25, pm10, aqi | Air quality sensor | -| `sensor_anglepos` | %, degN, degS | Angle Position sensor | -| `sensor_atmo` | kPa, ha, mbar | Atmospheric pressure sensor. | -| `sensor_baro` | kPa, ha, mbar | Barometric pressure sensor. | -| `sensor_co2` | ppm | CO2-level sensor | -| `sensor_co` | mol/m3 | Carbon Monoxide level sensor | -| `sensor_current` | A, mA | Current sensor | -| `sensor_dew` | C, F | Dew point sensor | -| `sensor_direct` | deg | Direction sensor | -| `sensor_distance` | m, cm, ft | Distance sensor | -| `sensor_elresist` | ohm/m | Electrical resistivity sensor | -| `sensor_freq` | Hz, kHz | Frequency sensor | -| `sensor_gp` | %, NOM | General purpose sensor | -| `sensor_gust` | kph | Gust sensor | -| `sensor_humid` | %, g/m3 | Relative humidity sensor | -| `sensor_lumin` | Lux, % | Luminance sensor | -| `sensor_moist` | %, kOhm, m3/m3, aw | Moisture sensor | -| `sensor_noise` | dB | Noise sensor | -| `sensor_power` | W, Btu/h | Power sensor. **Deprecated.** | -| `sensor_rain` | mm/h, in/h | Rain rate sensor | -| `sensor_rotation` | rpm, Hz | Rotation sensor | -| `sensor_seismicint` | EMCRO, LEIDO, MERC, SHDO | Seismic intensity sensor | -| `sensor_seismicmag` | MB, ML, MW, MS | Seismic magnitude sensor | -| `sensor_solarrad` | w/m2 | Solar radiation | -| `sensor_tank` | l, gal, m3 | Tank capacity sensor | -| `sensor_temp` | C, F | Temperature sensor | -| `sensor_tidelvl` | m, ft | Tide level sensor | -| `sensor_uv` | index | Ultraviolet sensor | -| `sensor_veloc` | m/s, mph | Velocity sensor | -| `sensor_voltage` | V, mV | Voltage sensor. **Deprecated.** | -| `sensor_watflow` | l/h | Water flow sensor | -| `sensor_watpressure` | kPa | Water pressure sensor | -| `sensor_wattemp` | C, F | Water temperature sensor | -| `sensor_weight` | kg, lbs | Weight sensor | -| `sensor_wind` | kph | Wind sensor | - -> Please note that `sensor_power` and `sensor_voltage` services are deprecated. -> A [`meter_elec`](/device_services/generic/meter.md) service should be used instead for reporting electricity measurements. - -## Interfaces - -| Type | Interface | Value type | Properties | Storage | Aggregation | Description | -|------|-----------------------|------------|------------|-------------|-------------|---------------------------------------------------------------------------| -| in | cmd.sensor.get_report | string | | | | Value is the desired unit. Use empty value to get report in default unit. | -| out | evt.sensor.report | float | `unit` | `aggregate` | `unit` | | - -## Interface properties - -| Name | Example | Required | Description | -|--------|---------|----------|---------------------------------------------------| -| `unit` | `"C"` | Yes | One of the units defined in `sup_units` property. | - -## Service properties - -| Name | Type | Example | Description | -|-------------|-----------|---------|---------------------------------------------------------------------------------------------| -| `sup_units` | str_array | ["C"] | List of supported units. See list of [well-defined units](#service-names) for each service. | - -## Examples - -* Example of a temperature sensor report: - -```json -{ - "serv": "sensor_temp", - "type": "evt.sensor.report", - "val_t": "float", - "val": 22, - "storage": { - "strategy": "aggregate", - "sub_value": "C" - }, - "props": { - "unit": "C" - }, - "tags": null, - "src": "-", - "ver": "1", - "uid": "5c0df678-144b-4184-b024-f0cd6f6aa382", - "topic": "pt:j1/mt:evt/rt:dev/rn:zw/ad:1/sv:sensor_temp/ad:18_2" -} -```