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
+7 -4
View File
@@ -189,10 +189,10 @@ def _device_may(payload: dict[str, Any], request: Request) -> None:
A panel credential names the account that approved the pairing, so without
this it would be that person's session hanging on a wall. What a panel
genuinely needs is small and worth writing out: the dashboards it was
assigned, its own definition, the messages its own widgets and ports bind
to, and the bytes those messages currently point at, for a tile drawing a
camera frame — plus an upload named after one of its ``in`` ports, for a
microphone whose recording is the value it publishes.
assigned, its own definition and report, the messages its own widgets and
ports bind to, and the bytes those messages currently point at, for a tile
drawing a camera frame — plus an upload named after one of its ``in``
ports, for a microphone whose recording is the value it publishes.
Publishing is in the list because a panel cannot be strictly read-only — a
control on a panel is the point of putting one there, and a querying chart
@@ -239,6 +239,9 @@ def _device_may(payload: dict[str, Any], request: Request) -> None:
f"{api}/panels/{device.id}",
):
allowed = True
elif method == "PUT" and path == f"{api}/devices/{device.id}/report":
# What it has, said about itself and nobody else.
allowed = True
elif method == "POST" and path == f"{api}/flows/ws-ticket":
# How its live socket opens; the socket applies the panel's own scope.
allowed = True
+77 -11
View File
@@ -18,8 +18,13 @@ device nodes in published flows wire its own ports to, and nothing else.
Deleting the device revokes it, and so does unpairing, which bumps the
device's nonce and leaves what it shows as it was.
``/panels/pair``, ``/panels/pair/{code}`` and ``GET /panels/{id}`` are what the
openpanel firmware calls, and stay as aliases until every device has updated.
Once paired, a device says what it has with ``PUT /devices/{id}/report``: its
board, its screen and the ports it serves, which the device node's ports are
checked against.
``/panels/pair``, ``/panels/pair/{code}`` and ``GET /panels/{id}`` are what
openpanel firmware from before devices calls, and stay as aliases until every
device has updated.
"""
from __future__ import annotations
@@ -34,7 +39,7 @@ import httpx
import redis
from fastapi import APIRouter, Depends, HTTPException, Request
from fastapi.concurrency import run_in_threadpool
from pydantic import BaseModel, Field, field_validator
from pydantic import BaseModel, Field, ValidationError, field_validator
from fluksio.api.deps import (
CurrentUser,
@@ -52,6 +57,7 @@ from fluksio.flow.devices import (
DeviceExists,
DeviceIo,
DeviceNotFound,
DeviceReport,
DeviceStore,
is_lan,
presence,
@@ -88,6 +94,10 @@ RESERVED = {"pair", "pending"}
#: How much of what a device says about itself is kept.
HELLO_LENGTH = 64
#: The most a capability report may weigh. A panel with every header pin
#: reported is a few kB.
REPORT_MAX = 16 * 1024
class _Pending(BaseModel):
"""A device waiting to be told what it is."""
@@ -314,6 +324,7 @@ class DevicePublic(DeviceDocument):
last_seen: datetime | None = None
#: What the device says it has, as it last said so. None until it reports.
report: dict[str, Any] | None = None
reported_at: datetime | None = None
class DevicesPublic(BaseModel):
@@ -499,15 +510,19 @@ async def read_devices(store: DeviceStoreDep) -> Any:
"""Every device, what each one shows, and whether it is connected."""
def gather() -> list[DevicePublic]:
return [
DevicePublic(
**_document(device, store).model_dump(),
online=presence.online(device.id),
last_seen=presence.last_seen(device.id),
report=store.state(device.id).report,
found = []
for device in store.list():
state = store.state(device.id)
found.append(
DevicePublic(
**_document(device, store).model_dump(),
online=presence.online(device.id),
last_seen=presence.last_seen(device.id),
report=state.report,
reported_at=state.reported_at,
)
)
for device in store.list()
]
return found
data = await run_in_threadpool(gather)
return DevicesPublic(
@@ -596,6 +611,57 @@ panels_router.add_api_route(
)
@router.put(
"/{device_id}/report",
response_model=Message,
dependencies=[Depends(get_current_user)],
)
async def put_report(device_id: str, request: Request, store: DeviceStoreDep) -> Any:
"""A device says what it has: its board, its screen, its ports.
Only the device itself, through its own credential, which ``_device_may``
holds to its own id. The report replaces the one before it, and the flows
are validated again, since a device node's ports are checked against it.
The first report of a touch screen makes the device touch friendly, as
the switch would have been set by hand. Later ones leave the setting to
whoever changed it since.
"""
device: DeviceDef | None = getattr(request.state, "device", None)
if device is None or device.id != device_id:
raise HTTPException(
status_code=403, detail="Only the device itself reports what it has"
)
raw = bytearray()
async for chunk in request.stream():
raw += chunk
if len(raw) > REPORT_MAX:
raise HTTPException(
status_code=413,
detail=f"A report is at most {REPORT_MAX // 1024} KB",
)
try:
report = DeviceReport.model_validate_json(bytes(raw))
except ValidationError as exc:
raise HTTPException(
status_code=422,
detail=exc.errors(
include_url=False, include_input=False, include_context=False
),
)
first = await run_in_threadpool(store.report, device_id, report)
if first and report.display and report.display.touch and not device.touch:
with suppress(StaleVersion, DeviceNotFound):
await run_in_threadpool(
store.write,
device.model_copy(update={"touch": True}),
device.version,
)
_changed()
await _recheck(request)
return Message(message=f"{len(report.ports)} ports reported")
@router.put(
"/{device_id}",
response_model=DeviceDef,
@@ -53,6 +53,8 @@ def _epoch(column: Any) -> ColumnElement[int]:
class HealthSummary(BaseModel):
status: str
problems: list[str]
#: Worth a look, but not faults: they leave ``status`` as it is.
warnings: list[str] = []
flows: dict[str, int]
nodes: dict[str, int]
queue: dict[str, Any]
@@ -241,9 +243,24 @@ async def read_summary(request: Request, controller: FlowControllerDep) -> Any:
if invalid:
problems.append(f"{len(invalid)} flow(s) cannot run: {', '.join(invalid)}")
# Working, if not as well as they should: a device switched off, a send
# queue full. A warning, held back by the same floor as `unhealthy`.
degraded = controller.unhealthy_nodes(health="degraded")
warnings = (
[
f"{len(degraded)} node(s) degraded: "
+ ", ".join(
sorted(f"{e.id} ({e.health_detail or 'no detail'})" for e in degraded)
)
]
if degraded
else []
)
return HealthSummary(
status="degraded" if problems else "ok",
problems=problems,
warnings=warnings,
flows={
"total": len(names),
# What the engine will actually act on. Enabled is not enough:
@@ -267,6 +284,7 @@ async def read_summary(request: Request, controller: FlowControllerDep) -> Any:
"total": len(entries),
"error": len(errored),
"unhealthy": len(unhealthy),
"degraded": len(degraded),
"failing": len(failing),
},
queue=queue,
+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",
+2 -2
View File
@@ -182,8 +182,8 @@ async def list_shared_nodes() -> Any:
@mcp.tool()
async def list_devices() -> Any:
"""Every paired screen or board, the dashboards it shows and whether it is
connected."""
"""Every paired screen or board, the dashboards it shows, whether it is
connected and what it reports having."""
return await _call("GET", "/devices/")
+92
View File
@@ -803,6 +803,98 @@ def test_a_port_wired_twice_or_an_unknown_device_is_an_issue(
client.delete(f"{FLOWS}/{flow}", headers=superuser_token_headers)
#: What a P4 panel reports: a GPIO pin either way, its backlight and touch.
REPORT = {
"schema": 1,
"platform": "esp32p4",
"board": "p4",
"firmware": "0.1.2",
"display": {"w": 1024, "h": 600, "shape": "rect", "touch": True},
"ports": [
{"port": "backlight", "direction": "out", "dtype": "int"},
{"port": "touch", "direction": "in", "dtype": "bool"},
{
"port": "gpio.4",
"direction": "in",
"modes": ["in", "out"],
"dtype": "bool",
"config": {"type": "object", "properties": {"invert": {"type": "boolean"}}},
},
],
"features": {"display": True},
# A newer firmware's key, which this version drops.
"battery": {"level": 80},
}
def test_a_device_reports_what_it_has(
client: TestClient, superuser_token_headers: dict[str, str]
) -> None:
"""Only from its own credential, at most 16 KB, the whole report replaced.
The device node's ports are checked against it from then on.
"""
_panels(
client,
superuser_token_headers,
{"panels": [{"id": "porch_io"}, {"id": "other"}]},
)
_publish_flow(client, superuser_token_headers, "porch", [PORCH_NODE])
device = _pair(client, superuser_token_headers, "porch_io")
other = _pair(client, superuser_token_headers, "other")
url = f"{PREFIX}/porch_io/report"
def issues() -> set[tuple[str | None, bool]]:
found = client.get(f"{FLOWS}/porch", headers=superuser_token_headers).json()
return {
(i["port"], i["advisory"])
for i in found["issues"]
if i["code"] == "device_port"
}
# Without a report the ports are the device's business.
assert issues() == set()
assert (
client.put(url, headers=superuser_token_headers, json=REPORT).status_code == 403
)
assert client.put(url, headers=other, json=REPORT).status_code == 403
padded = {**REPORT, "firmware": "x" * 20_000}
assert client.put(url, headers=device, json=padded).status_code == 413
assert (
client.put(url, headers=device, json={**REPORT, "schema": 2}).status_code == 422
)
put = client.put(url, headers=device, json=REPORT)
assert put.status_code == 200, put.text
listed = client.get(f"{PREFIX}/", headers=superuser_token_headers).json()
stored = next(d for d in listed["data"] if d["id"] == "porch_io")
assert stored["reported_at"]
assert "battery" not in stored["report"]
assert stored["report"]["ports"][2]["modes"] == ["in", "out"]
# A touch screen's first report makes the device touch friendly.
assert stored["touch"] is True
# What the device reads stays what it was: no report, no presence.
read = client.get(f"{PREFIX}/porch_io", headers=device).json()
assert "report" not in read and read["touch"] is True
# gpio.4 is wired as in, which its modes allow, and the backlight as int.
assert issues() == set()
# A report replaces the one before: the backlight gone, gpio.4 out only.
gpio = {"port": "gpio.4", "direction": "out", "dtype": "bool"}
assert (
client.put(url, headers=device, json={**REPORT, "ports": [gpio]}).status_code
== 200
)
assert issues() == {("gpio.4", False), ("backlight", True)}
client.delete(f"{FLOWS}/porch", headers=superuser_token_headers)
# The other tests wire porch_io without a report.
store = app.state.device_store
with store._state_lock:
states = store._read_states()
states["porch_io"].report = None
store._write_states(states)
def test_publishing_a_flow_with_device_nodes_tells_the_devices(
client: TestClient, superuser_token_headers: dict[str, str]
) -> None:
+28 -5
View File
@@ -1,4 +1,4 @@
"""A device node: never run by the engine, down while its device is away."""
"""A device node: never run by the engine, degraded while its device is away."""
import asyncio
from pathlib import Path
@@ -67,7 +67,7 @@ def test_the_engine_never_runs_a_device_node(tmp_path: Path) -> None:
asyncio.run(controller._teardown())
def test_a_device_node_is_down_while_its_device_is_away(tmp_path: Path) -> None:
def test_a_device_node_is_degraded_while_its_device_is_away(tmp_path: Path) -> None:
controller = _controller(tmp_path)
async def scenario() -> list[tuple[str, str | None]]:
@@ -85,10 +85,33 @@ def test_a_device_node_is_down_while_its_device_is_away(tmp_path: Path) -> None:
presence.closed("wall")
return seen
# Degraded, not down: a switched-off panel is a warning, never a fault.
assert asyncio.run(scenario()) == [
("down", "Offline"),
("degraded", "Offline"),
("ok", None),
("down", "Offline"),
("down", "Offline"),
("degraded", "Offline"),
("degraded", "Offline"),
]
presence.forget("wall")
def test_an_offline_device_is_a_warning_not_a_fault(tmp_path: Path) -> None:
controller = _controller(tmp_path)
async def scenario() -> list:
await controller.reload()
# Past the floor that holds back a device rebooting.
controller.loaded["hall.panel"].health_since -= 3600
found = (
controller.unhealthy_nodes(),
[e.id for e in controller.unhealthy_nodes(health="degraded")],
[(i.code, i.advisory) for i in controller.flow_issues("hall")],
)
await controller._teardown()
return list(found)
assert asyncio.run(scenario()) == [
[],
["hall.panel"],
[("node_degraded", True)],
]