span-panel-api-schema-1 1.4.0b3__tar.gz → 1.4.0b4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/CHANGELOG.md +6 -2
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/PKG-INFO +2 -2
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/pyproject.toml +4 -2
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/adapter.py +155 -12
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/adoption.py +12 -4
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/charge_limit.py +42 -1
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/description.py +15 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/devices.py +25 -7
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/field_metadata.py +16 -14
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/panel.py +7 -6
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/reference/parent_child_tree.json +15 -17
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/snapshot.py +15 -12
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/transport.py +17 -3
- span_panel_api_schema_1-1.4.0b4/src/span_panel_api_schema_1/tree_export.py +924 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/.gitignore +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/README.md +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/breaker.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/charge-limit.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/connection.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/door.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/grid-forming.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/grid.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/info.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/load-shed.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/meter.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/pcs.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/power-flows.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/shed-forecast.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/shed.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/soc.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/status.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/catalogs/switch.json +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/spec/registries/device-types.md +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/__init__.py +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/catalog.py +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/circuits.py +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/const.py +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/extension.py +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/firmware.py +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/py.typed +0 -0
- {span_panel_api_schema_1-1.4.0b3 → span_panel_api_schema_1-1.4.0b4}/src/span_panel_api_schema_1/spec_lock.json +0 -0
|
@@ -16,17 +16,18 @@ Requires `span-panel-api` **3.8.0 or newer**, whose snapshot fields accept the u
|
|
|
16
16
|
### Added
|
|
17
17
|
|
|
18
18
|
- **spanos3/r202639/03 batch 2: reads more of the data this firmware publishes.**
|
|
19
|
+
- **`SchemaOneAdapter` exports the tree it holds, masked**, for `SpanMqttClient.masked_tree()`.
|
|
20
|
+
- **Each SPAN Drive's declared charge-current limit range is reported.**
|
|
19
21
|
|
|
20
22
|
### Changed
|
|
21
23
|
|
|
22
|
-
- The shipped reference tree is recaptured with every circuit inside the panel's breaker positions.
|
|
24
|
+
- The shipped reference tree is recaptured with `ebus-panel-sim` 0.9.0: every circuit inside the panel's breaker positions, firmware r202639's discharge-positive battery meter, and no user charge limit until one is set.
|
|
23
25
|
- **`proximity_proven` is `None`**, where it was a hard-coded `True`, because the tree publishes no proximity property.
|
|
24
26
|
- **`uptime_s` is `None`**, where it was always `0`, because no device publishes an uptime and this parser keeps no readiness clock to measure one.
|
|
25
27
|
|
|
26
28
|
### Removed
|
|
27
29
|
|
|
28
30
|
- **BREAKING FOR CONSUMERS: `snapshot.build_snapshot()` no longer takes the `ready_since` argument**, which no caller in this repository passed, so a call that passes it by keyword or position now raises `TypeError`.
|
|
29
|
-
|
|
30
31
|
- **BREAKING: snapshots no longer include synthesised `unmapped_tab_N` entries for unoccupied breaker positions, which carried no measured data**, and `panel.build_unmapped_tabs` and `const.UNMAPPED_TAB_PREFIX` are gone with them.
|
|
31
32
|
|
|
32
33
|
### Fixed
|
|
@@ -37,6 +38,9 @@ Requires `span-panel-api` **3.8.0 or newer**, whose snapshot fields accept the u
|
|
|
37
38
|
([#215](https://github.com/SpanPanel/span-panel-api/issues/215)).
|
|
38
39
|
- **Each MQTT message costs the same few microseconds however many devices the panel declares**, where routing it tested every recorded subscription in turn and every readiness check walked the device tree. On a 30-device tree the work per message falls
|
|
39
40
|
from 90–250 µs to about 2 µs, measured on a desktop machine ([#223](https://github.com/SpanPanel/span-panel-api/issues/223)).
|
|
41
|
+
- **A property the panel clears reads as unpublished**, where it read as an empty value until the panel published it again.
|
|
42
|
+
- **A charge-current limit outside the range a SPAN Drive declares is refused** instead of published.
|
|
43
|
+
- **A device typed as a subtype of a class (`energy.ebus.device.bess.<x>`) is read as that class**, where it was dropped from the snapshot, adoption and discovery ([#228](https://github.com/SpanPanel/span-panel-api/issues/228)).
|
|
40
44
|
|
|
41
45
|
## [1.2.2]
|
|
42
46
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: span-panel-api-schema-1
|
|
3
|
-
Version: 1.4.
|
|
3
|
+
Version: 1.4.0b4
|
|
4
4
|
Summary: Parent/child schema (data-model-version 1.x) parser for span-panel-api
|
|
5
5
|
Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
|
|
6
6
|
Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
|
|
@@ -8,7 +8,7 @@ Author: SpanPanel
|
|
|
8
8
|
License-Expression: MIT
|
|
9
9
|
Requires-Python: <4.0,>=3.14
|
|
10
10
|
Requires-Dist: ebus-sdk<0.24,>=0.19.0
|
|
11
|
-
Requires-Dist: span-panel-api<4.0,>=3.8.
|
|
11
|
+
Requires-Dist: span-panel-api<4.0,>=3.8.0b2
|
|
12
12
|
Description-Content-Type: text/markdown
|
|
13
13
|
|
|
14
14
|
# span-panel-api-schema-1
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "span-panel-api-schema-1"
|
|
3
|
-
version = "1.4.
|
|
3
|
+
version = "1.4.0b4"
|
|
4
4
|
description = "Parent/child schema (data-model-version 1.x) parser for span-panel-api"
|
|
5
5
|
authors = [
|
|
6
6
|
{name = "SpanPanel"}
|
|
@@ -33,7 +33,9 @@ dependencies = [
|
|
|
33
33
|
# unset read as a constant 0.
|
|
34
34
|
# Raised to 3.8.0b1: this parser fills snapshot fields new in it and imports
|
|
35
35
|
# `device_id_order` from its models.
|
|
36
|
-
|
|
36
|
+
# Raised to 3.8.0b2: this parser implements the masked-tree protocol and types
|
|
37
|
+
# new in it, and relies on its client reading a cleared value as unpublished.
|
|
38
|
+
"span-panel-api>=3.8.0b2,<4.0",
|
|
37
39
|
# Only this distribution depends on the eBus SDK. The bootstrap and
|
|
38
40
|
# schema-0 stay clean, so a flat-panel install never pulls it in — which is
|
|
39
41
|
# what bounds the release coupling this dependency introduces to panels on
|
|
@@ -17,9 +17,10 @@ tree, and the SDK repopulates — so there is no resync hook to wire or forget.
|
|
|
17
17
|
|
|
18
18
|
from __future__ import annotations
|
|
19
19
|
|
|
20
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
20
21
|
import logging
|
|
21
22
|
import time
|
|
22
|
-
from typing import TYPE_CHECKING, Final
|
|
23
|
+
from typing import TYPE_CHECKING, Final, NamedTuple
|
|
23
24
|
|
|
24
25
|
from ebus_sdk import Controller
|
|
25
26
|
|
|
@@ -45,22 +46,38 @@ from span_panel_api_schema_1.const import (
|
|
|
45
46
|
STATE_READY,
|
|
46
47
|
TYPE_CIRCUIT,
|
|
47
48
|
)
|
|
48
|
-
from span_panel_api_schema_1.description import declared_settable, device_type, node_properties
|
|
49
|
+
from span_panel_api_schema_1.description import declared_settable, declares_class, device_type, node_properties
|
|
49
50
|
from span_panel_api_schema_1.devices import feed_circuit_ids
|
|
50
51
|
from span_panel_api_schema_1.field_metadata import build_field_metadata
|
|
51
52
|
from span_panel_api_schema_1.panel import integer, positions_outside_model, text
|
|
52
53
|
from span_panel_api_schema_1.snapshot import TreeRoles, build_snapshot, harmonised_evse_keys
|
|
53
54
|
from span_panel_api_schema_1.transport import ControllerRoutes, control_target
|
|
55
|
+
from span_panel_api_schema_1.tree_export import export_masked_tree
|
|
54
56
|
|
|
55
57
|
if TYPE_CHECKING:
|
|
56
58
|
from collections.abc import Callable
|
|
57
59
|
|
|
58
60
|
from ebus_sdk.homie import DiscoveredDevice
|
|
59
61
|
|
|
60
|
-
from span_panel_api.models import FieldMetadata, SpanPanelSnapshot, V2HomieSchema
|
|
62
|
+
from span_panel_api.models import FieldMetadata, MaskedTree, SpanPanelSnapshot, V2HomieSchema
|
|
61
63
|
|
|
62
64
|
_LOGGER = logging.getLogger(__name__)
|
|
63
65
|
|
|
66
|
+
_DISTRIBUTION: Final = "span-panel-api-schema-1"
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _producer() -> str:
|
|
70
|
+
"""The distribution and version that wrote an export, or ``unknown`` where this code runs without its dist-info.
|
|
71
|
+
|
|
72
|
+
A checkout put on ``sys.path`` has no installed metadata, and an export must
|
|
73
|
+
not fail for the lack of a version string.
|
|
74
|
+
"""
|
|
75
|
+
try:
|
|
76
|
+
return f"{_DISTRIBUTION} {version(_DISTRIBUTION)}"
|
|
77
|
+
except PackageNotFoundError:
|
|
78
|
+
return f"{_DISTRIBUTION} unknown"
|
|
79
|
+
|
|
80
|
+
|
|
64
81
|
FEED_GRACE_S: Final = 2.0
|
|
65
82
|
"""How long an inverter's feed or a DER's model may stay unvalued once every name has arrived.
|
|
66
83
|
|
|
@@ -71,6 +88,50 @@ connection record at all, and a declared model may never be valued.
|
|
|
71
88
|
"""
|
|
72
89
|
|
|
73
90
|
|
|
91
|
+
class _ValueTopic(NamedTuple):
|
|
92
|
+
"""One device's `node/property`, and whether the topic carries its value or its `$target`."""
|
|
93
|
+
|
|
94
|
+
device_id: str
|
|
95
|
+
node_id: str
|
|
96
|
+
property_id: str
|
|
97
|
+
target: bool
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _value_topic(topic: str) -> _ValueTopic | None:
|
|
101
|
+
"""The value or `$target` a topic addresses, or None for any other topic.
|
|
102
|
+
|
|
103
|
+
The two shapes `Controller` stores a payload under, read as it reads them:
|
|
104
|
+
`<domain>/5/<device>/<node>/<property>` is a value unless the property id
|
|
105
|
+
starts with `$`, and `<domain>/5/<device>/<node>/<property>/$target` is a
|
|
106
|
+
target. `$state`, `$description` and every other shape are not values.
|
|
107
|
+
"""
|
|
108
|
+
parts = topic.split("/")
|
|
109
|
+
if parts[:2] != [HOMIE_DOMAIN, HOMIE_VERSION]:
|
|
110
|
+
return None
|
|
111
|
+
if len(parts) == 5 and not parts[4].startswith("$"):
|
|
112
|
+
return _ValueTopic(parts[2], parts[3], parts[4], target=False)
|
|
113
|
+
if len(parts) == 6 and parts[5] == "$target":
|
|
114
|
+
return _ValueTopic(parts[2], parts[3], parts[4], target=True)
|
|
115
|
+
return None
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def _forget(by_node: object, node_id: str, property_id: str) -> bool:
|
|
119
|
+
"""Remove one value from an SDK `{node: {property: value}}` map; whether there was one.
|
|
120
|
+
|
|
121
|
+
A node left with no values is removed with its last one, so the map holds
|
|
122
|
+
what the broker retains and nothing more.
|
|
123
|
+
"""
|
|
124
|
+
if not isinstance(by_node, dict):
|
|
125
|
+
return False
|
|
126
|
+
by_property: object = by_node.get(node_id)
|
|
127
|
+
if not isinstance(by_property, dict) or property_id not in by_property:
|
|
128
|
+
return False
|
|
129
|
+
del by_property[property_id]
|
|
130
|
+
if not by_property:
|
|
131
|
+
del by_node[node_id]
|
|
132
|
+
return True
|
|
133
|
+
|
|
134
|
+
|
|
74
135
|
def _unvalued_feeds_for_unplaced_pvs(roles: TreeRoles) -> list[str]:
|
|
75
136
|
"""Circuits whose feed has not arrived, while an inverter has no known source.
|
|
76
137
|
|
|
@@ -145,8 +206,48 @@ class SchemaOneAdapter:
|
|
|
145
206
|
return [f"{HOMIE_DOMAIN}/{HOMIE_VERSION}/#"]
|
|
146
207
|
|
|
147
208
|
def handle_message(self, topic: str, payload: str) -> None:
|
|
209
|
+
"""Route one message to the SDK callback that asked for it, keeping a clear a clear.
|
|
210
|
+
|
|
211
|
+
A zero-length payload deletes a retained message, and Homie 5 spells an
|
|
212
|
+
empty string differently, as one `0x00` byte, so that the two stay
|
|
213
|
+
apart. The SDK decodes both to `""` and stores it, which would leave a
|
|
214
|
+
property the panel cleared reading as one it published empty. So a
|
|
215
|
+
clear of a value or `$target` the tree holds is applied here: the
|
|
216
|
+
stored value goes, exactly as an unpublished one is absent, and
|
|
217
|
+
property observers hear `None`. A clear of `$state` (the SDK's device
|
|
218
|
+
removal) or `$description` still goes to the SDK, as does anything
|
|
219
|
+
else. A `$description` cleared on its own makes the SDK log
|
|
220
|
+
`descriptionParseError` at ERROR and keep the stale description; that
|
|
221
|
+
is normally silent only because Homie clears `$state` first, after
|
|
222
|
+
which the SDK no longer holds the device and ignores the rest.
|
|
223
|
+
"""
|
|
224
|
+
if not payload and self._clear(topic):
|
|
225
|
+
return
|
|
148
226
|
self._routes.dispatch(topic, payload)
|
|
149
227
|
|
|
228
|
+
def _clear(self, topic: str) -> bool:
|
|
229
|
+
"""Apply a clear of a value or target; False where the topic addresses none the tree holds.
|
|
230
|
+
|
|
231
|
+
Only a device the controller holds is touched, the same test the SDK
|
|
232
|
+
applies before storing a value. Any other clear goes on to dispatch,
|
|
233
|
+
where a route the SDK still records for a device it dropped ignores it,
|
|
234
|
+
and an unrouted one takes back what is held for its topic.
|
|
235
|
+
|
|
236
|
+
A clear of a value that was never published changes nothing and is not
|
|
237
|
+
reported. A cleared value is reported as a change, so it forgets the
|
|
238
|
+
remembered readiness where a new value would; a cleared target is not,
|
|
239
|
+
as no target change is.
|
|
240
|
+
"""
|
|
241
|
+
address = _value_topic(topic)
|
|
242
|
+
device = None if address is None else self._controller.get_device(address.device_id)
|
|
243
|
+
if address is None or device is None:
|
|
244
|
+
return False
|
|
245
|
+
if address.target:
|
|
246
|
+
_forget(device.property_targets, address.node_id, address.property_id)
|
|
247
|
+
elif _forget(device.properties, address.node_id, address.property_id):
|
|
248
|
+
self._notify(address.device_id, address.node_id, address.property_id, None)
|
|
249
|
+
return True
|
|
250
|
+
|
|
150
251
|
def is_ready(self) -> bool:
|
|
151
252
|
"""Ready when the whole declared tree has described itself.
|
|
152
253
|
|
|
@@ -360,13 +461,15 @@ class SchemaOneAdapter:
|
|
|
360
461
|
return []
|
|
361
462
|
|
|
362
463
|
def find_node_by_type(self, type_str: str) -> str | None:
|
|
363
|
-
"""Return the id of the first device declaring `type_str
|
|
464
|
+
"""Return the id of the first device declaring `type_str` or a subtype of it.
|
|
364
465
|
|
|
365
466
|
Named for the flat schema's nodes; under parent/child the same question
|
|
366
|
-
is asked of devices, and the answer is a device id.
|
|
467
|
+
is asked of devices, and the answer is a device id. A device typed
|
|
468
|
+
``…device.bess.hybrid`` is a ``…device.bess`` (`declares_class`), the
|
|
469
|
+
same device the snapshot reads as the battery.
|
|
367
470
|
"""
|
|
368
471
|
for device in self._children():
|
|
369
|
-
if device_type(device)
|
|
472
|
+
if declares_class(device_type(device), type_str):
|
|
370
473
|
return device.device_id
|
|
371
474
|
return None
|
|
372
475
|
|
|
@@ -422,7 +525,9 @@ class SchemaOneAdapter:
|
|
|
422
525
|
is addressable by id — the BESS, the MID, the lugs, a charger — and none
|
|
423
526
|
of them is a circuit, so answering on membership alone would report a
|
|
424
527
|
BESS as a circuit whose relay the panel declares non-commandable. It
|
|
425
|
-
declares no relay at all.
|
|
528
|
+
declares no relay at all. The class is the answer rather than the exact
|
|
529
|
+
type, so a subtyped circuit the snapshot reads into `circuits` is a
|
|
530
|
+
circuit here too.
|
|
426
531
|
|
|
427
532
|
A child that has not described itself yet reads as absent, because it
|
|
428
533
|
has declared nothing: type, nodes and properties all arrive together in
|
|
@@ -435,7 +540,7 @@ class SchemaOneAdapter:
|
|
|
435
540
|
would put a second, weaker rule where the authorisation lives.
|
|
436
541
|
"""
|
|
437
542
|
device = self._child(circuit_id)
|
|
438
|
-
return device is not None and device_type(device)
|
|
543
|
+
return device is not None and declares_class(device_type(device), TYPE_CIRCUIT)
|
|
439
544
|
|
|
440
545
|
def set_dominant_power_source_target(self) -> ControlTarget | None:
|
|
441
546
|
"""The settable successor: `shed/asserted-islanding-state` on the panel.
|
|
@@ -534,22 +639,39 @@ class SchemaOneAdapter:
|
|
|
534
639
|
charge-only EVSE cannot be told to export by lowering a ceiling, so a
|
|
535
640
|
negative value is not a smaller limit but a malformed one.
|
|
536
641
|
|
|
642
|
+
**Refuses outside the range the limit declares.** Firmware r202639
|
|
643
|
+
publishes `<min>:<commissioned maximum>` as the limit's `$format`
|
|
644
|
+
(`6:32`), so a value under the minimum is refused here instead of being
|
|
645
|
+
published for the panel to reject or misapply. A declared maximum
|
|
646
|
+
tighter than the ceiling applies too. A format that is absent, or that
|
|
647
|
+
cannot be read as an integer range, bounds nothing extra and the
|
|
648
|
+
ceiling rule above still holds.
|
|
649
|
+
|
|
537
650
|
A charger that declares no ceiling is not second-guessed — the catalog
|
|
538
|
-
makes `installer-max` a SHOULD, and the
|
|
539
|
-
the
|
|
651
|
+
makes `installer-max` a SHOULD, and the values that bound the write are
|
|
652
|
+
the ones the panel published, not ones this library invents. With no
|
|
653
|
+
ceiling, a maximum declared in the limit's `$format` still bounds the
|
|
654
|
+
write; with neither, nothing does.
|
|
540
655
|
"""
|
|
541
656
|
writable = self._writable_charge_limit(node_id)
|
|
542
657
|
if writable is None or amps < 0:
|
|
543
658
|
return None
|
|
544
|
-
device, surface,
|
|
659
|
+
device, surface, limit = writable
|
|
545
660
|
ceiling = surface.ceiling
|
|
546
661
|
commissioned = None if ceiling is None else integer(device, surface.node, ceiling.property_id)
|
|
547
662
|
if commissioned is not None and amps > commissioned:
|
|
548
663
|
return None
|
|
664
|
+
if limit.bounds is not None:
|
|
665
|
+
minimum, maximum = limit.bounds
|
|
666
|
+
if (minimum is not None and amps < minimum) or (maximum is not None and amps > maximum):
|
|
667
|
+
return None
|
|
549
668
|
return str(amps)
|
|
550
669
|
|
|
551
670
|
def register_property_callback(self, callback: Callable[[str, str, str, str | None], None]) -> Callable[[], None]:
|
|
552
|
-
"""Subscribe to per-property updates: `(device_id, node_id, property_id, value)`.
|
|
671
|
+
"""Subscribe to per-property updates: `(device_id, node_id, property_id, value)`.
|
|
672
|
+
|
|
673
|
+
`value` is `None` when the panel clears a value it had published.
|
|
674
|
+
"""
|
|
553
675
|
self._property_callbacks.append(callback)
|
|
554
676
|
|
|
555
677
|
def _unregister() -> None:
|
|
@@ -585,6 +707,23 @@ class SchemaOneAdapter:
|
|
|
585
707
|
return device, surface, surface.limit
|
|
586
708
|
return None
|
|
587
709
|
|
|
710
|
+
def export_masked_tree(self) -> MaskedTree | None:
|
|
711
|
+
"""The device tree the adapter holds, masked, or None before the root has described itself.
|
|
712
|
+
|
|
713
|
+
Computed at call time and not gated on `is_ready()`: a tree that has not
|
|
714
|
+
finished arriving is exactly when a diagnostic is wanted, and
|
|
715
|
+
`metadata["tree_complete"]` says whether this one is whole.
|
|
716
|
+
"""
|
|
717
|
+
root = self._controller.get_root(self._serial_number)
|
|
718
|
+
if root is None or root.description is None:
|
|
719
|
+
return None
|
|
720
|
+
return export_masked_tree(
|
|
721
|
+
root,
|
|
722
|
+
self._children(),
|
|
723
|
+
producer=_producer(),
|
|
724
|
+
tree_complete=self._controller.is_tree_complete(self._serial_number),
|
|
725
|
+
)
|
|
726
|
+
|
|
588
727
|
def _require_root(self) -> DiscoveredDevice:
|
|
589
728
|
"""The root, or a clear error if discovery has not finished.
|
|
590
729
|
|
|
@@ -648,6 +787,10 @@ class SchemaOneAdapter:
|
|
|
648
787
|
protocol has no place for the previous value, and consumers that need
|
|
649
788
|
one keep it themselves.
|
|
650
789
|
"""
|
|
790
|
+
self._notify(device_id, node_id, property_id, value)
|
|
791
|
+
|
|
792
|
+
def _notify(self, device_id: str, node_id: str, property_id: str, value: str | None) -> None:
|
|
793
|
+
"""Report one property's new value, `None` once cleared, after forgetting what it invalidates."""
|
|
651
794
|
# The one value readiness waits on.
|
|
652
795
|
if (device_id, node_id, property_id) == (self._serial_number, NODE_INFO, PROP_MODEL):
|
|
653
796
|
self._ready = None
|
|
@@ -35,7 +35,14 @@ from span_panel_api_schema_1.const import (
|
|
|
35
35
|
TYPE_PANEL,
|
|
36
36
|
TYPE_PV,
|
|
37
37
|
)
|
|
38
|
-
from span_panel_api_schema_1.description import
|
|
38
|
+
from span_panel_api_schema_1.description import (
|
|
39
|
+
declared_settable,
|
|
40
|
+
declares_class,
|
|
41
|
+
device_type,
|
|
42
|
+
nodes,
|
|
43
|
+
optional_str,
|
|
44
|
+
properties,
|
|
45
|
+
)
|
|
39
46
|
|
|
40
47
|
if TYPE_CHECKING:
|
|
41
48
|
from ebus_sdk.homie import DiscoveredDevice
|
|
@@ -72,10 +79,11 @@ def is_modelled(declared: str) -> bool:
|
|
|
72
79
|
Subtype-aware, because firmware may declare either a base type or a subtype
|
|
73
80
|
of it -- ``…device.lugs`` with a ``direction`` property, or
|
|
74
81
|
``…device.lugs.upstream``. A subtype of something modelled is modelled: the
|
|
75
|
-
snapshot builder
|
|
76
|
-
|
|
82
|
+
snapshot builder sorts each class with the same `declares_class`, so the
|
|
83
|
+
two agree about which devices a class covers, and a subtype the builder
|
|
84
|
+
reads is never adopted behind its back.
|
|
77
85
|
"""
|
|
78
|
-
return any(declared
|
|
86
|
+
return any(declares_class(declared, known) for known in MODELLED_TYPES)
|
|
79
87
|
|
|
80
88
|
|
|
81
89
|
def build_adopted_devices(children: list[DiscoveredDevice]) -> tuple[AdoptedDevice, ...]:
|
|
@@ -39,6 +39,7 @@ Homie 5's default rather than a rule this module chose, and it is the same one
|
|
|
39
39
|
from __future__ import annotations
|
|
40
40
|
|
|
41
41
|
from dataclasses import dataclass
|
|
42
|
+
import re
|
|
42
43
|
from typing import TYPE_CHECKING
|
|
43
44
|
|
|
44
45
|
from span_panel_api_schema_1.description import declared_settable, nodes, optional_str, properties
|
|
@@ -81,6 +82,42 @@ mappings.
|
|
|
81
82
|
"""
|
|
82
83
|
|
|
83
84
|
|
|
85
|
+
_PLAIN_INTEGER = re.compile(r"-?[0-9]+", re.ASCII)
|
|
86
|
+
|
|
87
|
+
IntegerBounds = tuple[int | None, int | None]
|
|
88
|
+
"""A declared integer range, `(minimum, maximum)`; None on a side the format leaves open."""
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def declared_integer_bounds(datatype: str, declared: object) -> IntegerBounds | None:
|
|
92
|
+
"""The range an `integer` property's `$format` declares, or None.
|
|
93
|
+
|
|
94
|
+
Homie 5 spells it `<min>:<max>` and allows either side to be empty. Anything
|
|
95
|
+
else is not interpreted: a format that is not a string, a datatype that is
|
|
96
|
+
not `integer`, a missing colon, extra segments, or a bound that is not a
|
|
97
|
+
plain integer (an optional minus sign and ASCII digits, so `1_0`, `+6` and
|
|
98
|
+
non-ASCII digits are refused) or a minimum above the maximum all yield None,
|
|
99
|
+
which bounds nothing. Guessing a range from a format we cannot read would
|
|
100
|
+
refuse a write the panel might accept, and the commissioned ceiling still
|
|
101
|
+
applies either way.
|
|
102
|
+
|
|
103
|
+
A property declared `float` is not bounded by its range: only `integer`
|
|
104
|
+
ranges are read.
|
|
105
|
+
"""
|
|
106
|
+
if datatype != "integer" or not isinstance(declared, str):
|
|
107
|
+
return None
|
|
108
|
+
parts = declared.split(":")
|
|
109
|
+
if len(parts) != 2:
|
|
110
|
+
return None
|
|
111
|
+
low, high = parts[0].strip(), parts[1].strip()
|
|
112
|
+
if any(text and _PLAIN_INTEGER.fullmatch(text) is None for text in (low, high)):
|
|
113
|
+
return None
|
|
114
|
+
minimum = int(low) if low else None
|
|
115
|
+
maximum = int(high) if high else None
|
|
116
|
+
if minimum is not None and maximum is not None and minimum > maximum:
|
|
117
|
+
return None
|
|
118
|
+
return minimum, maximum
|
|
119
|
+
|
|
120
|
+
|
|
84
121
|
@dataclass(frozen=True, slots=True)
|
|
85
122
|
class ChargeLimitProperty:
|
|
86
123
|
"""One declared property of the resolved surface.
|
|
@@ -95,6 +132,8 @@ class ChargeLimitProperty:
|
|
|
95
132
|
unit: str | None
|
|
96
133
|
datatype: str
|
|
97
134
|
settable: bool
|
|
135
|
+
bounds: IntegerBounds | None = None
|
|
136
|
+
"""The `<min>:<max>` range the declaration's `$format` states, or None where it states none we can read."""
|
|
98
137
|
|
|
99
138
|
|
|
100
139
|
@dataclass(frozen=True, slots=True)
|
|
@@ -144,9 +183,11 @@ def resolve_charge_limit(device: DiscoveredDevice | None) -> ChargeLimitSurface
|
|
|
144
183
|
def _property(property_id: str, definition: dict[str, object] | None) -> ChargeLimitProperty | None:
|
|
145
184
|
if definition is None:
|
|
146
185
|
return None
|
|
186
|
+
datatype = str(definition.get("datatype") or "string")
|
|
147
187
|
return ChargeLimitProperty(
|
|
148
188
|
property_id=property_id,
|
|
149
189
|
unit=optional_str(definition.get("unit")),
|
|
150
|
-
datatype=
|
|
190
|
+
datatype=datatype,
|
|
151
191
|
settable=declared_settable(definition),
|
|
192
|
+
bounds=declared_integer_bounds(datatype, definition.get("format")),
|
|
152
193
|
)
|
|
@@ -36,6 +36,21 @@ def device_type(device: DiscoveredDevice) -> str:
|
|
|
36
36
|
return str(declared) if declared else ""
|
|
37
37
|
|
|
38
38
|
|
|
39
|
+
def declares_class(declared: str, known: str) -> bool:
|
|
40
|
+
"""Whether a declared device type is the class `known` or a subtype of it.
|
|
41
|
+
|
|
42
|
+
eBus device types are hierarchical and a subtype carries its parent's
|
|
43
|
+
class, so a device typed ``…device.bess.hybrid`` is a ``…device.bess``.
|
|
44
|
+
The boundary is the dot: ``…device.lugsfoo`` merely begins with
|
|
45
|
+
``…device.lugs`` and names a different class.
|
|
46
|
+
|
|
47
|
+
The one answer to the question for every reader of a type -- the snapshot
|
|
48
|
+
roles, adoption, field metadata and discovery -- so that no two of them can
|
|
49
|
+
disagree about which class a device belongs to.
|
|
50
|
+
"""
|
|
51
|
+
return declared == known or declared.startswith(f"{known}.")
|
|
52
|
+
|
|
53
|
+
|
|
39
54
|
def nodes(description: dict[str, object]) -> dict[str, dict[str, object]]:
|
|
40
55
|
"""The capability nodes a description declares, by node id."""
|
|
41
56
|
declared = description.get("nodes")
|
|
@@ -36,12 +36,13 @@ From r202639 the BESS meter is published discharge-positive, the negation of
|
|
|
36
36
|
The frame is chosen from the enclosure's release build number
|
|
37
37
|
(``firmware.release_build``), never from the respin suffix after it. Where the
|
|
38
38
|
version does not parse, the two wire properties decide instead: one nonzero sign
|
|
39
|
-
on both is the old frame, opposite signs the new one.
|
|
39
|
+
on both is the old frame, opposite signs the new one. The reference capture
|
|
40
|
+
(``ebus-panel-sim`` 0.9.0) publishes no SPAN version string and is read this way:
|
|
41
|
+
it carries r202639's frame, told by its opposite signs. Where either is zero or
|
|
40
42
|
absent the old frame is assumed, because that is what every earlier release of
|
|
41
|
-
this package applied
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
or zero flow figure.
|
|
43
|
+
this package applied. A battery at rest reads zero in both frames, so the
|
|
44
|
+
assumption only decides a nonzero BESS meter beside a missing or zero flow
|
|
45
|
+
figure.
|
|
45
46
|
|
|
46
47
|
On either firmware ``panel.power_flow_battery`` (passed through untouched, and
|
|
47
48
|
charge-positive) and ``battery.power_w`` end up as each other's mirror, so a
|
|
@@ -53,7 +54,7 @@ from __future__ import annotations
|
|
|
53
54
|
from typing import TYPE_CHECKING
|
|
54
55
|
|
|
55
56
|
from span_panel_api.models import SpanBatterySnapshot, SpanEvseSnapshot, SpanMidSnapshot, SpanPVSnapshot
|
|
56
|
-
from span_panel_api_schema_1.charge_limit import ChargeLimitProperty, ChargeLimitSurface, resolve_charge_limit
|
|
57
|
+
from span_panel_api_schema_1.charge_limit import ChargeLimitProperty, ChargeLimitSurface, IntegerBounds, resolve_charge_limit
|
|
57
58
|
from span_panel_api_schema_1.const import (
|
|
58
59
|
NODE_CONNECTION,
|
|
59
60
|
NODE_GRID,
|
|
@@ -368,9 +369,12 @@ def build_evse(
|
|
|
368
369
|
The charge-current pair is read through `resolve_charge_limit` rather than
|
|
369
370
|
from named constants, because which node and properties carry it is a
|
|
370
371
|
question only this charger's `$description` can answer. See
|
|
371
|
-
`span_panel_api_schema_1.charge_limit`.
|
|
372
|
+
`span_panel_api_schema_1.charge_limit`. The limit's declared range comes from
|
|
373
|
+
the same resolution, so the range a control offers and the range
|
|
374
|
+
`SchemaOneAdapter.evse_charge_limit_payload` enforces cannot disagree.
|
|
372
375
|
"""
|
|
373
376
|
limit = resolve_charge_limit(evse)
|
|
377
|
+
minimum, maximum = _limit_bounds(limit)
|
|
374
378
|
return SpanEvseSnapshot(
|
|
375
379
|
node_id=node_id,
|
|
376
380
|
feed_circuit_id=feeds.get(evse.device_id, ""),
|
|
@@ -393,9 +397,23 @@ def build_evse(
|
|
|
393
397
|
charge_current_ceiling_a=_limit_value(evse, limit, limit.ceiling) if limit else None,
|
|
394
398
|
charge_current_limit_target_a=_limit_target(evse, limit),
|
|
395
399
|
charge_current_limit_settable=limit is not None and limit.limit is not None and limit.limit.settable,
|
|
400
|
+
charge_current_limit_minimum_a=minimum,
|
|
401
|
+
charge_current_limit_maximum_a=maximum,
|
|
396
402
|
)
|
|
397
403
|
|
|
398
404
|
|
|
405
|
+
def _limit_bounds(surface: ChargeLimitSurface | None) -> IntegerBounds:
|
|
406
|
+
"""The range the resolved limit declares, `None` on a side it leaves open or cannot be read.
|
|
407
|
+
|
|
408
|
+
`ChargeLimitProperty.bounds` is already None for a format
|
|
409
|
+
`declared_integer_bounds` will not interpret, so a declaration that bounds
|
|
410
|
+
nothing on the write path reports no range here either.
|
|
411
|
+
"""
|
|
412
|
+
if surface is None or surface.limit is None or surface.limit.bounds is None:
|
|
413
|
+
return None, None
|
|
414
|
+
return surface.limit.bounds
|
|
415
|
+
|
|
416
|
+
|
|
399
417
|
def _limit_value(evse: DiscoveredDevice, surface: ChargeLimitSurface, declaration: ChargeLimitProperty | None) -> int | None:
|
|
400
418
|
"""One half of the resolved charge-limit pair, or None where it is not declared."""
|
|
401
419
|
if declaration is None:
|
|
@@ -54,6 +54,7 @@ from span_panel_api_schema_1.const import (
|
|
|
54
54
|
TYPE_PV,
|
|
55
55
|
)
|
|
56
56
|
from span_panel_api_schema_1.description import (
|
|
57
|
+
declares_class,
|
|
57
58
|
device_type as declared_type,
|
|
58
59
|
nodes as declared_nodes,
|
|
59
60
|
optional_str,
|
|
@@ -221,7 +222,7 @@ def build_field_metadata(devices: list[DiscoveredDevice]) -> dict[str, FieldMeta
|
|
|
221
222
|
present_type_nodes: set[tuple[str, str]] = set()
|
|
222
223
|
for device in devices:
|
|
223
224
|
description: dict[str, object] = device.description or {}
|
|
224
|
-
device_type =
|
|
225
|
+
device_type = declared_type(device)
|
|
225
226
|
if not device_type:
|
|
226
227
|
continue
|
|
227
228
|
for node_id, node in declared_nodes(description).items():
|
|
@@ -274,7 +275,7 @@ def _charge_limit_metadata(devices: list[DiscoveredDevice]) -> dict[str, FieldMe
|
|
|
274
275
|
rather than absent hardware.
|
|
275
276
|
"""
|
|
276
277
|
for device in devices:
|
|
277
|
-
if not declared_type(device)
|
|
278
|
+
if not declares_class(declared_type(device), TYPE_EVSE):
|
|
278
279
|
continue
|
|
279
280
|
surface = resolve_charge_limit(device)
|
|
280
281
|
if surface is None:
|
|
@@ -293,16 +294,16 @@ def _charge_limit_entry(declaration: ChargeLimitProperty | None) -> FieldMetadat
|
|
|
293
294
|
|
|
294
295
|
|
|
295
296
|
def _node_declared(present_type_nodes: set[tuple[str, str]], device_type: str, node_id: str) -> bool:
|
|
296
|
-
"""Whether any present device of this type declares this node.
|
|
297
|
+
"""Whether any present device of this type, or a subtype of it, declares this node.
|
|
297
298
|
|
|
298
|
-
|
|
299
|
-
agree about which devices answer for a row, or a subtyped device that
|
|
299
|
+
Asks `declares_class`, as `_lookup` does, and has to: presence and lookup
|
|
300
|
+
must agree about which devices answer for a row, or a subtyped device that
|
|
300
301
|
dropped a property would resolve through one and misclassify through the
|
|
301
302
|
other. Both are now exercised on non-lugs types, lugs having moved to a
|
|
302
303
|
direction-resolved lookup of their own.
|
|
303
304
|
"""
|
|
304
305
|
return any(
|
|
305
|
-
node == node_id and (declared_device_type
|
|
306
|
+
node == node_id and declares_class(declared_device_type, device_type)
|
|
306
307
|
for declared_device_type, node in present_type_nodes
|
|
307
308
|
)
|
|
308
309
|
|
|
@@ -376,7 +377,7 @@ def _lugs_metadata(
|
|
|
376
377
|
and so yields no entry, which is deliberate: the mapper reads its values
|
|
377
378
|
through the same call, so nothing would populate those fields either.
|
|
378
379
|
"""
|
|
379
|
-
lugs = find_lugs([d for d in devices if declared_type(d)
|
|
380
|
+
lugs = find_lugs([d for d in devices if declares_class(declared_type(d), TYPE_LUGS)], upstream=upstream)
|
|
380
381
|
if lugs is None:
|
|
381
382
|
return {}
|
|
382
383
|
|
|
@@ -405,7 +406,8 @@ def _lookup(
|
|
|
405
406
|
"""Find a declaration, allowing a device type to be a subtype of the mapped one.
|
|
406
407
|
|
|
407
408
|
eBus device types are hierarchical and a subtype carries its parent's
|
|
408
|
-
properties, so a device typed `X.Y` satisfies a row written for `X
|
|
409
|
+
properties, so a device typed `X.Y` satisfies a row written for `X`
|
|
410
|
+
(`declares_class`), and one typed `Xfoo` does not.
|
|
409
411
|
|
|
410
412
|
Lugs were the observed instance — `…device.lugs` versus a subtyped
|
|
411
413
|
`…device.lugs.upstream` — and they no longer come through here, because
|
|
@@ -419,7 +421,7 @@ def _lookup(
|
|
|
419
421
|
return exact
|
|
420
422
|
suffix = f"|{node_id}|{property_id}"
|
|
421
423
|
for key, value in declared.items():
|
|
422
|
-
if key.endswith(suffix) and key[: -len(suffix)]
|
|
424
|
+
if key.endswith(suffix) and declares_class(key[: -len(suffix)], device_type):
|
|
423
425
|
return value
|
|
424
426
|
return None
|
|
425
427
|
|
|
@@ -570,7 +572,7 @@ def addressed_rows(devices: list[DiscoveredDevice]) -> set[tuple[str, str, str]]
|
|
|
570
572
|
addressed = set(_ADDRESSED)
|
|
571
573
|
for device in devices:
|
|
572
574
|
evse_type = declared_type(device)
|
|
573
|
-
if not evse_type
|
|
575
|
+
if not declares_class(evse_type, TYPE_EVSE):
|
|
574
576
|
continue
|
|
575
577
|
surface = resolve_charge_limit(device)
|
|
576
578
|
if surface is None:
|
|
@@ -643,14 +645,14 @@ def _short_type(device_type: str) -> str:
|
|
|
643
645
|
def is_addressed(addressed: set[tuple[str, str, str]], device_type: str, node_id: str, property_id: str) -> bool:
|
|
644
646
|
"""Whether any addressed row covers this declaration, subtypes included.
|
|
645
647
|
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
648
|
+
Asks `declares_class`, as `_lookup` does, for the same reason: eBus device
|
|
649
|
+
types are hierarchical and a subtype carries its parent's properties, so a
|
|
650
|
+
device typed ``X.Y`` is served by a row written for ``X``. Without it a
|
|
649
651
|
panel that subtypes its lugs devices would report every mapped lugs property
|
|
650
652
|
as newly discovered — which is the false positive that would teach a
|
|
651
653
|
maintainer to stop reading this.
|
|
652
654
|
"""
|
|
653
655
|
return any(
|
|
654
|
-
node == node_id and prop == property_id and (device_type
|
|
656
|
+
node == node_id and prop == property_id and declares_class(device_type, mapped_type)
|
|
655
657
|
for mapped_type, node, prop in addressed
|
|
656
658
|
)
|