Skip to main content

Architecture

OmniBus is a single Node.js service with a Svelte web UI. Understanding three pieces — ports, adapters, and outputs — is enough to use it effectively.

The data path​

┌─────────────┐   serial bytes   ┌──────────────┐   parsed PDUs   ┌────────────┐
│ MS/TP / RTU │ ───────────────► │   Adapter    │ ───────────────►│ TCP server │
│   bus       │ ◄─────────────── │ (per port)   │ ◄───────────────│  (per port)│
└─────────────┘                  │              │                 └────────────┘
                                 │              │   parsed PDUs   ┌────────────┐
                                 │              │ ───────────────►│   MQTT     │
                                 │              │ ◄───────────────│  publisher │
                                 └──────────────┘                 └────────────┘
  • Each serial port has exactly one adapter — the protocol spoken on that line.
  • The adapter decodes bytes into structured PDUs and emits them to whichever outputs are enabled for that port.
  • Control flows the other way too: a TCP client, an MQTT command topic, or a REST call can drive the bus through the same adapter.

Components​

server.js          Express + WebSocket entry point on a single port. Handles
                   auth, the REST API, the static web UI, and the lifecycle of
                   every port's adapter and outputs.

Adapters           One per protocol (Modbus RTU, BACnet MS/TP, OSDP, M-Bus,
                   DNP3, Metasys N2, Jandy, Pentair, Modbus TCP client, raw).
                   Each owns a serial device (or a network client) and the
                   protocol logic for it.

Outputs            TCP server (per port), a shared MQTT publisher, REST
                   endpoints, and webhook delivery. The same parsed event can
                   go to all of them at once.

Web UI             A Svelte single-page app served from the same port. Auth
                   gate, dashboard, per-port config panels, MQTT settings,
                   system management, account/users.

A single port, single process​

OmniBus runs as one process listening on one HTTP(S) port. The web UI, the REST API, and the WebSocket live behind that port. Each enabled serial port also gets its own TCP server on a separate port (allocated from 9000 upward) for raw/Modbus/BACnet TCP clients. There is one shared MQTT client for the whole instance.

Where configuration lives​

  • data/config.json — a single JSON file holding the admin users, MQTT broker settings, and per-port configuration. Auto-created; on a production install it lives in /var/lib/omnibus.
  • data/audit.log — an append-only JSON-Lines audit trail of mutating actions.
  • TLS material — the internal Root CA and the server's leaf certificate also live in the data directory.

The data directory is the only stateful thing on the box. Back it up and you can rebuild the unit anywhere — see Backup & Restore.

Set OMNIBUS_DATA_DIR to relocate it (used for tests, multi-tenant hosts, or pointing at an external mount).

Resilience​

OmniBus is built to run unattended:

  • Each adapter has a watchdog: a serial port that errors or goes idle is reopened automatically, and a wedged adapter is restarted.
  • The systemd unit uses WatchdogSec — if the whole process hangs, systemd restarts it; Restart=always covers crashes and planned restarts.
  • On hosts that expose /dev/watchdog, the installer can enable the hardware watchdog so even a kernel hang recovers.

Branding / white-label​

Product name, vendor, support email, and product URL come from a single source and can be overridden per OEM SKU with environment variables (OMNIBUS_PRODUCT_NAME, OMNIBUS_VENDOR, OMNIBUS_SUPPORT_EMAIL, OMNIBUS_PRODUCT_URL) at boot.