Skip to content

Add meter transformer interfaces #142

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 6 commits into
base: master
Choose a base branch
from
Open

Add meter transformer interfaces #142

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
705812b
Add meter transformer interfaces
BudzikM Jul 28, 2025
134aaac
Fix formating
BudzikM Jul 28, 2025
55dd1b7
Remove copy paste remainings
BudzikM Jul 28, 2025
dac6073
improve descriptions
BudzikM Jul 28, 2025
d5251ef
Update device_services/generic/meter.md
BudzikM Jul 28, 2025
da02a29
Add missing split strategy
BudzikM Jul 28, 2025
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
51 changes: 40 additions & 11 deletions device_services/generic/meter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,21 @@ An electricity meter service can represent a stand-alone AMS meter, like a HAN s

## Interfaces

| Type | Interface | Value type | Properties | Storage | Aggregation | Description |
|------|-----------------------------|------------|------------------------------------------|-------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| in | cmd.meter.get_report | string | | | | Value is an import/consumption `unit` defined in [`sup_units`](#service-properties) property. May not be supported by all meters. Empty or null value requests all supported units. |
| out | evt.meter.report | float | `unit`, `prv_data`, `delta_t`, `virtual` | `aggregate` | `unit` | Returns an import/consumption meter report for `unit` specified in properties. |
| in | cmd.meter.reset | null | | | | Resets all historical readings. |
| - | | | | | | |
| in | cmd.meter_export.get_report | string | | | | Value is a export/production `unit` defined in [`sup_export_units`](#service-properties) property. |
| out | evt.meter_export.report | float | `unit`, `prv_data`, `delta_t` | `aggregate` | `unit` | Returns a export/production meter report for `unit` specified in properties. |
| - | | | | | | |
| in | cmd.meter_ext.get_report | str_array | | | | Requests an extended electricity report for listed extended values. Empty or null value requests all supported extended values. |
| out | evt.meter_ext.report | float_map | | `split` | | Returns an extended electricity report. See [electricity measurements](#electricity-measurements) section for more information. |
| Type | Interface | Value type | Properties | Storage | Aggregation | Description |
|------|----------------------------------|------------|------------------------------------------|-------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| in | cmd.meter.get_report | string | | | | Value is an import/consumption `unit` defined in [`sup_units`](#service-properties) property. May not be supported by all meters. Empty or null value requests all supported units. |
| out | evt.meter.report | float | `unit`, `prv_data`, `delta_t`, `virtual` | `aggregate` | `unit` | Returns an import/consumption meter report for `unit` specified in properties. |
| in | cmd.meter.reset | null | | | | Resets all historical readings. |
| - | | | | | | |
| in | cmd.meter_export.get_report | string | | | | Value is a export/production `unit` defined in [`sup_export_units`](#service-properties) property. |
| out | evt.meter_export.report | float | `unit`, `prv_data`, `delta_t` | `aggregate` | `unit` | Returns a export/production meter report for `unit` specified in properties. |
| - | | | | | | |
| in | cmd.meter_ext.get_report | str_array | | | | Requests an extended electricity report for listed extended values. Empty or null value requests all supported extended values. |
| out | evt.meter_ext.report | float_map | | `split` | | Returns an extended electricity report. See [electricity measurements](#electricity-measurements) section for more information. |
| - | | | | | |
| in | cmd.meter_transformer.get_report | null | | | | Requests a list of transformation ratios for each measurement affected by the transformer. |
| out | evt.meter_transformer.report | float_map | | `split` | | Returns a map of transformation ratios for each measurement affected by the transformer. |
Copy link
Contributor

@boguslaw-wojcik boguslaw-wojcik Aug 3, 2025

Choose a reason for hiding this comment

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

no point to have storage strategy split here, we can assume that report will always contain ALL units which are transformed.

| in | cmd.meter_transformer.set | float_map | | `split` | | Sets the transformer ratio for the selected unit. Each measurement received from the device is multiplied by the corresponding ratio before being reported. |

> For backward compatibility the service reports imported/consumed values using `evt.meter.report` interface and exported/produced values using `evt.meter_export.report`.

Expand Down Expand Up @@ -132,6 +136,31 @@ An electricity meter service can represent a stand-alone AMS meter, like a HAN s
}
```

* Example of a transformer ratio set:

```json
{
"serv": "meter_elec",
"type": "cmd.meter_transformer.set",
"val_t": "float_map",
"val": {
"A": 40,
"kWh": 1,
"W": 40,
"V": 1
},
Copy link
Contributor

@boguslaw-wojcik boguslaw-wojcik Aug 3, 2025

Choose a reason for hiding this comment

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

command doesn;t have split strategy, commands are not sotred

"storage": {
"strategy": "split"
},
"props": null,
"tags": null,
"src": "-",
"ver": "1",
"uid": "e604e951-7afb-4f96-981b-62e905757686",
"topic": "pt:j1/mt:cmd/rt:dev/rn:zigbee/ad:1/sv:meter_elec/ad:1_2"
}
```

## Electricity measurements

Electricity measurements can be reported using different interfaces.
Expand Down