PQ SDK Tooling¶

pq-tools is the container with the PQ adapter tools. It is distributed through the PQ Installer under the name PQ SDK Tooling. Every command names its tool first:

Tool	Command	Purpose
Documentation	`docs`	Prepares and checks the documentation pages for an adapter
Lab	`lab`	Runs a built adapter image and records its trace for bring-up and certification (Lab rig)

The documentation tool reads the adapter's YAML declaration and generates the structured pages from it. It does not implement the adapter, interpret the device protocol, or discover how the hardware must be connected. Those facts come from the adapter author and the device documentation.

Get the tool through the PQ Installer¶

The online installer downloads the selected pq-tools image from repo.protequ.com and loads it into Docker. The installer currently deploys the PQ core services as well, because it installs the complete PQ stack.

Requirements¶

64-bit Windows 10 22H2 or Windows 11 23H2;
administrator permissions;
internet access to repo.protequ.com;
Docker Desktop, or permission for the installer to install it;
at least 10 GB of free disk space.

Steps¶

Download pq-installer-online-v<version>-windows.exe from the PQ releases.
If Windows blocks the file, open its Properties, select Unblock, and click OK.
Start the installer and approve the administrator prompt.
Read and accept the PQ agreement.
Complete the Core Services screen.
On Adapters & Integrations, search for PQ SDK Tooling or pq-tools.
Select the tooling image, choose its version, and click INSTALL.
Wait for completion. If Docker Desktop asks you to sign in, choose Skip and keep Docker Desktop running.

Confirm that Docker has the selected image:

docker image ls repo.protequ.com/pq/pq-tools

Use the tag shown by this command below. If the installer selected latest, use latest.

After the installer is available, no separate request is needed. If the tooling does not appear in the catalog, check the internet connection and refresh the catalog.

What the tool can do¶

The tool works on one adapter bundle mounted at /work:

Operation	Command	Result
Create the coverage skeleton	`--scaffold`	Writes `capabilities-coverage.yaml` with the required catalog rows and preserves existing answers
Fill unassessed coverage	`--assess`	Asks the questions in the terminal and writes the answers
Check coverage	`--validate`	Fails when coverage is incomplete or malformed
Render a preview	`--preview /work/preview`	Writes the generated adapter pages for a reading pass

The generated pages include the adapter identity, configuration, device tree, capabilities, events, access model, certification, notes, and the connection page when those inputs exist. The device tree and its relationships come from adapter-registration.yaml; do not write a second table for them.

certification.yaml is read-only input for this tool. A separate certification runner must create it from executed acceptance tests on the real device. pq-tools does not generate certification verdicts. Do not create or edit them by hand. If the runner is not available or no certification run exists, omit the file; the tool then omits the certification page.

The page that contains device-specific installation knowledge is docs/connection.md. Fill that page using the connection guide template. The template asks how the device connects, what the installer sets, how to enter those values in PQ, and how to recognize and fix a failed connection.

The tool does not require protocol documentation. Keep protocol and API material in the repository or documentation system where you normally maintain it. Do not copy it into the adapter bundle or source code.

Typical command sequence¶

Run these commands from the directory that contains the bundle:

# Add all required capability rows without changing existing answers.
docker run --rm -v "$PWD:/work" \
  repo.protequ.com/pq/pq-tools:<tag> docs \
  --bundle /work --scaffold

# Answer remaining capability questions in the terminal.
docker run --rm -it -v "$PWD:/work" \
  repo.protequ.com/pq/pq-tools:<tag> docs \
  --bundle /work --assess

# Check that every required row is complete and valid.
docker run --rm -v "$PWD:/work" \
  repo.protequ.com/pq/pq-tools:<tag> docs \
  --bundle /work --validate

# Render the pages into /work/preview.
docker run --rm -v "$PWD:/work" \
  repo.protequ.com/pq/pq-tools:<tag> docs \
  --bundle /work --preview /work/preview

Replace <tag> with the version selected in the installer. On PowerShell, use ${PWD} when Docker does not expand $PWD correctly. The --assess command needs an interactive terminal.

What the tool needs¶

For bundle mode, prepare the bundle in the adapter project. The YAML declaration describes the adapter and drives the generated pages. You can create, assess, validate, and preview the bundle yourself:

<YourAdapter>/
├── adapter-registration.yaml
├── capabilities-coverage.yaml
└── docs/
    ├── connection.md
    └── notes.md                 optional

