Skip to main content

Matter Module

The Matter module on Aida Controller connects your building to Matter ecosystems in two directions:

RoleWhat it does
Bridge (northbound)Expose facility lighting, shading, and HVAC zones — plus selected Scenes — to Apple Home, Google Home, and Alexa for local voice control
Controller (southbound)Commission Matter devices (first product target: Philips Hue Bridge) into Aida as one gateway device with light resources under it

Voice and phone commands on the bridge, and Control / schedules / Scenes on Hue resources, all run through the same Control engine as the rest of the controller (source=matter for voice).

:::info Version requirement Matter requires Aida Controller 2.0 v2.22.0 or later. After a software update to 2.22.0+, also update host-controller so the matter-bridge and matter-controller sidecars start. :::

:::caution One voice Matter bridge per LAN Do not run Aida Home Hub Matterbridge and this Controller Matter bridge on the same site network at the same time. Pick one voice bridge for the LAN. :::

Overview​

Operator work is on the controller UI under Modules → Matter, with three tabs:

  • Bridge — which zones and Scenes to export, network binding, Matterbridge UI link, commissioning (QR / setup code)
  • Controller — Hue (and peer) commission by setup code, node inventory, refresh
  • Logs — command history for Matter traffic

This module provides:

  • Voice export — lighting zones as dimmable lights, shading as window coverings, HVAC as thermostats, Scenes as On/Off endpoints
  • Facility-first scope — you choose which zones and Scenes to import; empty selection exports nothing
  • Hue adopt — one gateway device + endpoints as resources (not one device per bulb)
  • Software light policy — SOFTWARE_GATEWAY / SOFTWARE_LIGHT templates and Device Group overrides for multi-room Hue
  • Local Matter — pairing and control stay on the LAN after commission (no cloud skill required for v1)

How it works​

PieceRole
matter-bridgeMatterbridge + Aida plugin — advertises selected zones/Scenes; admin UI on port 8283
matter-controllerAida commissioner — pairs Hue (etc.); admin API on port 8291
Facility zoneslighting / shading / hvac membership targets for voice loads
ScenesOperations → Scenes primitives you explicitly select for export (facility zone_type=scene is not exported)

Prerequisites​

Before enabling Matter, ensure you have:

  • Aida Controller 2.0 v2.22.0+ with host-controller updated so Matter sidecars are running
  • Facility lighting / shading / HVAC zones (and optional Scenes) for the voice bridge
  • Phones or speakers on the same LAN as the controller (Matter / mDNS must work)
  • A stable IPv4 on the NIC you bind for Apple Home (set under Bridge settings)
  • For Hue: a Matter-capable Philips Hue Bridge and its Matter setup / pairing code

:::tip Sidecar warm-up After a stack restart, Matterbridge waits for the backend, then applies a short start delay (about 30 seconds) before the admin UI on :8283 answers. If Modules → Matter says the bridge is unreachable right after update, wait a minute and refresh. :::

Setup process​

Step 1: Confirm sidecars and enable the module​

  1. Update software to v2.22.0+, then update host-controller if prompted.
  2. On the appliance, confirm matter-bridge and matter-controller containers are running (host-controller reconcile starts them with the stack).
  3. Open Modules → Matter and enable the module.
  4. Under Bridge / Controller runtime toggles, leave both enabled unless you intentionally run only one role.

Step 2: Configure the voice bridge (optional)​

  1. Open Modules → Matter → Bridge.
  2. Select lighting, shading, and/or HVAC zones to export (explicit pick — nothing is auto-exported).
  3. Select Scenes to expose as voice On/Off endpoints (optional).
  4. Set network binding — choose the LAN interface / IPv4 Matterbridge should advertise (important for Apple Home).
  5. Save. The bridge restarts or reapplies binding as needed.

Step 3: Pair with Apple Home / Google / Alexa​

  1. Open Bridge → Commissioning (or the linked Matterbridge UI on port 8283).
  2. Open the commissioning window and use the QR code or manual pairing code.
  3. In the phone app, add the accessory on the same Wi‑Fi / LAN as the controller.
  4. Confirm zone and Scene endpoints appear with the names you expect.
  5. Test a voice or app command — Control Log should show events with source=matter.

Step 4: Commission Hue (optional)​

  1. Open Modules → Matter → Controller.
  2. Put the Hue Bridge in Matter pairing mode (Hue app / bridge docs) and copy the setup code.
  3. Enter the code (and optional display name) and commission.
  4. Aida creates one gateway device and lists bulbs as resources under it (Device Detail → Resources).
  5. Assign resources to Device Groups; apply SOFTWARE_LIGHT (and gateway) templates as needed for per-room policy.
  6. Use Control with resource selection, or Sync Device to refresh observed Matter state.

Step 5: Verify​

  1. Bridge UI / commissioning panel reachable; pairing code available when uncommissioned.
  2. Voice command dims a lighting zone or runs a Scene — members follow via Control.
  3. HVAC zone setpoint / mode from voice updates thermostats in that zone.
  4. Hue resources respond to on / off / dim / CCT from Control; Observed updates after sync or subscription.

Using the module day to day​

Bridge​

TaskWhere
Change which zones/Scenes are exportedModules → Matter → Bridge
Open Matterbridge adminLink to :8283 or commissioning panel
Re-pair / remove fabrics / soft resetBridge → Commissioning
Bind mDNS / IPv4 after NIC changeBridge network settings → apply

Controller (Hue)​

TaskWhere
Commission another bridgeModules → Matter → Controller
See endpointsController node list; Devices → gateway → Resources
Different policies per roomResource group override + group-default SOFTWARE_LIGHT
Refresh inventory / stateRefresh / Sync Device on the gateway

Control and Scenes​

Voice bridge commands and Hue resource commands use the same paths as Operations → Control and Scenes. Schedules and event redirections that target those zones, groups, or resources continue to work; Matter does not bypass the Control engine.

Monitoring and troubleshooting​

Common issues​

Matter bridge unreachable in the UI

  • Confirm host-controller was updated with v2.22.0+ so matter-bridge exists in the stack.
  • Confirm the matter-bridge container is running.
  • Wait for the start delay after backend becomes healthy, then refresh.
  • From the controller host: http://127.0.0.1:8283/ should return the Matterbridge UI.

Phone cannot find the bridge

  • Same LAN / VLAN as the controller; allow mDNS.
  • Set Bridge IPv4 / interface to the correct building NIC (not a management-only address phones cannot reach).
  • Only one Matter voice bridge on that LAN (disable Home Hub Matter if both were installed).

Zones or Scenes missing in Apple / Google / Alexa

  • Confirm they are selected under Bridge scope (empty list exports nothing).
  • Facility zone_type=scene is membership-only — export Operations → Scenes, not facility scene zones.
  • Re-save Bridge settings or restart Matterbridge after large membership changes.

Hue commissioned but Control does nothing

  • Confirm resources are listed under the gateway and assigned to a group with a SOFTWARE_LIGHT policy when you expect policy events.
  • Use Control with resource targeting if the group has mixed members.
  • Sync Device / refresh controller nodes; check Modules → Matter → Logs.

Module disabled

  • Expected: bridge stops exporting and controller adopt/invoke stops. Re-enable under Modules → Matter.