Skip to content

Getting Started

Welcome! This guide helps you get oriented before diving into the full documentation.

What is PQ?

PQ is a cloud-native physical access control platform. It manages doors, readers, inputs, outputs, and other security hardware through a unified event-driven architecture.

Your job as an adapter developer is to bridge your device to PQ: translate device events into PQ domain events, and route PQ commands back to the device.

What You Build vs. What the Framework Provides

You provide Framework provides
Vendor SDK / protocol knowledge NATS message bus integration
Device communication logic Event routing to server
Event translation Command dispatch and routing
Command execution on device Access sync engine (diff, ordering, hashing)
Thing configuration in YAML Persistence (LiteDB)
Connection retry and lifecycle management
UI and ABAC engine integration

The framework generates a significant portion of the boilerplate from your YAML configuration — Thing classes, function state machines, typed command and event classes.

How an Adapter Fits In

PQ Server (API, UI, ABAC)
        │
        │  NATS (events, commands, status)
        │
  Adapter Process
        │  ├─ Your protocol/SDK code
        │  └─ Generated framework scaffolding
        │
  Physical Device(s)

Where to Start

Follow these steps in order. Each step names the page with the details.

Step 1 — Understand the architecture (15 min) Read 00-overview.md. Pay attention to the Thing hierarchy, Functions, and the YAML-to-code generation workflow.

Step 2 — Prepare your development machine

  1. Install PQ with the PQ Installer. On Adapters & Integrations, also select PQ SDK Tooling (pq-tools). See PQ SDK Tooling.
  2. Switch the PQ box to development mode. Development mode publishes NATS and opens the Internal API, so an adapter that runs outside the box can connect. See Local adapter development setup. Use development mode only on a development machine, never on a customer installation.

Step 3 — Pick your adapter family (10 min) Browse archetypes/ and find the shape closest to your device's protocol (TCP, HTTP streaming, gRPC, native SDK, CCTV).

Step 4 — Build the minimal adapter (10 min) Follow tutorials/00-hello-world.md. You will have a compiling, running adapter skeleton before reading anything else.

Step 5 — Implement and debug from your IDE Implement the device protocol with 01-step-by-step.md and the patterns. Run the adapter from Visual Studio or Rider against your development box, as Local adapter development setup describes.

Step 6 — Build the image and test it on the device

  1. Build the adapter image. See Image anatomy.
  2. Start the lab rig with that image. The lab runs the image, records the adapter's protocol log, events and statuses, and sends commands through PQ. See Lab rig.
  3. Check each capability on the real device against the acceptance tests. The lab commands mark, command and expect show whether the expected event arrives.

Step 7 — Write the documentation

  1. Fill docs/connection.md with the connection guide template.
  2. Create the coverage file and answer the questions: docker run --rm -it -v "$PWD:/work" repo.protequ.com/pq/pq-tools:<tag> docs --bundle /work --assess.
  3. Check the bundle with --validate and read the generated pages with --preview /work/preview.

The full procedure is in Writing and delivering adapter documentation and PQ SDK Tooling.

Step 8 — Deliver Add the documentation bundle to the image, label it, and publish it. See Publishing an adapter and the definition of done.

What a Finished Adapter Looks Like

Pq.Adapter.Vendor.Product/
├─ adapter-registration.yaml     # Device types, functions, commands — you write this
├─ access-model.yaml             # Credential sync entities (optional)
├─ Communication/
│   ├─ Protocol.cs               # Device communication — always required
│   └─ Transport.cs              # Custom transport — only for gRPC/serial/SDK processes
├─ Devices/
│   ├─ ControllerDevice.cs       # Extend generated Thing classes
│   └─ DoorDevice.cs
└─ Commands/
    └─ DoorCommands.cs           # Command handler methods

Typical adapter: 8–15 files, most of the complexity in Protocol.cs and event translation logic. Generated code handles the rest.

Key Reference Documents

Keep these open while implementing:

When You Get Stuck

  1. Check 03-troubleshooting.md — covers the most common build, connection, and event issues
  2. Search the concepts/ directory for the specific area (commands, events, address resolution, …)
  3. Check patterns/ for the nearest matching implementation pattern