🇩🇪 Deutsche Version

Open building automation platform — connects KNX, Modbus, MQTT, Home Assistant, and more

open bridge connects different building technology protocols into a unified system. All values can be monitored via a web interface, linked through logic, and forwarded via MQTT — without proprietary configuration files.

1. Quick start — Proxmox LXC
2. Configuration
3. How does open bridge work?
4. Data points
5. Bindings
6. Search
7. Adapters
8. History
9. Change log (RingBuffer)
10. Backup & Restore
11. System status
12. Log viewer
13. Live connection (WebSocket)
14. Logic editor
15. Adapter configuration
16. MQTT topics
17. Data types
18. Settings
19. Helper scripts
20. Visualization (Visu)

• Floor plan and system diagram widget

1. Development

• Local development with PyCharm
• Local Git Hooks (Pre-Push Gate)

The LXC template contains a complete Ubuntu 26.04 system with open bridge server and starts the service automatically when the container boots.

Step 1 — Download the template

1. On the releases page, expand the assets and right-click to copy the URL of the .tar.zst file for your architecture:

   

2. In the Proxmox web interface, navigate to Datacenter → Storage → local → CT Templates.

3. Click Download from URL.

4. Paste the copied URL and click Query URL.

5. If not already enabled, activate Advanced in the bottom right of the popup.

6. Select SHA256 as the hash algorithm.

7. On the releases page, copy the checksum of the desired template from the Checksums section using the copy button:

   

   Note: If you copy the checksum directly from the column next to the asset, remove the SHA256: prefix, as Proxmox does not expect it!

8. Back in the Proxmox web interface, paste the copied hash into the Checksum field.

9. It should now look like this, for example:

   

10. Click Download.

Step 2 — Create the container

1. In the Proxmox menu, select Create CT.
2. Choose the just-downloaded openbridgeserver-lxc_… as the template.
3. Configure hostname, password, CPU, RAM, and network as needed — recommended: at least 512 MB RAM.
4. Start the container.

Step 3 — Access

Default credentials: username admin, password admin ⚠️ Change the password immediately after first login (Settings → Password).

Security configuration (required):

# Set environment variables in /etc/obs.env, e.g.:
OBS_MQTT__HOST=192.168.1.10
# Set automatically in the LXC template on first boot (random, per container).
# Only set if you need a manual override:
OBS_SECURITY__JWT_SECRET=<at-least-32-random-characters>

# Restart the service
systemctl restart obs

Configuration is loaded in this order (higher = precedence):

1. Environment variables (OBS_<SECTION>__<KEY>)
2. config.yaml (path via OBS_CONFIG, default: ./config.yaml)
3. Built-in defaults

server:
  host: 0.0.0.0               # Network interface
  port: 8080                  # Web interface port
  log_level: INFO             # Log level: DEBUG|INFO|WARNING|ERROR

mqtt:
  host: localhost             # Internal Mosquitto broker
  port: 1883
  username: null              # Credentials for internal broker
  password: null

database:
  path: /data/obs.db      # Database file

message_archive:
  path: /data/archives/messages.sqlite3  # separate archive DB for message archives

ringbuffer:
  storage: file               # Change log: file-only
  max_entries: 10000          # Maximum number of entries
  max_file_size_bytes: null   # Optional: hard file size limit for the ring buffer
  max_age: null               # Optional: maximum entry age in seconds

security:
  jwt_secret: changeme        # Session key — must be changed!
  jwt_expire_minutes: 1440    # Session duration (default: 24 hours)
  # Optional override for the private/internal URL target allowlist.
  # Default: OBS_SECRET_FILE_DIR/url-target-allowlist.yaml when OBS_SECRET_FILE_DIR is set,
  # otherwise secrets/url-target-allowlist.yaml next to the configured database.
  # url_target_allowlist_path: /data/secrets/url-target-allowlist.yaml

Note: The mqtt section refers to the internal Mosquitto broker. External MQTT brokers are set up as separate adapter instances (see MQTT adapter).

For support and failure scenarios, OBS ships an offline CLI that works directly on the SQLite configuration database and does not require the OBS HTTP server to be running.

In the LXC template, run the command inside the container:

obs-admin status
obs-admin db info
obs-admin adapters list
obs-admin adapters disable <instance-id-or-name>
obs-admin adapters enable <instance-id-or-name>
obs-admin bindings list --adapter <instance-id-or-name>
obs-admin bindings disable <binding-id>
obs-admin loglevel set DEBUG
obs-admin support-package create --output /tmp/obs-support.json

When upgrading an existing LXC container from a release that did not ship obs-admin, the first obs-update run may leave the command at /opt/obs/obs-admin without installing /usr/local/bin/obs-admin. In that case run /opt/obs/obs-admin ... directly or install the wrapper once with:

install -m 0755 /opt/obs/obs-admin /usr/local/bin/obs-admin

For Docker, run it on the host inside the OBS container, for example:

docker compose exec obs obs-admin status
docker compose exec obs obs-admin adapters disable <instance-id-or-name>

If the database is not at the normal configured path, pass it explicitly:

