Energy Storage Service#145
Conversation
The numeric sensor service documentation has been replaced with energy storage service details. This includes service names, interfaces, and properties relevant to energy storage.
![indivisus[bot]](https://avatars.githubusercontent.com/in/2748893?s=60&v=4){kind=small}
| | 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. | |
There was a problem hiding this comment.
[P2 - Medium] Bug: Wrong value type for evt.meter_ext.report - should be float_map not str_array
The evt.meter_ext.report interface is defined with value type str_array, but this is inconsistent with the established convention. In meter.md (line 30), evt.meter_ext.report uses float_map as the value type. The description 'Current measurements' also indicates numeric values which aligns with float_map, not str_array. This inconsistency could cause client implementations to fail when parsing the response.
Evidence:
| out | `evt.meter_ext.report` | `str_array` | Current measurements. |
Suggested fix:
Change the value type from str_array to float_map to match the meter.md convention:
| out | `evt.meter_ext.report` | `float_map` | Current measurements. || | 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. |
There was a problem hiding this comment.
[P3 - Low] Style: Typo: 'Affetcs' should be 'Affects'
There is a spelling error in the description for cmd.storage.set_type interface. The word 'Affetcs' should be corrected to 'Affects'.
Evidence:
| in | `cmd.storage.set_type` | `string` | Set battery chemistry. Allowed: LiFePo4, AGM. Affetcs SoC calculation.
| | 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. |
There was a problem hiding this comment.
[P3 - Low] Style: Missing trailing pipe character in markdown table rows
Lines 23, 24, and 25 in the Interfaces table are missing the trailing pipe character '|' at the end of each row. All other rows in the table properly end with '|'. This inconsistency may cause rendering issues in some markdown parsers.
Evidence:
| 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.
| # 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" | ||
| } | ||
| ``` |
There was a problem hiding this comment.
[P3 - Low] Other: New service not added to navigation sidebar or services index
The new energy_storage.md service documentation is being added but the PR does not include updates to device_services/_sidebar.md or device_services/device_services.md to add navigation links to this new service. Users will not be able to discover or navigate to this documentation through the standard navigation structure.
Evidence:
+++ b/device_services/generic/energy_storage.md
@@ -0,0 +1,71 @@
+# Energy Storage Service
|
|
||
| | 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. | |
There was a problem hiding this comment.
[P4 - Info] Other: Property description may be ambiguous about which interface it describes
The sup_extended_vals property description states 'List of supported evt.storage.report keys', but in meter.md the same property name is associated with evt.meter_ext.report. Since this service has both interfaces, the description should clarify the relationship between sup_extended_vals and both evt.storage.report and evt.meter_ext.report.
Evidence:
| `sup_extended_vals` | `str_array` | `["u","i_import","i_export","p_import","p_export"]` | List of supported `evt.storage.report` keys. |
| | 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. |
There was a problem hiding this comment.
[P4 - Info] Style: Inconsistent whitespace: tabs used instead of spaces in table rows
Lines 23, 24, and 25 use tab characters after '| in' and '| out' for alignment, while all other rows in the Interfaces table use spaces. Additionally, line 25 has extra whitespace in the Type column. This inconsistent formatting may cause alignment issues when viewing the markdown.
Evidence:
| in | `cmd.storage.set_type` | `string` |
| in | `cmd.storage.get_type` | `null` |
| out | `evt.storage.type_report` | `string` |
1 participant
The numeric sensor service documentation has been replaced with energy storage service details. This includes service names, interfaces, and properties relevant to energy storage.