The minimum bundle contains adapter-registration.yaml, capabilities-coverage.yaml, and docs/connection.md. Add access-model.yaml, certification.yaml, or docs/notes.md only when you have the corresponding input and the delivery explicitly includes it. certification.yaml is supplied by a separate certification runner; never create it by hand.

The adapter documentation contains the registration schema, access model schema, and connection guide template. Use these files directly from the checked-out documentation; no template request is needed.

If another person must publish the image, give them the checked bundle and the image build instructions. This handover does not require protocol documents in the bundle or a separate protocol review.

For the complete handover checklist, see Writing and delivering adapter documentation.

Lab rig¶

The lab runs your adapter inside the pq-tools container and records everything the adapter does into one trace: its protocol log, the events and statuses it publishes, the commands it receives, and its CPU and memory use. The lab does not build the adapter. It runs the image you already built with docker build, so the files under test are exactly the files you deliver.

What the lab needs¶

your adapter image, built and present in the local Docker;
a PQ box in development mode. Development mode publishes NATS and opens the Internal API on the front door; see Local adapter development setup, Step 1. It is allowed only on a development machine;
the NATS user and password of that box, and its address;
an API key for your PQ user;
network access from the container to the device.

Get an API key¶

The lab reads the device tree and sends commands through the PQ API as your user.

Sign in to PQ at https://<box-address>/.
Open https://<box-address>/swagger.
Run POST /Api/ApiKey.
Copy the key value from the response. PQ shows it only once.

DELETE /Api/ApiKey revokes all your keys.

Start the rig¶

The rig is one container that stays up for the whole session. Start it once from your adapter folder:

docker run -d --init --name pq-lab -v "$PWD:/work" \
  --mount type=image,source=<your-adapter-image>,target=/adapter \
  -e Mq__Host=<box-address>:4222 -e Mq__User=<nats-user> -e Mq__Password=<nats-password> \
  -e PQ_SERVER_URL=https://<box-address> -e PQ_API_KEY=<api-key> \
  repo.protequ.com/pq/pq-tools:<tag> lab rig

Use host.docker.internal as <box-address> when the PQ box runs on the same computer. The lab accepts the box's own certificate without a CA setup.

--mount type=image makes the adapter image readable at /adapter. Docker marks it as an experimental feature and prints a warning; the mount works regardless.
If your Docker does not support the image mount, copy the files out instead. Run docker create --name adapter-files <your-adapter-image>, then docker cp adapter-files:/app ./adapter-app, then docker rm adapter-files. Replace the --mount line with -v "$PWD/adapter-app:/adapter/app:ro".
--init cleans up the processes the lab ends.

Run lab commands¶

Send every lab command into the running rig with docker exec:

# Start the adapter from the image. /adapter/app is the image's /app folder.
docker exec pq-lab lab run --adapter /adapter/app

# Check that the adapter is alive.
docker exec pq-lab lab status

# Read the recorded trace.
docker exec pq-lab lab trace query --kind event

# Stop the adapter at the end of the session.
docker exec pq-lab lab teardown

The trace and session files are written to .pq-lab/ in your adapter folder, so you can read them on your computer. Remove the rig with docker rm -f pq-lab.

Common lab commands¶

Prefix each command with docker exec pq-lab.

Command	What it does
`lab run --adapter /adapter/app`	Starts the adapter and starts recording its trace
`lab status`	Shows whether the adapter is running
`lab tree`	Prints the adapter's device tree from the PQ server, with node ids and commands
`lab trace query --kind event`	Lists recorded events. Other kinds: `status`, `command`, `raw`, `decoded`, `log`
`lab mark`	Prints the current end of the trace, as a starting point for `lab expect`
`lab expect --since <offset> --expect "kind=event" --timeout 15`	Waits until a matching record appears after the mark, or fails after the timeout
`lab command <device-id> <command-id>`	Sends a command to a device through the PQ server, as the PQ app does
`lab state <device-id>`	Prints the latest status of a device
`lab restart`	Restarts the adapter from the same image files
`lab teardown`	Stops the adapter at the end of the session

A typical check of one command:

docker exec pq-lab lab mark                       # prints an offset, for example 48213
docker exec pq-lab lab command <door-id> pq.command.access.open
docker exec pq-lab lab expect --since 48213 --expect "kind=event" --timeout 15

To test a new build, rebuild your adapter image, remove the rig, and start it again. The image mount reads the image only when the container starts.