From 15a3c2ce621d94028f6cd56e6422da3db80f21e0 Mon Sep 17 00:00:00 2001 From: stroblme Date: Wed, 26 Aug 2026 21:43:59 +0200 Subject: [PATCH] Document how a connector handles a device that decides its own ports An undeclared key fails the whole reading, so a connector whose ports vary by model has to narrow what it publishes to what was bound. Names the idiom and the once-not-per-poll rule for saying a declared port is missing. --- docs/reference/connector-contract.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/reference/connector-contract.md b/docs/reference/connector-contract.md index 9142961..7f3a348 100644 --- a/docs/reference/connector-contract.md +++ b/docs/reference/connector-contract.md @@ -97,6 +97,27 @@ optional `interval`. output port publishes at most every *n* seconds, an input port wakes its node at most that often. A connector should poll at the rate the device is comfortable with and leave delivery rates to whoever wires it up. +- A key no port declares is an error, and it fails the whole reading rather + than the one value — a mistyped metric name is how a training curve goes + missing. + +### When the device decides what the ports are + +A connector for a device whose readings vary by model — which components a +relay has, which entities were flashed onto a board — cannot know its ports in +advance, and returning everything the device reports would fail on the first +value nobody bound. Narrow the reading to the ports that were declared: + +```python +declared = {spec.port for spec in self.output_ports if spec.name} +return {port: value for port, value in reading.items() if port in declared} +``` + +`spec.port` is the local, unqualified name and stays that way for the node's +whole life, so the set can be taken fresh each time. Say something in the log +when a declared port is not one the device has — once, not once per poll: from +the canvas a renamed entity and a typo look the same, and both leave a port +silent forever. ## Polling