obs-admin --db /data/obs.db adapters list --json
obs-admin --db /data/obs.db db backup --output /var/backups/obs/

Write commands create a SQLite backup next to the database before changing data by default. The offline support package uses the same central sanitizing logic as the support API and redacts secrets, tokens, passwords, endpoints, and full filesystem paths.

Backend fetches from logic API-client nodes, iCalendar nodes, Pushover image_url attachments, the camera proxy, and the weather API block private/local network targets by default. Admins can allow deliberate internal targets under Settings → Security → URL Target Allowlist or by editing the YAML file configured through security.url_target_allowlist_path.

By default, the YAML file is written to OBS_SECRET_FILE_DIR/url-target-allowlist.yaml when OBS_SECRET_FILE_DIR is set. Otherwise OBS writes it to secrets/url-target-allowlist.yaml next to the configured database file. For private targets, use an IP address or CIDR entry, for example 192.168.1.23/32 for a single LAN camera or 10.38.113.0/24 for an internal subnet.

If a hostname such as internal.example resolves to a private IP address, allowlist the resolved IP or CIDR. A hostname-only entry does not override private-IP blocking and does not bypass DNS validation.

┌──────────────────────────────────────────────────────────────┐
│                        open bridge server                    │
│                                                              │
│  ┌─────────────────────┐  value change  ┌─────────────────┐  │
│  │   Adapter instances │ ─────────────▶ │   Event bus     │  │
│  │                     │ ◀── write      │  (distributes   │  │
│  │  KNX, Modbus,       │                │  to all subs)   │  │
│  │  MQTT, 1-Wire …     │                └──┬──────┬───────┘  │
│  └─────────────────────┘                   │      │          │
│                                     ┌──────▼─┐ ┌──▼──────┐   │
│                                     │ Value  │ │ History │   │
│                                     │ store  │ │ RingBuf │   │
│                                     │        │ │ MQTT    │   │
│                                     └────────┘ │ WS      │   │
│                                                └─────────┘   │
│                                                              │
│  ┌───────────────────────────────────────────────────────┐   │
│  │                  Logic editor                         │   │
│  │  Value change → run graph → write DataPoint           │   │
│  └───────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌───────────────────────────────────────────────────────┐   │
│  │                   REST API + WebSocket                │   │
│  └───────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

Core principles:

• Adapters read values from the building (KNX telegram, Modbus register, MQTT message, …) and report them to the event bus.
• The event bus distributes every value simultaneously to: the value store (current state), history, change log, MQTT broker, WebSocket clients, and the logic editor.
• The logic editor reacts to value changes, executes automation logic, and writes results back to data points.
• Protocol bridge: When a value is received via one protocol, open bridge server automatically writes it to all other linked protocols — without additional configuration.

A data point is the central object in open bridge server. Every physical or virtual value in the system — a temperature, a switch state, an energy meter — is a data point.

GET    /api/v1/datapoints?page=0&size=50       # List (paginated)
POST   /api/v1/datapoints                      # Create new
GET    /api/v1/datapoints/{id}                 # Load single (incl. current value)
PATCH  /api/v1/datapoints/{id}                 # Update
DELETE /api/v1/datapoints/{id}                 # Delete (also removes all bindings)
GET    /api/v1/datapoints/{id}/value           # Current value only

Fields:

# Create a temperature data point
curl -X POST http://localhost:8080/api/v1/datapoints \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Living room temperature",
    "data_type": "FLOAT",
    "unit": "°C",
    "tags": ["climate", "living-room"]
  }'

A binding connects a data point to an adapter instance and an address (e.g. KNX group address or Modbus register).

GET    /api/v1/datapoints/{id}/bindings
POST   /api/v1/datapoints/{id}/bindings
PATCH  /api/v1/datapoints/{id}/bindings/{binding_id}
DELETE /api/v1/datapoints/{id}/bindings/{binding_id}

Directions:

Value transformation (value_formula):

Optional: a formula applied to the value before it enters the system (SOURCE) or leaves it (DEST). The variable is always x.

{ "value_formula": "x / 10" }

Available functions: abs, round, min, max, and all math.* functions. Division by zero and invalid results are caught — the original value is preserved.

Note: round() uses mathematical rounding (0.5 → round up), not the "banker's rounding" common in programming.

Value mapping (value_map):

Optional: a table that maps raw values to other values — useful for enumerations or status texts.

{ "value_map": { "0": "Off", "1": "On", "2": "Standby" } }

The key is always a string (the raw value is converted internally). Matching first tries the exact key and then a case-insensitive key, so OFF matches a map entry like "off". If no matching entry exists, the original value is passed through unchanged. value_map is applied after value_formula.

Send filters (DEST/BOTH only, checked in order):

Example: KNX temperature → Modbus register

# 1. Create data point
DP_ID=$(curl -s -X POST http://localhost:8080/api/v1/datapoints \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Living room temperature","data_type":"FLOAT","unit":"°C"}' \
  | jq -r .id)

