IPBuilding Gateway

Open replacement for the proprietary IPBox hub on the IPBuilding field bus. The gateway speaks UDP/1001 to relay, dimmer, and input modules on 10.10.1.x and exposes a northbound API (WebSocket /ws + REST /api/v1/ on port 8080) for any client — Home Assistant, MQTT, Matter, scripts. Scenes and automations live in your home automation platform, not in the gateway.

Deployment variants

The same gateway code runs in three shapes. Pick what fits your hardware:

Variant	Platform	Status
HA add-on (Docker, Supervisor-managed)	Home Assistant OS / Supervised	Primary, fully supported
Standalone Docker container (docker run / python -m gateway)	Linux — Raspberry Pi, NAS, VPS, any x86/ARM box	Same Python code, no Supervisor
ESP32 firmware (C++ / ESP-IDF)	ESP32 + W5500 Ethernet	Future — protocol-level POC (ARCHITECTURE.md §3)

For the HA add-on variant, follow the Installation steps below. For standalone or ESP32, see ARCHITECTURE.md §3 and the add-on documentation.

If Home Assistant is your client: the companion is required

The gateway only speaks the northbound protocol (WebSocket /ws + REST /api/v1/ on port 8080). To get lights, switches, sensors, and buttons in HA you also need the companion integration IPBuilding Gateway Companion App at the latest release of both. This holds for any deployment variant — HA add-on, standalone Docker container, or ESP32 firmware — as long as HA is the client that turns protocol messages into entities.

You install	You get
Gateway only	Gateway service on port 8080 — no HA entities
Gateway + companion	Lights, switches, sensors, buttons, dashboards

If you don't use Home Assistant at all (pure MQTT, custom scripts, …) the companion is irrelevant — talk to the northbound API directly.

Features

• UDP/1001 field bus — IP0200PoE relays, IP0300PoE dimmers, IP1100PoE inputs
• Northbound API — WebSocket /ws and REST /api/v1/ on port 8080
• Runtime discovery — ARP monitor and optional init-sweep; updates devices.json
• Supervisor discovery — registers with HA when the companion is installed (no manual host/port on HA OS)
• Health reporting — /api/v1/status and watchdog /health
• Optional IPBox REST shim on :30200 for migration only (off by default)

This add-on does not implement IPBox scenes, moods, or button→relay rules.

Requirements {#prerequisites}

• Home Assistant OS or Supervised
• IPBuilding Gateway Companion App companion — any recent release; see the companion releases page
• IPBuilding modules reachable on 10.10.1.x with HA using a source IP on that segment (host_network: true — see network notes)
• A valid devices.json in the add-on config folder

Installation

1. Companion (required — do this first or in parallel)

Adds custom repository markminnoye/ha-ipbuilding-gateway in HACS, then download IPBuilding Gateway Companion App and restart HA. Full steps: companion README

2. Add-on repository

Or: Settings → Add-ons → Add-on Store → ⋮ → Repositories

https://github.com/markminnoye/IPBuilding-Gateway

3. Install and configure the add-on

Add-on Store → IPBuilding Gateway → Install

Then follow add-on documentation for:

• copying or generating devices.json
• add-on options (hub IP, discovery, timeouts)
• starting the add-on and reading logs

4. Link in Home Assistant

With the add-on running and the companion installed:

Settings → Devices & Services → Discovered → IPBuilding Gateway Companion App → Add

Manual host/port remains available if discovery is blocked; see the companion configuration guide.

Security

• host_network: true — the add-on joins your host network stack; use only on a trusted LAN segment. See Home Assistant app security.
• The gateway API has no authentication and uses plain HTTP/WebSocket. Do not expose port 8080 outside your network.

Documentation

Document	Audience
Add-on DOCS	Operators — install, options, network, troubleshooting
Companion README	HA integration — entities, automations, dashboard
Changelog	Release notes for this add-on
Architecture	Migration from IPBox, deployment variants
API reference	Northbound REST/WebSocket
Developer library	Python gateway/ package (not the add-on UI)

Add-on manifest and Supervisor integration follow the official Home Assistant Apps developer docs.

Support

• Add-on / gateway: IPBuilding-Gateway issues
• Companion / HA entities: ha-ipbuilding-gateway issues

When reporting problems, state both versions (add-on and companion) from GET /api/v1/status or the add-on info panel.

Migrating from IPBox / HA-IPBuilding

The legacy HA-IPBuilding integration uses the IPBox REST API (:30200). This stack uses the open gateway plus companion on :8080. See ARCHITECTURE.md for the cutover path.