Integration capabilities: panel, editor and pairing

Integrations are managed from the "Integrations" screen — an equipment panel that lives in the same visual language as the device registry and does not introduce a new interface. It answers three questions: which transports the platform knows, which integrations are described, and whether something is silent.

What the panel shows

• Summary — the number of integrations, devices, devices online and devices without a link.
• Integration cards — transport, direction, vendors, device count by availability, last update, error reason and dependencies. The cards are sorted by weight: whatever is silent sits at the top.
• Filter "All / Online / With a problem".
• Transport catalog — MQTT, Matter, Zigbee, Modbus, KNX · BACnet, ONVIF, REST, with the liveness of each.

The row separates two things that usually get confused: status is the state of the device, link is the liveness of the transport. An unknown protocol leaves the transport as null instead of making the platform guess.

How it is edited

Since the end of October 2026 the row is not only reported but also editable: a label, a note, a transport chosen from the catalog and a map of the public settings. Through GET/POST/DELETE /api/integrations with the config permission; a POST with an id in the body replaces or creates. The merge behaves like the server's: a value replaces, null deletes the key. The profile screen and the editor light up only when the session has the permission — the decision is always the server's, and the refusal is a 403.

What actually pairs

The step wizard goes through the four steps network kind → device → test request → result against POST /api/pair (again the config permission):

• Matter pairs for real — the bridge goes through the controller, picks the OnOff endpoint and writes matter-devices.json; from there the device enters the registry with origin "integration" (response 201).
• Modbus, KNX, ONVIF and HTTP are leads — the "test request" step is a real TCP connect with a 3 s timeout (tcpProbe), and the device waits for its driver (response 200 with paired: false).

Server-side validation is clean and mirrored in the kiosk: id as a slug, a name up to 80 characters, an 11-digit code for the pairable transports, host and a port within 1–65535 for the test steps. A refusal is a 400 with human-readable details fields, and a missing Matter controller is a 503 with a reason. The 11-digit code is entered on the tablet, used once and does not remain in state, in the log or in localStorage; on failure the server replaces it with … before the record is written.

Secrets

Labels and public settings are edited from the tablet, but addresses and secrets are not entered on the kiosk — a secret typed on the living-room tablet is not a secret. Integration settings are stored on the server in bridge/integrations.json with an atomic write; GET shows the remaining fields, and a stored secret is never returned. The editor hints when the server is hiding a value.

What is pending

• The real drivers behind the catalog — Modbus, KNX, Zigbee and ONVIF/RTSP (support level by transport).
• Entering secrets through the interface without them ever reaching the tablet.
• A voice assistant and the floor plan are not part of this layer.

See also the installer guide for the order in which this is done on site, and Integrations and protocols for the description of the levels per transport.