Aida Home Hub

Aida Home Hub is a local IoT hub that bridges consumer smart-home platforms — Alexa, Google Home, Apple Home / Siri, and Home Assistant — to MHT INX lighting and shade clusters. It runs on your home LAN, keeps a cluster registry, and translates voice or automation commands into INX cluster events.

Overview

This product provides:

• Cluster registry — named rooms/zones (must match Commissioner Cluster ID / device keyw)
• INX discovery — find nodes on the LAN (ARP prefilter + CoAP probe)
• Matter Bridge — expose clusters to Apple Home, Google Home, and Alexa (local control)
• Home Assistant — MQTT discovery for lights and covers
• Operator web UI — Clusters, Devices, and Integrations pages

:::note Not a building controller Home Hub is a voice and Home Assistant bridge. Day-to-day facility BMS, schedules, and BACnet belong on Aida Controller. Node serial assignment and Excel config push belong on Aida Commissioner. :::

How it works

Piece	Role
Cluster	Logical room or zone — one command dims or moves everything in that group
Matter Bridge	Exposes clusters as Matter devices for phone pairing
MQTT broker	Co-installed Mosquitto (MQTTS :8883) for HA discovery and INX events
Operator UI	Register clusters, discover devices, follow integration guides

Control is cluster-first: say “turn on Kitchen lights,” not a specific PoE node IP.

Prerequisites

Before installing Home Hub, ensure you have:

• Ubuntu or Debian host on the same LAN as the INX nodes (sudo available)
• INX nodes commissioned with Cluster IDs (see Aida Commissioner)
• Network path for CoAP (UDP 5683) and, for Matter, mDNS / same Wi‑Fi as phones
• Optional: Home Assistant on the same LAN if you plan to use MQTT discovery

Installation

The production installer installs Docker if needed, pulls images from Public ECR, and co-installs Mosquitto and Matterbridge by default.

curl -fsSL https://aida-platform.com/home-hub/install.sh | sudo bash

Pin a release:

RELEASE_TAG=v1.0.0 curl -fsSL https://aida-platform.com/home-hub/install.sh | sudo bash

After install

Item	Default
Install directory	/opt/aida-home-hub
Hub UI / API	http://<host-ip>:8080
Matterbridge UI	http://<host-ip>:8283
MQTTS (Home Assistant)	port 8883
Operator scripts	start.sh, stop.sh, uninstall.sh in the install directory

:::tip Host network The hub uses Docker host networking so CoAP and Matter discovery see the LAN. Do not put it behind a bridge-only Docker network. :::

Setup process

Step 1: Open the operator UI

1. On a browser on the same LAN, open http://<hub-host>:8080.
2. Confirm health at /health if needed.
3. Use the Clusters, INX devices, and Integrations pages.

Step 2: Register clusters

On the Clusters page:

1. Add each room or zone you commissioned (for example Kitchen, Living Room).
2. Choose the cluster kind (light or shade) as appropriate.
3. Set a friendly display name if you want a different label in the UI.

:::important Name match Cluster names must match the Commissioner Excel Cluster ID and the keyw values written to devices. Otherwise voice and HA commands will not reach the fixtures. :::

Step 3: Discover INX devices (optional)

On the INX devices page, run discovery to list nodes on the LAN. Use this to verify connectivity and serials; primary control still goes through clusters.

Step 4: Pair voice apps with Matter

Matter is the recommended path for Alexa, Google Home, and Apple Home.

1. Confirm clusters are registered (Matterbridge exposes up to twelve by default).
2. Open Integrations → Matter Bridge in the hub UI.
3. Ensure Matterbridge is running (co-installed by install.sh).
4. On your phone, open Apple Home, Google Home, or Alexa → add a Matter device.
5. On the hub page, tap Open Commissioning, then scan the QR code or enter the setup code.
6. Name each light or shade when prompted.

Example voice commands after pairing:

• “Turn on the kitchen lights”
• “Dim living room lights to 40%”
• “Close the living room shades”

Step 5: Connect Home Assistant (optional)

1. Confirm the hub MQTT broker is reachable (default MQTTS port 8883 on the hub host).
2. In Home Assistant go to Settings → Devices & services → Add integration → MQTT.
3. Enter the hub host as broker, port 8883, and enable TLS.
4. Complete the wizard. Within about a minute, clusters should appear as lights and covers under the MQTT integration.

Topic pattern	Purpose
homeassistant/light/<id>/config	Light cluster discovery
homeassistant/cover/<id>/config	Shade cluster discovery
aida_home_hub/cluster/<name>/state	JSON state
aida_home_hub/cluster/<name>/set	JSON commands from HA

Ports and services

Port	Service
8080	Home Hub web UI and API
8283	Matterbridge frontend / pairing API
8883	MQTTS (Home Assistant and hub)
1883	Plain MQTT (optional, co-installed broker)
5683	CoAP to INX nodes (UDP)

Troubleshooting

Symptom	What to check
No pairing QR / code	Matterbridge running on :8283; refresh Integrations → Matter Bridge
Phone cannot find Matter device	Phone on same Wi‑Fi as hub; open commissioning before scanning
HA shows no devices	Broker host is the hub LAN IP (not 127.0.0.1 unless HA is on the same machine); port 8883 reachable; clusters registered
Voice does nothing	Cluster name matches Commissioner Cluster ID; Matterbridge restarted after adding clusters
Discovery finds nothing	Host on correct subnet; NET_RAW / host network; nodes powered and on LAN

Related documentation

• Aida Home overview — product map and naming convention
• Aida Commissioner — write Cluster IDs during install
• Aida Controller — commercial edge alternative

Support

For support, contact your system administrator or MHT Technologies.