Installing the KNX Bridge Agent

The bridge is the on-prem piece that watches the local KNXnet/IP gateway and forwards telegrams to the KNX Clarity cloud. It runs as a long-lived Docker container; one bridge per project.

This page is the install guide for the person putting the box next to the gateway. For what the bridge shows you once it is running — and for provisioning the token below — see Live KNX bus telemetry.

What you need before you start

1. A Linux host on the same LAN as the KNXnet/IP gateway. A Raspberry Pi 4, a NUC, the customer's existing NAS — anything that runs Docker and Linux 22.04+. The gateway and the host have to be reachable from each other on UDP/3671 (or whatever port the gateway is configured for).
2. Docker + Docker Compose installed. Both ship with most modern distros; if not, see docker.com/get-started.
3. A KNX Clarity Pro or Enterprise plan, with the project's telemetry consent toggle flipped on in the Live Bus tab.
4. A bridge token (kxb_…), provisioned from the same Live Bus tab. The token is shown exactly once on creation — copy it straight into your secret manager.
5. The cloud ingest URL for the stage you're connecting to — ops shares this per stage; it's the TelemetryIngestUrl value from the CloudFormation output.

Quick install

1. Clone the bridge source (or get the tarball from your operator):

   git clone https://github.com/<your-fork>/knx-project-cloud.git
   cd knx-project-cloud/bridge

2. Copy the example compose file:

   cp docker-compose.example.yml docker-compose.yml

3. Open docker-compose.yml and fill in the four required env vars:

   environment:
     KNX_GATEWAY_HOST: 192.168.1.50 # IP of your KNXnet/IP gateway
     KNX_GATEWAY_PORT: 3671 # only change if non-standard
     INGEST_URL: https://...lambda-url... # from your operator
     BRIDGE_TOKEN: kxb_... # from the Live Bus tab

4. Build and start:

   docker compose up -d --build

5. Verify it's healthy:

   curl http://localhost:8080/health
   # → {"ok":true,"knxConnected":true}

   In the KNX Clarity UI, the project's Live Bus tab now shows the bridge as active and (assuming the bus has any traffic) telegrams start flowing in within a few seconds.

Why host networking

The compose example sets network_mode: host. KNXnet/IP Tunneling sends the gateway a source UDP port that the gateway then uses for all replies; Docker's default bridge networking NATs that port and the protocol breaks. Host networking bypasses the NAT and keeps the container's port equal to the host's port — the bridge then binds HEALTH_PORT (default 8080) directly on the host.

Tuning

All configuration is via env vars. Defaults are fine for most installs; tune only when there's a specific reason.

Env var	Default	Notes
KNX_GATEWAY_HOST	—	Required. IP / hostname of the gateway.
KNX_GATEWAY_PORT	3671	KNXnet/IP Tunneling default.
INGEST_URL	—	Required. Cloud Function URL for the stage.
BRIDGE_TOKEN	—	Required. kxb_… token from Live Bus → Neue Brücke.
BATCH_MAX_SIZE	500	Cloud cap is 1000; lower batches lower latency.
BATCH_FLUSH_MS	1000	Lower for snappier UI; higher to coalesce a quiet bus.
QUEUE_MAX_SIZE	10000	Hard buffer cap. Older drops first if ingest is down.
HEALTH_PORT	8080	0 to disable. Move if it conflicts with another svc.
LOG_LEVEL	info	debug / info / warn / error.

Operations

• Restart: docker compose restart. Pending telegrams are flushed on graceful shutdown so a clean restart never loses bus activity.
• Logs: docker compose logs -f knx-bridge.
• Stats: curl http://localhost:8080/stats returns counters for total accepted / sent / dropped / failed-flush telegrams plus the KNX connection state. Wire it into your monitoring if you have one.
• Token rotation: revoke the old bridge in the Live Bus tab, provision a new one, swap BRIDGE_TOKEN in compose, restart. Revoked bridges keep their row + telegram history in the cloud.
• Disable telemetry: revoke all bridges first, then flip the consent toggle off. The cloud refuses the toggle while bridges are active so you don't end up with bridges that look healthy but silently get rejected by the ingest endpoint.

Troubleshooting

/health returns 503 with knxConnected: false

The bridge can't reach the gateway. Check from the host:

nc -uvz $KNX_GATEWAY_HOST 3671

If that fails, the gateway is unreachable on the network — verify the IP, the firewall, and that the gateway has Tunneling enabled (some installs ship with only Routing turned on, which the bridge does not yet support).

Logs show permanent ingest failure (status=401)

The bridge token has been revoked, expired, or the project's telemetry consent has been flipped off. Check the project in the UI and either re-enable consent / re-provision a token, or stop the bridge if telemetry shouldn't be running.

Logs show permanent ingest failure (status=403 tier_blocked)

The org's plan was downgraded below Pro. Either upgrade or stop the bridge.

Telegrams arrive in the cloud but decodedValue is missing

The bridge ships rawValueHex for every telegram and decodedValue only when it recognises the GA's datapoint type. v1 ships decoders for DPT 1.x (bool), 5.001 (percent), 9.x (float), 14.x (float), 16.x (string). Unknown DPTs render as raw hex in the UI; the cloud-side fuller decoder is a follow-up.

What v1 does not do

• Write to the bus. Cloud → bridge → bus is a separate project with a much higher security bar.
• Multiple gateways per bridge. Run one bridge per gateway.
• KNX Secure. Encrypted bus traffic is opaque to v1; the bridge silently drops it.