# 2. KNX binding (read from GA 1/2/3)
curl -X POST http://localhost:8080/api/v1/datapoints/$DP_ID/bindings \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"adapter_instance_id": "KNX-UUID", "direction": "SOURCE",
       "config": {"group_address": "1/2/3", "dpt_id": "DPT9.001"}}'

# 3. Modbus binding (write to register 100)
curl -X POST http://localhost:8080/api/v1/datapoints/$DP_ID/bindings \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"adapter_instance_id": "MODBUS-UUID", "direction": "DEST",
       "config": {"unit_id": 1, "register_type": "holding", "address": 100, "data_format": "float32"}}'

Server-side search across all data points. Never returns the entire dataset.

GET /api/v1/search?q=&tag=&type=&adapter=&page=0&size=50

Each adapter type can run in multiple independent instances. All instances are managed via the web interface or the API.

Adapter configuration is done entirely through the web interface — all fields are dynamically rendered from the JSON schema of the respective adapter. Password fields appear masked. Changes take effect immediately without restart.

GET    /api/v1/adapters/instances              # All instances with status
POST   /api/v1/adapters/instances              # Create new instance
PATCH  /api/v1/adapters/instances/{id}         # Change configuration + reconnect
DELETE /api/v1/adapters/instances/{id}         # Stop + delete
POST   /api/v1/adapters/instances/{id}/restart # Reconnect
POST   /api/v1/adapters/instances/{id}/test    # Test connection

GET    /api/v1/adapters/{type}/schema          # JSON schema for instance configuration
GET    /api/v1/adapters/{type}/binding-schema  # JSON schema for binding configuration

open bridge server supports two authentication methods:

POST   /api/v1/auth/login                              # Login → receive token
POST   /api/v1/auth/refresh                            # Refresh token

GET    /api/v1/auth/users                              # All users (admin only)
POST   /api/v1/auth/users                              # Create user (admin only)
DELETE /api/v1/auth/users/{username}                   # Delete user (admin only)
POST   /api/v1/auth/me/change-password                 # Change own password

POST   /api/v1/auth/apikeys                            # Create API key
DELETE /api/v1/auth/apikeys/{id}                       # Revoke API key

POST   /api/v1/auth/users/{username}/mqtt-password     # Set up MQTT access
DELETE /api/v1/auth/users/{username}/mqtt-password     # Remove MQTT access

MQTT access: The internal Mosquitto broker is password-protected. Each user can receive a separate MQTT account (independent of the login password) to connect directly to the broker.

Value history of a data point — raw or aggregated.

GET /api/v1/history/{id}?from=&to=&limit=
GET /api/v1/history/{id}/aggregate?fn=avg&interval=1h&from=&to=

Aggregation functions: avg (average), min, max, last

Time intervals: 1m, 5m, 15m, 30m, 1h, 6h, 12h, 1d

All timestamps follow the timezone configured in the settings.

Control recording: The record_history field on the data point controls whether values are written to the history. Data points with record_history: false are ignored by the history module. Management is done under Settings → History.

The RingBuffer stores the last N value changes as a log. In the web interface, the list updates immediately (without reloading), since new entries are transmitted live via the WebSocket connection.

GET  /api/v1/ringbuffer?q=&adapter=&from=&limit=   # Query entries
POST /api/v1/ringbuffer/query                       # v2 query DSL (filter groups + pagination + sorting)
POST /api/v1/ringbuffer/export/csv                  # CSV export of complete filtered result set
GET  /api/v1/ringbuffer/stats                       # Entry count, capacity
POST /api/v1/ringbuffer/config                      # Change file-only + capacity

The q parameter searches both the name and the ID of the data point.

POST /api/v1/ringbuffer/query uses a filter DSL with clear semantics:

• filters.adapters.any_of: OR within the adapter list.
• filters.values: type-aware value filters (eq/ne/gt/gte/lt/lte/between/contains/regex) matching data_type.
• filters.metadata: filterable snapshot metadata from DataPoint/Binding context (tags, adapter_types, group_addresses, topics, entity_ids, register_types, register_addresses).
• Filter groups (time, adapters, datapoints, values, metadata, q) are combined with AND.
• Time filters support open boundaries (from without to, to without from) and the combination of absolute bounds (from/to) plus relative offsets (from_relative_seconds/to_relative_seconds).
• Pagination via pagination.limit + pagination.offset, sorting via sort.field (id|ts) and sort.order (asc|desc).
• The versioned metadata model is documented in docs/ringbuffer-metadata-model-v1.md (metadata_version: 1).

POST /api/v1/ringbuffer/export/csv uses the same request body as /query, but always exports the complete filtered result set (UI pagination is ignored).

CSV columns: id, ts, datapoint_id, name, topic, old_value_json, new_value_json, source_adapter, quality, metadata_version, metadata_json.

Complete configuration backup and restore. Existing entries are updated, missing ones are created.

GET  /api/v1/config/export    # Download backup file (JSON)
POST /api/v1/config/import    # Restore backup file

The backup contains: all data points, bindings, adapter instances, and KNX group addresses.

Import KNX project file:

