Skip to content

Energy Storage Service #145

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

Open
BudzikM wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Energy Storage Service #145

Show file tree
Hide file tree
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
71 changes: 71 additions & 0 deletions device_services/generic/energy_storage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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. |

@indivisus indivisus Bot Apr 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@indivisus indivisus Bot Apr 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.get_type` | `null` | Request current battery type.
| out | `evt.storage.type_report` | `string` | Current battery type.
Comment on lines +23 to +25

@indivisus indivisus Bot Apr 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +23 to +25

@indivisus indivisus Bot Apr 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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

@indivisus indivisus Bot Apr 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

| `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"
}
```
Comment on lines +1 to +71

@indivisus indivisus Bot Apr 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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

95 changes: 0 additions & 95 deletions device_services/generic/numeric_sensor.md
View file
Open in desktop

This file was deleted.