StatusPoll¶

Overview¶

Periodic device status polling. When a device does not push status changes on its own (no event stream, or an unreliable one), the framework calls the adapter on a fixed interval so it can read the current state of the device and update the relevant Things. The adapter implements the read-and-publish logic; the framework owns the scheduling.

Added in: PQ Framework 2.0
Namespace: Pq.Adapters.Framework

When to Use¶

Devices with no asynchronous event/notification channel (poll-only protocols)
Request/response protocols where state must be queried explicitly
Supplementing an event stream with a periodic reconciliation read
Detecting silent state changes (e.g., a relay toggled outside the system)

If the device reliably pushes every state change, prefer the event stream and skip this function.

States¶

None. StatusPoll does not expose status states of its own. The adapter updates the states of other functions (Door, Reader, Input, etc.) with the polled values.

Actions¶

None. Polling is driven by the framework scheduler on the configured interval; there are no action methods to invoke.

Properties¶

Property	Type	Default	Range	Description
`poll_interval_seconds`	`int`	`30`	`5`–`3600`	Seconds between status polls

YAML Example¶

device_types:
  - type_id: AccessController
    name: "Access Control Panel"
    functions:
      StatusPoll:
        poll_interval_seconds: 15
      ConnectionBase:
      Door:
      Input:

Code Usage¶

The framework invokes a status-poll handler on the configured interval. Write a static PollStatus method — the source generator detects it by signature and wires it to the scheduler automatically. Read the device state, then commit the resolved values to the relevant Things in batch updates.

internal static class ControllerStatusPolling
{
    // detected by the source generator; invoked by the framework on each poll tick
    public static async Task PollStatus(
        AccessController controller,                   // Thing type - first param (required)
        IThingQuery.IDescendants<ControllerDoor> doors, // DI - descendant query
        Protocol protocol,                              // DI - adapter service
        CancellationToken ct)                           // must be last
    {
        var snapshot = await protocol.ReadStatus(ct);

        foreach (var door in doors)
        {
            var batch = door.StatusBatch();
            batch.Set(snapshot.IsSecured(door.Address) ? DoorState.Secured : DoorState.Unsecured);
            await batch.Commit(ct); // one publish for all changes
        }
    }
}

Detection contract — the generator matches only this shape: public static, returns Task, named PollStatus, first parameter is the Thing type that owns the poll, CancellationToken last, remaining parameters DI-resolved. An instance method, or a first parameter that is not a Thing type, is silently not detected — the code compiles, but the framework never polls. Verify wiring by checking that <ThingType>.StatusPoll.g.cs appears in .GeneratedFiles/.

Notes¶

Framework-Scheduled: You do not start your own timer; the framework calls the handler at poll_interval_seconds
Cover All States: Poll every status-bearing function the protocol exposes for each polled element — a partition has armed/alarm/trouble, a door has its own set (see RULE-051 in compliance rules)
Batch Updates: Collect all polled values per Thing and commit them together to minimize message traffic
Snapshot Semantics: Commit scopes to exactly the functions you called Set(...) on; Set(state) selects its function from the state enum's type. Functions you did not set are left untouched — siblings are never cleared
Connection Lifecycle: The scheduler polls only connected Things; no manual online guard is needed
Interval Trade-off: Shorter intervals detect changes faster but increase device and network load; choose per device capacity
Reconciliation: Even with an event stream, a slow poll can correct missed or dropped events