POST /api/v1/knxproj/import   # Upload .knxproj file (multipart/form-data)
GET  /api/v1/knxproj/ga       # Show imported group addresses
DELETE /api/v1/knxproj/ga     # Delete all imported addresses

After import, the group addresses appear as search suggestions in the binding form.

GET /api/v1/system/health      # Check reachability (no login required)
GET /api/v1/system/adapters    # Adapter status + binding count
GET /api/v1/system/datatypes   # All available data types
GET /api/v1/system/settings    # Read system settings (e.g. timezone)
PUT /api/v1/system/settings    # Update system settings

GET /api/v1/adapters/knx/dpts  # List all registered KNX DPT types

The log viewer shows recent application log messages in real time. The admin GUI displays the last 500 entries and streams new entries live via WebSocket.

GET /api/v1/system/logs?limit=N   # Recent log entries (newest first, max 500)
GET /api/v1/system/log-level      # Read current log level (admin only)
PUT /api/v1/system/log-level      # Change log level at runtime (admin only)

Log entries have the following fields:

The log level can be changed at runtime without a restart (admin only). The buffer holds the last 500 entries and is not persisted across restarts.

Via the WebSocket connection, value changes and new RingBuffer entries are immediately transmitted to all connected browsers — no manual reload required.

WS /api/v1/ws?token={jwt}

Subscribe to data point:

{"action": "subscribe", "datapoint_ids": ["uuid-1", "uuid-2"]}

Incoming value change:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "v": 21.4,
  "u": "°C",
  "t": "2026-03-27T10:23:41.123Z",
  "q": "good"
}

New RingBuffer entry (to all connections, without subscription):

{
  "action": "ringbuffer_entry",
  "entry": {
    "ts": "2026-03-27T10:23:41.123Z",
    "datapoint_id": "550e8400-...",
    "name": "Living room temperature",
    "new_value": 21.4,
    "old_value": 21.1,
    "quality": "good",
    "source_adapter": "KNX"
  }
}

Data quality (q):

The logic editor enables visual creation of automation rules — without programming knowledge. Blocks are placed on a canvas by drag & drop and connected with lines.

Flow:

1. A Read DP block monitors a data point.
2. When the value changes, open bridge server executes the entire graph.
3. Blocks are evaluated in sequence.
4. A Write DP block writes the result back — this automatically triggers all adapters, MQTT, history, and the RingBuffer.
5. The Trigger block fires the graph on a schedule (e.g. daily at 07:00).

The graph can also be started manually via the ▶ Run button.

States (hysteresis, memory, statistics, operating hours, min/max tracker, consumption counter) are stored in the database and survive a restart.

Direct feedback loops are validated in the editor and blocked when saving or connecting nodes. Use a Memory block as an explicit tick boundary for controlled feedback: it outputs the value stored from the previous graph run and stores the current input for the next run.

Decision and Mapping share the same condition operators: equals, not equal, greater/less than, greater/less or equal, range, text comparison, contains, starts with, ends with, and regular expression.

Both DataPoint blocks have three tabs: Connection, Transformation, and Filter. A dot (•) appears in the tab when something is active.

Optional formula applied to the value. Variable: x

Predefined templates (examples):

The Trigger block fires graphs on a schedule. Three input methods that synchronize with each other:

1. Templates — over 30 predefined schedules in 4 groups (minute intervals, hour intervals, daily, weekly/monthly)

2. Visual editor — five fields: minute / hour / day / month / weekday

3. Direct entry — standard cron expression

0 7 * * *         → daily at 07:00
*/15 * * * *      → every 15 minutes
0 8 * * 1-5       → weekdays at 08:00
0 6,18 * * *      → daily at 06:00 and 18:00

For reference: crontab.guru (link directly in the configuration panel)

In all formula fields (Read DP, Write DP, formula block, binding transformation):

• Variable x = the incoming value (always passed as a number)
• No import needed — all functions directly available
• round() uses mathematical rounding (0.5 → round up)

Practical examples:

Formula block (inputs a and b):

a * 2 + b              # Double input a, add b
max(a, b)              # Take the larger of the two values
round((a + b) / 2, 1)  # Average, 1 decimal place
abs(a - b)             # Absolute difference

Additionally, an output transformation can be configured — a second formula (variable x) applied to the calculated result.

The logic engine converts values automatically:

Connections between different block types always work.

Shows calculated intermediate values directly on the blocks — live and automatically.

1. Open the graph
2. Click the 🔍 Debug button in the toolbar
3. Each block shows a yellow band with its current output values
4. The display updates automatically after each execution (value change, schedule, manual start)

Instance configuration — basic parameters:

Connection types:

KNX IP Secure — keyfile mode (recommended)

The easiest way for KNX IP Secure is to import the .knxkeys file from ETS:

1. In ETS: Security → Export key backup → save .knxkeys file
2. In open bridge server: Settings → Adapter → Edit KNX instance → Upload keyfile
3. Enter keyfile password — open bridge server shows all available tunnels with PA, user ID, and number of secured group addresses
4. Select desired tunnel → individual_address is set automatically
5. Set connection_type to tunneling_secure (or routing_secure)

