Comm¶

Overview¶

Communication monitoring for field bus sub-nodes. Tracks the link health of a child node hanging off a shared bus (RS-485, RS-232, multidrop loop, or similar) and propagates online/offline transitions down to the node's own children.

Use Comm for sub-nodes on a bus that share a single physical transport managed by a parent controller. For the top-level device that owns the transport itself, use the ConnectionBase function instead.

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

When to Use¶

RS-485 / multidrop bus nodes (expansion boards, door controllers, I/O modules)
Daughter modules addressed over a shared serial or field bus
Any child node whose reachability depends on a parent's transport
Devices where a single cable fault should mark a whole branch offline

Do NOT use for:

The top-level device that owns the network/serial connection (use ConnectionBase)
Application-level data sync status (use the relevant synchronization function)

States¶

State	Status String	Description
`Online`	`pq.state.connection.online`	Node is reachable on the bus and responding
`Offline`	`pq.state.connection.offline`	Node communication lost (no response on the bus)

Actions¶

Disconnected(timestamp)

Description: Node communication lost (bus timeout, cable fault, address not responding)
Target State: Offline
Events: pq.event.technical.communication.lost
Usage: Polling the node times out, the bus reports a fault, or the node stops acknowledging

Reconnected(timestamp)

Description: Node communication restored
Target State: Online
Events: pq.event.technical.communication.restored
Usage: The node resumes responding on the bus after a fault

Properties¶

None — adapter-specific. Define any monitoring parameters (e.g., poll timeout, retry count) as properties in adapter-registration.yaml if your device needs them.

YAML Example¶

device_types:
  - type_id: BusController
    name: "Field Bus Controller"
    functions:
      ConnectionBase:        # owns the physical transport
    properties:
      bus_poll_interval_ms:
        type: "int"
        default: 500
        description: "Interval between bus polls"

  - type_id: BusNode
    name: "Bus Sub-Node"
    functions:
      Comm:                  # link health on the shared bus
    properties:
      node_address:
        type: "int"
        range: [1, 255]
        description: "Address of this node on the bus"

Code Usage¶

public class BusNodeThing : Thing
{
    public CommFunction Comm { get; }

    public async Task HandlePollResult(NodePollResult result, CancellationToken ct)
    {
        if (result.Responded)
        {
            await Comm.Reconnected(DeviceTimestamp.UtcNow);
        }
        else
        {
            // bus timeout or cable fault on this address
            await Comm.Disconnected(DeviceTimestamp.UtcNow);
        }
    }
}

Notes¶

Child Propagation: When a node goes Offline, the framework propagates the offline condition to that node's children so an entire branch reflects the fault.
Bus vs Device: Comm describes a node behind a transport; ConnectionBase describes the device that owns the transport. A controller typically has ConnectionBase while each board it polls has Comm.
Restoration Event: Unlike many functions, Reconnected() does publish an event (pq.event.technical.communication.restored).
Polling vs Push: Most bus nodes are monitored by parent polling; call Disconnected/Reconnected from the poll loop based on whether the node acknowledges.