Connection Guide (`docs/connection.md`)¶

Every adapter carries a docs/connection.md. It is the one page that gets a panel physically talking to Protequ: what to set on the equipment and on any converter between it and the network, and which of those values to carry into the adapter configuration.

This is the hardest part of a real installation to get right, and the easiest to lose. Someone knows what to set on the converter; someone else knows how to point Protequ at it; rarely the same person, and never a year later. This page is where that knowledge lives so the next installer does not rediscover it.

It is published verbatim as the adapter's first chapter, before the configuration page — an installer connects the box before adding it to the tree. Everything else on the adapter's pages is generated from YAML; this page is not, because how you wire and address a panel cannot be derived from a schema.

Where it lives¶

<adapter-project>/docs/connection.md. The documentation tool picks it up with no further wiring.

Skeleton¶

Copy this and fill it in. Keep the headings so every adapter reads the same way; drop a section only when it genuinely does not apply. Write for the installer standing at the panel, not for a developer.

# Connecting the hardware

## How Protequ reaches it

One line: over an IP network directly, over a serial line through a serial-to-Ethernet converter, or
through the manufacturer's own gateway or software.

## Before you start

What has to be in place first: cabling, a converter box, a firmware level, a licence or an account in
the manufacturer's software. List the things an installer must have on hand before the steps below make
sense.

## On the equipment

What to set on the panel itself or in the manufacturer's application. Numbered steps, each one action:

1. Enable the communication protocol / interface.
2. Set the address and port the panel listens on (or dials out to).
3. Generate or set the communication password, if the panel uses one.

State exact values where they are fixed (a port number, a baud rate, parity), and say where a value is
chosen by the installer (an IP address on the site network).

## In Protequ

Which of the values above go into which field when you add the adapter. Point at the configuration page
for the full field list; here, only the values that come from the steps above.

| You set on the equipment | You enter in Protequ |
|---|---|
| The panel's IP address and port | Host name or IP address, Port |
| The communication password | Password |

## Confirm it works

How to tell the link is up: run discovery and see the panel's parts appear, or watch the event log for
the first event the panel sends.

## If it does not connect

The two or three failures that actually happen, each with its fix:

- Nothing appears after discovery → check the port is open and the password matches.
- The panel connects then drops → check only one system is talking to it at a time.

The trivial case¶

Many IP panels have nothing to set beyond a reachable address. The page is still worth writing, because "there is nothing to configure on the box, point Protequ at its address and port" is itself the answer an installer is looking for. Keep the shape; let the sections be short.

# Connecting the hardware

## How Protequ reaches it

Over an IP network, directly. There is no converter and nothing to configure on the panel beyond giving
it an address the Protequ server can reach.

## In Protequ

Enter the panel's IP address and port on the configuration page. Nothing else is needed.

## Confirm it works

Run discovery; the panel's inputs and outputs appear in the tree within a few seconds.

Vocabulary¶

Same surface rules as every published adapter page:

Plain language. No framework types, no protocol frame names, no state or reason tokens. Say "the panel will not answer", not the name of the handshake that failed.
Name the hardware manufacturer and the converter model freely — this is your adapter's own page, and an installer needs to know exactly which box you mean.
Values an installer types or reads go inline as code: 10001, 9600 8N1, 192.168.1.50.

Screenshots¶

Keep the guide text-first: an exact value (Port 10001, 9600 8N1) survives a firmware redesign that moves every button, and a screenshot does not. Publishing image files alongside the page is a separate capability; until it lands, describe the screen in words and give the values.

Connection Guide (docs/connection.md)¶