KNX IP Secure — manual mode (only when no keyfile is available):

For tunneling_secure:

For routing_secure:

Note: If knxkeys_file_path and knxkeys_password are set, they take precedence over the manual fields. All password fields are masked in the web interface.

Keyfile API (for custom integrations):

POST /api/v1/knx/keyfile   # Upload .knxkeys, return tunnel list
DELETE /api/v1/knx/keyfile/{file_id}  # Delete keyfile

Response from the upload endpoint:

{
  "file_id": "uuid",
  "file_path": "/data/knxkeys/uuid.knxkeys",
  "project_name": "My KNX project",
  "tunnels": [
    { "individual_address": "1.1.100", "host": "1.1.50", "user_id": 2, "secure_ga_count": 15 },
    { "individual_address": "1.1.101", "host": "1.1.50", "user_id": 3, "secure_ga_count": 15 }
  ],
  "backbone": null
}

Binding configuration:

Supported DPTs:

open bridge server supports over 85 KNX data types. The complete list is available via GET /api/v1/adapters/knx/dpts.

DPT 1 — 1-bit Boolean

DPT 2 — 2-bit controlled value

DPT 3 — 4-bit relative control value

DPT 4 — 1-byte character

DPT 5 — 8-bit unsigned

DPT 6 — 8-bit signed

DPT 7 — 16-bit unsigned

DPT 8 — 16-bit signed

DPT 9 — 2-byte KNX floating point (EIS5)

DPT 10, 11 — Time and date

DPT 12, 13 — 32-bit integer

DPT 14 — 32-bit IEEE-754 floating point (physical quantities)

DPT 16, 17, 18, 19 — Text, scenes, date/time

DPT 20 — 1-byte enum/mode

DPT 29 — 64-bit integer (Smart Metering)

DPT 219, 240 — Special types

Note for KNX dimmers: Create two separate bindings — one DEST for the write address, one SOURCE for the feedback address.

Instance configuration:

Binding configuration:

Practical tip: Most controllers (Siemens, Beckhoff …) use big/big. If the value is obviously wrong, try changing word_order to little first.

Same binding configuration as TCP. Additional instance fields: port (e.g. /dev/ttyUSB0), baudrate, parity, stopbits, bytesize, timeout.

Connects to an external owserver process (the OWFS 1-Wire bus server) via the pyownet TCP protocol — the same "OBS is a client of an external service" relationship the MQTT adapter has with Mosquitto. owserver abstracts USB busmasters (plain USB sticks such as the DS9490, the ElabNET PBM's multiple channels) and the native kernel 1-Wire bus behind one uniform device tree, so this adapter never needs to know which hardware is actually behind it.

owserver itself is not started by OBS — it ships as an opt-in Docker Compose sidecar (owserver service, COMPOSE_PROFILES=onewire, see .env.example) or, on the Proxmox LXC template, as a systemd service gated behind the OBS_ONEWIRE__USB_ALL / OBS_ONEWIRE__PBM_DEVICES variables in /etc/obs.env.

Instance configuration:

Binding configuration:

The binding form's Scan button browses the connected owserver instance for attached sensors and their available properties, and lets you assign a persistent alias label per ROM-ID.

Note: This replaces the legacy sysfs-based adapter (w1_path, /sys/bus/w1/devices), which required OBS to run on the same host as the Linux kernel's w1 driver. Via owserver, OBS can talk to any 1-Wire busmaster — including on a different host or inside its own container — and also supports the ElabNET PBM (ProfessionalBusMaster), not just the plain kernel driver.

A 1-Wire busmaster's device node isn't guaranteed to stay the same across reboots or when other USB/serial devices are attached:

• A plain USB busmaster (e.g. DS9490) enumerates as /dev/bus/usb/<bus>/<device> — bus/device numbers can shift.
• The ElabNET PBM enumerates as an FTDI serial device (/dev/ttyUSB0, /dev/ttyUSB1, …) — the trailing number depends on plug-in order.

For the PBM, /dev/serial/by-id/usb-FTDI_... is usually already a stable path that udev creates automatically for any serial device exposing a serial number, without a custom rule. Plain USB busmasters don't get an equivalent automatic alias, so a custom udev rule is the reliable fix there — and it also works for the PBM if you'd rather have a short, self-chosen name than the long by-id path.

1. Identify the device

First check with lsusb what hardware is actually attached — not every host has both types at once. A plain USB busmaster (DS9490R, DS1490F, …) reports the fixed VID:PID 04fa:2490; the ElabNET PBM shows up as an FTDI chip under vendor 0403 (the exact product ID depends on the specific FTDI chip variant):

lsusb

Example output for a host with both device types attached:

$ lsusb
Bus 001 Device 004: ID 04fa:2490 Dallas Semiconductor DS1490F 2-in-1 Fob, 1-Wire adapter
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)

Then read vendor/product/serial attributes for whichever device is actually present — for the busmaster via the /dev/bus/usb/<bus>/<device> path from lsusb (here 001/004), for the PBM either directly via the /dev/serial/by-id/... entry udev already created (ls /dev/serial/by-id/) or via the assigned /dev/ttyUSB*:

