Core Concepts¶

Before diving into adapter development, understand these fundamental concepts. They form the vocabulary we use throughout all documentation.

The Big Picture¶

An adapter sits between PQ system and physical devices:

graph TB
    subgraph PQ["PQ System"]
        Users["Users, Credentials, Rules"]
    end

    subgraph Adapter["Adapter"]
        Recv["Receives: Commands"]
        Send["Sends: Events, Status"]
        Proto["Protocol Layer"]
    end

    subgraph Device["Physical Devices"]
        HW["Controllers, Readers, Panels"]
    end

    PQ <-->|NATS Bus| Adapter
    Adapter <-->|Device Protocol| Device

Glossary¶

Quick reference for all terms. Click links for detailed explanations.

Term	One-line definition
Code Generation	How YAML + your C# become typed Things, commands, and events
Framework Architecture	Runtime model: Thing tree, lifecycle, messaging, capabilities
Communication Overview	Transport, Connection, Protocol architecture
Event	Something that happened (past tense)
Event Types	Classifying messages: audit events vs status vs control
Event Routing	Automatic event delivery with EventRouter
Event Intercepting	Intercepting events before publishing
Status	Current state right now (present tense)
Command	Request to do something (future tense)
Property	Configuration value on a device
Thing	Any device or logical unit in hierarchy
Function	Capability of a Thing (what it can do)
Protocol	How adapter talks to physical device
TCP Transport	Framework-provided TCP communication
Channel	Message pipeline in the framework
Thing Queries	Find Things and Functions in the tree
Persistent Storage	Data that survives adapter restart
Device Timestamps	Timezone-aware event timestamps
Card Wire Bit-Length	Carrying a card's per-channel bit width (CodeBits / BitLength / card_bits)

Message Flow Overview¶

Three types of messages flow through the system:

graph TB
    PQ["PQ System"]

    subgraph Adapter
        CMD["Command Handler"]
        STAT["Status Reporter"]
        EVT["Event Publisher"]
    end

    Device["Physical Device"]

    PQ -->|Command| CMD
    CMD -->|Execute| Device
    Device -->|State change| STAT
    STAT -->|Status| PQ
    Device -->|Event occurs| EVT
    EVT -->|Event| PQ

The Three Message Types¶

Type	Direction	Tense	Example
Command	PQ -> Adapter	Future	"Unlock door 5"
Event	Adapter -> PQ	Past	"Door 5 was opened by user John"
Status	Adapter -> PQ	Present	"Door 5 is currently unlocked"

Time Perspective¶

Understanding the time perspective helps distinguish message types:

Tense	Type	Examples
Past	Event	"Door opened", "Access granted", "Alarm triggered"
Present	Status	"Door is open", "Online", "Armed"
Future	Command	"Open door", "Unlock", "Arm zone"

Event: Reports what already happened. Cannot be undone. Historical record.

Status: Snapshot of current state. Changes over time. Can be queried.

Command: Request for future action. May succeed or fail. Needs response.

Device Hierarchy (Things)¶

Devices form a tree structure:

graph TB
    Root["DeviceAdapterBase (root)"]

    Root --> DC1["Door Controller 1"]
    Root --> DC2["Door Controller 2"]

    DC1 --> R1["Card Reader (entry)"]
    DC1 --> R2["Card Reader (exit)"]
    DC1 --> REX["REX Button"]

    DC2 --> R3["Card Reader"]
    DC2 --> BIO["Biometric Reader"]

Each node in this tree is a Thing. See Things for details.

Properties vs Status¶

Common confusion: what's the difference?

Aspect	Property	Status
Nature	Configuration	State
Changes	Rarely (user sets)	Often (device reports)
Examples	IP address, door name, unlock duration	Online/offline, door open/closed
Who sets	Administrator	Device itself
Persisted	Yes (in PQ database)	Sometimes (current snapshot)

Property: "Door unlock duration = 5 seconds"
          (configured once, doesn't change by itself)

Status:   "Door is currently open"
          (changes every time someone opens/closes door)

Reading Order¶

Foundations (read first): Code Generation and Framework Architecture — the mental model for what you write versus what the framework runs.

Then the vocabulary, in this order:

Communication Overview - Transport, Connection, Protocol (START HERE for communication)
Events - what happened
Event Types - classifying device messages
Event Routing - automatic event dispatch
Device Timestamps - timezone-aware timestamps (CRITICAL)
Status - current state
Commands - requests to act
Properties - configuration
Things - device hierarchy
Functions - device capabilities
Protocol - device communication details
TCP Transport - framework TCP support
Channels - message pipelines
Thing Queries - querying the device tree
Persistent Storage - data between restarts

After concepts, proceed to Event Mapping Guide for systematic vendor event translation.

Next: Events - Understanding device events