Capability report: PUT /devices/{id}/report, a Capabilities section, offline devices degraded

A device reports its board, screen, camera and ports from its own
credential (16 KB, schema 1, replacing the last report), and the flows
are validated against it again. The node panel turns a reported port's
config schema into a form, a reported screen is a canvas preset and a
touch screen's first report turns Touch friendly on. An offline device
node is degraded: amber on the canvas, a warning on Home, never a fault.
This commit is contained in:
Melvin Strobl
2026-10-16 17:37:49 +02:00
parent 1dc891aa1b
commit 4286acadfd
28 changed files with 820 additions and 129 deletions
+36 -4
View File
@@ -1363,9 +1363,14 @@ class FlowController:
}
)
def unhealthy_nodes(self, flow: str | None = None) -> list[LoadedNode]:
def unhealthy_nodes(
self, flow: str | None = None, health: Health = "down"
) -> list[LoadedNode]:
"""Nodes that have been down long enough to be worth telling anyone.
Or degraded, with ``health``: working, but not as well as they should,
which is a warning rather than a fault.
The floor is on the surfacing, not on the transition: `entry.health` is
the truth the moment the node reports it, so a flow reading a node's
health is never told a stale story — only the screens wait. And only
@@ -1376,7 +1381,7 @@ class FlowController:
return [
entry
for entry in self.loaded.values()
if entry.health == "down"
if entry.health == health
and now - entry.health_since >= HEALTH_FLOOR
and (flow is None or entry.flow == flow)
]
@@ -1384,6 +1389,9 @@ class FlowController:
def _health_issues(self, flow: str | None = None) -> list[ValidationIssue]:
"""Nodes that are running but not working, as issues on their flow.
A degraded node is an advisory one: it works, if not as it should, such
as a device node whose device is switched off.
Not part of `self.issues`: that list is what a build found, and this is
what is happening now. Derived on read, so a node reporting itself well
again clears it with nothing to remember.
@@ -1399,6 +1407,17 @@ class FlowController:
node=entry.id,
)
for entry in self.unhealthy_nodes(flow)
] + [
ValidationIssue(
code="node_degraded",
message=(
f"Node '{entry.id.rpartition('.')[2]}' is degraded: "
f"{entry.health_detail or 'no detail given'}"
),
flow=entry.flow,
node=entry.id,
)
for entry in self.unhealthy_nodes(flow, "degraded")
]
def flow_issues(self, flow: str) -> list[ValidationIssue]:
@@ -2101,6 +2120,10 @@ def _collect_issues(
return issues
#: The dtypes a device port reads as a plain number.
_NUMBERS = frozenset({"int", "float"})
def _device_issues(
loaded: dict[str, LoadedNode], devices: Any
) -> list[ValidationIssue]:
@@ -2111,6 +2134,10 @@ def _device_issues(
direction or of another dtype is an error too, and one the device does not
list is a warning: the device may know it all the same. Without a report
a port is the device's business and nothing is said about it.
A port reporting ``modes`` may be wired in any of them, as a GPIO pin is
either way. ``int`` and ``float`` pass for each other: the device reads a
number either way.
"""
if devices is None:
return []
@@ -2163,12 +2190,17 @@ def _device_issues(
elif said is None:
problem = f"'{device}' does not report a port '{spec.port}'."
advisory = True
elif said.get("direction") and said["direction"] != direction:
elif said.get("direction") and direction not in (
said.get("modes") or [said["direction"]]
):
problem = (
f"'{spec.port}' of '{device}' is an {said['direction']} "
f"port, wired here as {direction}."
)
elif said.get("dtype") and said["dtype"] != spec.dtype.value:
elif said.get("dtype") and not (
said["dtype"] == spec.dtype.value
or {said["dtype"], spec.dtype.value} <= _NUMBERS
):
problem = (
f"'{spec.port}' of '{device}' carries {said['dtype']}, "
f"wired here to a {spec.dtype.value} message."
+76 -1
View File
@@ -38,7 +38,13 @@ from pydantic import BaseModel, Field, TypeAdapter, ValidationError, field_valid
from fluksio.flow.dashboards import DashboardDef, DashboardNotFound, DashboardStore
from fluksio.flow.events import event_bus
from fluksio.flow.messages import MessageSpec, flow_of, qualify, validate_qualified
from fluksio.flow.messages import (
DType,
MessageSpec,
flow_of,
qualify,
validate_qualified,
)
from fluksio.flow.schemas import FlowDef, NodeDef, _validate_name
from fluksio.flow.store import FlowStore, InvalidName, StaleVersion, checked
@@ -158,6 +164,61 @@ class DeviceState(BaseModel):
_STATES = TypeAdapter(dict[str, DeviceState])
class ReportDisplay(BaseModel):
"""The device's screen, in pixels."""
w: int = Field(ge=0)
h: int = Field(ge=0)
shape: Literal["rect", "round"] = "rect"
touch: bool = False
class ReportPort(BaseModel):
"""One port the device has, and how it may be wired."""
port: str = Field(pattern=PORT_PATTERN.pattern)
#: Its default direction: ``in`` publishes, ``out`` follows.
direction: Literal["in", "out"]
dtype: DType
#: A JSON schema of the ``config`` the device reads for this port.
config: dict[str, Any] | None = None
#: Sends only while somebody wants it, such as a camera.
on_demand: bool | None = None
#: The directions it may be wired in, when it may be either: a GPIO pin.
modes: list[Literal["in", "out"]] | None = None
class ReportCamera(BaseModel):
"""The camera sensor the device found, and what it delivers."""
sensor: str = ""
w: int = 0
h: int = 0
fps: int = 0
class DeviceReport(BaseModel):
"""What a device says it has, version 1.
Keys this version does not know are dropped, so a newer firmware still
reports to an older instance. The whole report replaces the one before.
"""
version: Literal[1] = Field(alias="schema")
platform: str = ""
board: str = ""
firmware: str = ""
display: ReportDisplay | None = None
ports: list[ReportPort] = Field(default_factory=list)
camera: ReportCamera | None = None
#: The build's features, true when there: ``{"camera": true}``.
features: dict[str, bool] = Field(default_factory=dict)
def stored(self) -> dict[str, Any]:
"""As ``devices.json`` keeps it: the device's own keys, nothing unset."""
return self.model_dump(mode="json", by_alias=True, exclude_none=True)
class DeviceNotFound(KeyError):
def __init__(self, device_id: str) -> None:
super().__init__(device_id)
@@ -372,6 +433,20 @@ class DeviceStore:
self._write_states(states)
return state.nonce
def report(self, device_id: str, report: DeviceReport) -> bool:
"""Keep what the device says it has, in place of what it said before.
Returns whether it is the first report this device made.
"""
with self._state_lock:
states = self._read_states()
state = states.setdefault(device_id, DeviceState())
first = state.report is None
state.report = report.stored()
state.reported_at = datetime.now(UTC)
self._write_states(states)
return first
# -- the panels file of an older instance -------------------------------
def migrate(self, panels_file: Path) -> None:
+4 -2
View File
@@ -31,7 +31,7 @@ def _never(**_: Any) -> None:
class DeviceNode(Node):
"""A device's ports, wired to messages. Down while the device is away."""
"""A device's ports, wired to messages. Degraded while the device is away."""
passive = True
@@ -81,7 +81,9 @@ class DeviceNode(Node):
presence.unwatch(self.cfg.device, self._presence)
def _presence(self, online: bool) -> None:
# Degraded rather than down: a panel switched off or asleep is a thing
# to notice, not a fault of the flow wiring it.
if online:
self.report_health("ok")
else:
self.report_health("down", "Offline")
self.report_health("degraded", "Offline")
+2 -1
View File
@@ -47,7 +47,7 @@ MANUAL_RUN_PREFIX = "manual-"
# neither the brain graph nor the health summary treats them as a fault.
# Lives here rather than beside the controller so `ValidationIssue` can carry
# the distinction itself, and every reader gets it for free.
ADVISORY_ISSUES = frozenset({"unauthenticated_hook", "ignored_worker"})
ADVISORY_ISSUES = frozenset({"unauthenticated_hook", "ignored_worker", "node_degraded"})
class ValidationIssue(BaseModel):
@@ -62,6 +62,7 @@ class ValidationIssue(BaseModel):
"self_loop_needs_initial",
"missing_source",
"node_unhealthy",
"node_degraded",
"ignored_worker",
"unknown_device",
"device_port",