# plain USB busmaster (only if lsusb listed a 04fa:2490 device above)
udevadm info -a -n /dev/bus/usb/001/004 | grep -E 'idVendor|idProduct|serial' | head -5

# PBM / serial device (only if lsusb listed a 0403:xxxx device above)
udevadm info -a -n /dev/serial/by-id/usb-ElabNET_PBM01-USB_BM_00000401-if00-port0 | grep -E 'idVendor|idProduct|serial' | head -5

Example output for the devices above:

$ udevadm info -a -n /dev/bus/usb/001/004 | grep -E 'idVendor|idProduct|serial' | head -5
    ATTR{idProduct}=="2490"
    ATTR{idVendor}=="04fa"
    ATTRS{idProduct}=="0024"
    ATTRS{idVendor}=="8087"

$ ls /dev/serial/by-id/
usb-ElabNET_PBM01-USB_BM_00000401-if00-port0

$ udevadm info -a -n /dev/serial/by-id/usb-ElabNET_PBM01-USB_BM_00000401-if00-port0 | grep -E 'idVendor|idProduct|serial' | head -5
    SUBSYSTEMS=="usb-serial"
    ATTRS{idProduct}=="6015"
    ATTRS{idVendor}=="0403"
    ATTRS{serial}=="BM_00000401"
    ATTRS{idProduct}=="0024"

Two things stand out here:

• The busmaster reports no serial attribute at all — this fob-style device simply doesn't expose a serial number. The rule can therefore only key on idVendor/idProduct; with more than one identical busmaster on the same host that's not enough to tell them apart (match on the fixed KERNELS/bus path instead in that case).
• For the PBM, udevadm info -a shows the plural ATTRS{...}, not ATTR{...} — idVendor/idProduct/serial sit on the parent USB device in the sysfs chain, not on the tty device itself. The udev rule must therefore also use ATTRS{} (a parent device's attribute) rather than ATTR{} (the matched device's own attribute) — otherwise the rule never fires, since the tty device doesn't carry those attributes at all. For the plain USB busmaster (SUBSYSTEM=="usb" matches the busmaster device itself), ATTR{} is correct.

Prefer serial when the device reports one — unlike idVendor/idProduct, it's unique per physical unit, so the rule still matches the right device if you ever plug in a second one of the same model.

Note: The ElabNET PBM already gets a stable /dev/serial/by-id/... symlink out of the box (see the ls /dev/serial/by-id/ output above) — for this device, a custom udev rule usually isn't needed at all; pointing OBS_ONEWIRE__PBM_DEVICES at that path directly is enough. A custom rule only pays off here for a shorter, self-chosen name.

2. Write the rule

Create the rule on the Proxmox host (not inside the container — Proxmox resolves the LXC passthrough mount against the host's device tree before the container starts, so the symlink must already exist there), e.g. /etc/udev/rules.d/99-onewire.rules:

# DS9490/DS1490F plain USB busmaster — idVendor/idProduct are fixed for this device family
# (04fa:2490). No serial condition, since this device reports no serial number (see step 1) —
# with more than one identical busmaster, this match alone won't tell them apart.
SUBSYSTEM=="usb", ATTR{idVendor}=="04fa", ATTR{idProduct}=="2490", SYMLINK+="onewire-busmaster"

# ElabNET PBM (FTDI) — ATTRS{} rather than ATTR{}, since idVendor/idProduct/serial sit
# on the parent USB device, not on the tty device itself (see note above). idProduct varies
# by FTDI chip variant (6015 here) — check your own variant and serial with lsusb/udevadm.
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", ATTRS{serial}=="BM_00000401", SYMLINK+="onewire-pbm"

Only carry over the block(s) for hardware that's actually attached (see the lsusb output from step 1) — a rule for hardware that isn't present is harmless but obviously creates no symlink.

Apply it without rebooting, then confirm the symlink appeared:

udevadm control --reload-rules && udevadm trigger
ls -l /dev/onewire-busmaster /dev/onewire-pbm

3. Point the passthrough at the stable path

• Proxmox LXC (/etc/pve/lxc/<CTID>.conf) — both lines are required, the mount entry alone is not sufficient (see AGENTS.MD's "owserver (1-Wire) in the LXC template" section):

  lxc.mount.entry: /dev/onewire-busmaster dev/onewire-busmaster none bind,optional,create=file
  lxc.cgroup2.devices.allow: c 189:* rwm
  

  The major number (189 for USB device nodes) can vary — check the real one with ls -l /dev/onewire-busmaster. Then set the LXC's OBS_ONEWIRE__* variables in /etc/obs.env to the symlinked name instead of the raw device path.

• Docker Compose (docker-compose.yml):

  devices:
    - "/dev/onewire-busmaster:/dev/onewire-busmaster"
    - "/dev/onewire-pbm:/dev/ttyUSB0"

Connects to an external MQTT broker (separate from the internal Mosquitto).

Instance configuration: host, port, username, password

Binding configuration:

Sends notifications when a linked data point changes and the binding condition is fulfilled. The binding uses the read direction (SOURCE) because the adapter observes value changes and turns them into messages.

Supported providers:

Binding configuration:

Message placeholders: ###DP### = value, ###DPU### = unit, ###DPN### = data point name, ###DPI### = data point ID, ###TS### = timestamp.

Note: Signal is not offered by the MESSAGE adapter for now because it would require operating a separate Signal gateway service.

Connects open bridge server bidirectionally to a Home Assistant instance. Receives state changes in real time via WebSocket (state_changed events) and writes values via the HA REST API (service calls).

Instance configuration:

Binding configuration:

Text states such as "on"/"off", "true"/"false" are automatically converted to Boolean values. Numeric texts are passed as numbers.

Connects open bridge server bidirectionally to an ioBroker instance via Socket.IO. Values are initially read when binding and then updated in real time via stateChange events; write commands are sent to ioBroker via setState.

Instance configuration:

Binding configuration:

Text states such as "on"/"off", "true"/"false" are automatically converted to Boolean values. Numeric texts are passed as numbers. For separate status and command objects, state_id can point to the status and command_state_id to the command state.

Development and review notes on the current implementation are in docs/iobroker-adapter.md.

Polls OID values from SNMP-capable devices (SNMPv1, v2c, v3) and writes values via SNMP SET. Each binding configures its own host and OID — no persistent TCP connection, stateless UDP per request.

Instance configuration:

Binding configuration:

Note: pysnmp must be installed (pip install pysnmp). If the library is not present, the adapter starts without error but cannot poll.

Replays historical switch states during absence so the building appears occupied. When the simulation is active, the adapter queries the history database for the past N days and fires each historical event at the corresponding time today.

Instance configuration:

Binding configuration:

Note: Only SOURCE bindings are valid — the adapter replays historical values but does not accept writes. DEST/BOTH bindings are skipped with a warning.

Generates time-controlled events without external hardware — for time-of-day or sun-position based automations, holiday and vacation logic.

Instance configuration:

Binding configuration:

Holiday modes:

open bridge server uses two parallel topic strategies:

Message format (dp/{uuid}/value):

{ "v": 21.4, "u": "°C", "t": "2026-03-27T10:23:41.123Z", "q": "good" }

Set a value:

mosquitto_pub -t "dp/550e8400-.../set" -m '{"v": 22.5}'

Type conversions are lossless where possible — on loss, a message is written to the log.

Settings are accessible via the web interface (⚙ in the sidebar).

General:

• Timezone — all timestamps in the interface are displayed in this timezone (history, RingBuffer, history search, astro block)
• Import KNX project file — upload ETS project file (.knxproj) to use group addresses as search suggestions in the binding form

History: Overview of all data points with history recording. Data points with disabled recording (record_history: false) are shown first. Toggle recording per data point.

Password: Change own login password

Users (administrators only): Create, delete users, manage MQTT access

API keys: Create and revoke keys for connecting external systems

Backup: Download or restore complete configuration

The script scripts/Import-EtsGaCsv.ps1 reads an ETS GA CSV export and automatically creates a DataPoint with matching type and unit for each group address. It then creates a binding to the specified KNX adapter instance.

Prerequisites: PowerShell 5.1 or newer, reachable open bridge server instance, valid API key.

Parameters:

CSV format (ETS 5/6 GA export):

The export is done in ETS via Export group address list → CSV. The script automatically recognizes semicolon and comma separators as well as German and English column headers.

"Group name";"Address";"Central";"Unfiltered";"Description";"Comment";"DatapointType";"Security"
"Living room temperature";"1/1/1";"";"";"";"";DPST-9-1;Auto
"Living room brightness";"1/1/2";"";"";"";"";DPST-9-2;Auto
"Roller shutter GF up/down";"1/2/1";"";"";"";"";DPST-1-8;Auto

DPT specifications in DPST-X-Y format (main and subtype) or DPT-X (main type only) are automatically converted to open bridge server format (DPT9.001) and the appropriate data type (FLOAT, INTEGER, BOOLEAN, STRING) and unit are set. If the DPT is missing, FLOAT without unit is used.

Example:

.\scripts\Import-EtsGaCsv.ps1 `
    -Url    http://localhost:8080 `
    -ApiKey obs_abc123 `
    -File   C:\Projects\GA_Export.csv `
    -Adapter "KNX/IP"

ETS 5 (ANSI encoding):

.\scripts\Import-EtsGaCsv.ps1 `
    -Url      http://localhost:8080 `
    -ApiKey   obs_abc123 `
    -File     C:\Projects\GA_Export.csv `
    -Adapter  "KNX/IP" `
    -Encoding Default

With error log:

.\scripts\Import-EtsGaCsv.ps1 `
    -Url     http://localhost:8080 `
    -ApiKey  obs_abc123 `
    -File    C:\Projects\GA_Export.csv `
    -Adapter "KNX/IP" `
    -LogFile C:\Projects\import_errors.log

The script continues on individual errors. At the end, the number of successfully imported, skipped (rows without address), and failed GAs is displayed.

The Visu interface is a separate single-page app (accessible at /visu/), with which interactive control panels — called Visu pages — can be created and displayed in full-screen mode on displays or tablets. Each page consists of freely positionable widgets that display or control data points.

The floor plan widget allows you to embed a building floor plan or system diagram as an interactive background in a Visu page. Areas (polygons) can be defined, labeled, and linked to actions on the image — as well as mini-widgets placed directly on the plan.

In the widget's configuration panel, an image can be uploaded (SVG, PNG, or JPG). The image is stored as a Base64 data URL directly in the config JSON — no separate upload endpoint needed. For files over 2 MB, a notice appears; SVG is recommended for floor plans as it scales without loss.

The rotation of the image can be set in 90° steps (0° / 90° / 180° / 270°), to use landscape graphics directly in portrait mode.

With the polygon tool in the full-screen canvas, areas can be drawn on the floor plan:

1. Click New area in the configuration panel — the full-screen canvas opens.
2. Click on the canvas to set corner points of the polygon.
3. Close the polygon by clicking the first point again or pressing Enter.

Each area can be assigned the following properties:

When Navigation is selected as the click action, a page selector opens. The selected Visu page is opened directly when clicking on the area in the viewer. This allows, for example, floor plans to be linked — clicking a room opens a detail view.

Any mini-widgets (e.g. switch, temperature display, dimmer) can be positioned directly on the floor plan:

1. Click Add mini-widget in the configuration panel and choose the widget type.
2. Click Position — the full-screen canvas opens.
3. Drag the mini-widget to the desired position on the plan via drag & drop.

For each mini-widget, the following can be configured:

Mini-widgets do not rotate when the floor plan is rotated — they always remain upright and are correctly positioned over the floor plan based on image coordinates.

The repository contains preconfigured PyCharm run configurations in the .run/ directory. After opening the project, they are available directly in the run selector.

1. Create Python environment

cd openbridgeserver
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt -r requirements_dev.txt

In PyCharm under Settings → Project → Python Interpreter, select the interpreter .venv/bin/python.

2. Install frontend dependencies

cd gui && npm install

3. Create configuration file

cp config.example.yaml config.yaml

Adjust the following values in config.yaml:

mqtt:
  username: obs
  password: change-this-mqtt-service-password   # must match .env

database:
  path: /absolute/path/to/project/data/obs.db  # local path, not /data

mosquitto:
  passwd_file: /absolute/path/to/project/data/mosquitto/passwd
  reload_pid: null
  reload_command: null
  service_username: obs
  service_password: change-this-mqtt-service-password

4. Set up environment variables

cp .env.example .env   # if not already present

The .env file contains the MQTT password with which the Docker Mosquitto is initialized — this value must match mqtt.password in config.yaml.

Prerequisite: Docker Desktop must be running (for the Mosquitto broker).

Default credentials: admin / admin

# Unit and adapter tests only (no Docker needed)
pytest tests/unit/ tests/adapters/

# All tests incl. integration (Docker must be running)
pytest tests/

# Check only (same behavior as CI job)
./tools/lint.sh --check

# With auto-fix
./tools/lint.sh --fix

See tools/README.md for full documentation of build-local.sh — commands, options, and the local Docker image naming schema.

Versioned hooks live in .githooks/. To activate them in a clone, set core.hooksPath once:

./tools/setup-git-hooks.sh

On each git push, the hook runs:

• ./tools/check-i18n-hardcoded-strings.sh
• python3 -m ruff check .
• python3 -m ruff format . --check
• pytest tests/ -v --cov=obs --cov-report=xml --cov-report=term --junitxml="${TMPDIR:-/tmp}/openbridge-pre-push-junit.xml"

The i18n gate checks changed GUI/Visu files for hardcoded user-facing strings, locale key parity, and raw translation expressions such as $t(...) rendered as template text.

To bypass once:

git push --no-verify

GUI translations are managed via hosted.weblate.org. The source language is German (de.json); the community translates on Weblate.

Prerequisite: wlc is already included in requirements_dev.txt and is installed during the normal setup.

Set up credentials — either in ~/.config/weblate:

[weblate]
url = https://hosted.weblate.org/api/

[keys]
https://hosted.weblate.org/api/ = <your-api-key>

or via environment variables: WLC_URL / WLC_KEY.

Upload source strings (after changes to de.json):

wlc push gui-admin       # Admin GUI  (gui/src/locales/de.json)
wlc push frontend-visu   # Visu SPA   (frontend/src/locales/de.json)

Download translations (after community translations on Weblate):

wlc pull gui-admin
wlc pull frontend-visu

The Weblate project configuration is in .weblate in the project root directory.

# Mosquitto (temporary)
docker run -d -p 1883:1883 eclipse-mosquitto:2

# Configuration
cp config.example.yaml config.yaml

# Server with automatic restart on code changes
uvicorn obs.main:create_app --factory --reload --host 0.0.0.0 --port 8080

The database is updated automatically — each new version adds missing tables and columns without losing existing data. Current version: V21.

We'd like to use Weblate to support language translations. As soon as this is set up, contributions would be very much welcome.

MIT — free and open source.