Matter bridge plugin

Shows devices you define in Nexus to Alexa, Google Home, Apple Home and Home Assistant as a Matter bridge, on your own network without a cloud or skill. Their state comes from Nexus (for example a Loxone output); what those apps command comes back into Nexus as sensors.

What it does

• Sensors: commands from the apps per device: on/off, brightness, colour temperature, colour, a blind's target position and slat angle, a thermostat's setpoints and mode, a fan's speed, lock and unlock requests, opening and closing a valve, a wallbox's charging release, current and mode, and a chime played from an app (a ring pulse and its sound).
• Actuators: each device's state for the apps: the same values back, plus temperature, humidity, illuminance, pressure, flow, air quality, CO₂ and PM2.5, contact, motion, smoke and CO alarms, water leaks, rain, frost, battery levels, button and doorbell presses that start routines, and energy: power, energy, voltage and current of meters, PV systems, home batteries, wallboxes and heat pumps, and a wallbox's car and session.
• Catalog: one folder per device with exactly the signals its type has.
• Panel: where pairing stands ("Not paired yet", or a pairing window counting down to its end), the QR code and code (while the bridge's own code works), the paired apps with a Remove button each, and every device with its id, last command and last state, with Edit and Remove buttons. It refreshes by itself on pairing, pairing windows, controllers, device changes and new commands and states.
• Actions: Add device, Edit device, Remove device (while the bridge runs, no restart), Open pairing window (15 minutes, to add a second app) and Remove pairing.

Before you start

• Nexus with host networking (network_mode: host, as in compose.yaml) and IPv6 enabled on the host, on the same network segment (VLAN) as your Echo, Google or Apple hub. mDNS (UDP 5353) must reach Nexus, and the UDP port (5540) must be open on the host's firewall.
• A Matter controller: an Echo of the 4th generation or newer, a Google Nest hub, an Apple TV or HomePod, or Home Assistant with its Matter integration.
• UDP port 5540 free on the host, or another one in the settings (Home Assistant's Matter Server and Matterbridge use 5540 too).
• About 180–230 MB of memory per running instance; one instance is enough for 50 devices.

Configuration

Devices are not settings: add them with Add device on the instance page (name, type, where a kind has several types the one you want, e.g. Light → Dimmable, for door locks Allow unlocking, for battery-powered sensors and buttons Battery), at most 50 (Alexa's limit for one bridge).

Sensors and actuators

Matter device types

Every device type matter.js 0.18 knows (it follows Matter 1.6.1, so this covers every type up to 1.5 and the newest ones), and whether the bridge offers it. What an app shows of a type is up to the app; the newer the type, the fewer apps know it.

Good to know

• To pair, add a Matter device in the app and scan the QR code on the instance page, or type the 11-digit code. Alexa warns that the bridge is not certified; that is expected.
• Renaming a device keeps it in the apps (Alexa may show the old name until you rename it there); removing and adding it again makes a new device, and its routines are lost.
• Wire each command sensor and its state actuator: a command that matches the state the bridge shows sends nothing new, so the state must come back from Loxone.
• Door locks refuse unlocking from the apps unless Allow unlocking is on. The smoke and CO alarm only forwards what Nexus reports; it is no replacement for a certified smoke detector.
• While a pairing window is open, anyone on your network who sees the code could pair. Alexa can't find the bridge? Usually mDNS or IPv6 doesn't reach it (see the reference).

More

The full reference (managing devices, what each device type shows in the apps and what Alexa does with it, how values convert, pairing more apps and removing them, the panel, networking and troubleshooting, storage, memory, limits, security notes and development notes) is in REFERENCE.md next to this file, and on the plugin's page in the Nexus documentation.

Managing devices

Devices are kept in the plugin store (devices), not in the settings, and changed with actions on the instance page while the bridge runs; none of them restarts the instance or touches a pairing. Their buttons are in the Status card: Add device above the Devices table, Edit and Remove on each row, Open pairing window in the Pairing section and Remove on each controller's row.

• Kinds with several types. type is the kind, and the type goes in the kind's own field:

  Kind (type)	Field	Types
  Light (lights)	light	dimmable-light, on-off-light, color-temperature-light, color-light
  Plug (plugs)	plug	plug, dimmable-plug
  Wall switch or dimmer (wall-controls)	wallControl	wall-switch, wall-dimmer
  Blind or shutter (blinds)	blind	window-covering, venetian-blind
  Thermostat (thermostats)	thermostat	thermostat, thermostat-heat-cool
  Sensor (sensors)	sensor	temperature-sensor, humidity-sensor, light-sensor, pressure-sensor, flow-sensor, air-quality-sensor
  Leak, rain or frost sensor (water-sensors)	waterSensor	water-leak-detector, rain-sensor, water-freeze-detector
  Button or doorbell (buttons)	button	generic-switch, doorbell
  Energy meter (energy-meters)	energyMeter	electrical-meter, solar-power, battery-storage

  Every other type is a kind of its own, with the type as type, e.g. { "type": "door-lock", "name": "Front door" }; a kind with several types looks like { "type": "lights", "light": "dimmable-light", "name": "Kitchen" }. (Up to plugin version 0.1.0, type was the type itself.)

• Ids. A new device gets an id from its name and a short random suffix, e.g. kitchen-light-3f2a. Its signals refer to it, and its Matter identity (endpoint, unique id, serial number) derives from it, so neither changes when the device is renamed.

• Adding shows the device to every paired app at once: a Matter controller sees it within a second (measured with matter.js). The Alexa app may take a minute or need Discover devices.

• Renaming keeps the device, its routines and its signals. The bridge reports the new label (Matter's NodeLabel) to the paired apps right away, but apps often keep the name they gave the device when it was added: rename it in the app too, or remove it there and discover again.

• Removing takes the device from every app (routines using it stop working). Its signals in Nexus stay, in the error state ("the bridge has no device …"), until you remove them.

• From an older version. Devices that the first version kept in the settings move into the bridge's own storage once (config version 2), with their name as id (what their signals refer to) and the Matter identity they had, so a paired Alexa keeps them. That happens at the first start, or when the settings are saved before it; either way nothing is lost.

Device types

Each device is one bridged Matter device. Its type decides what the apps show and which signals it has.

Battery. Sensors, buttons and doorbells (every type above with actuators only, except the smoke and CO alarm, which reports itself as wired) can be added with Battery on: the device then also has a battery actuator, and the apps show its level (Matter's power source with a battery) and warn when it is low. Without it the device has no battery at all, as a mains-powered one.

"Unknown" is Matter's empty value: the apps show no reading rather than a made-up one; "Starts as" is what a new device shows before Nexus sends anything.

After a restart (a config change, an update) each device shows what it showed before, although Nexus doesn't replay values to actuators when an instance starts. matter.js stores on/off, brightness, colour, positions, fan speeds, setpoints and thermostat modes itself. For contacts, motion, locks, valves, alarms, leaks, rain, frost, measurements, air quality, battery levels, electrical measurements and a wallbox's car, supply and current the plugin keeps the last state Nexus sent (store keys state:<device id>): without it a restart would show every door closed and then "open" it again, which starts "door opens" routines although nothing happened, and temperatures would be unknown until Loxone happens to send again. After the factory reset that follows removing the last app, the bridge sets every state Nexus sent in this run again, in the order it sent them.

Sensors-only types are what start routines in Alexa ("when the front door opens, announce …"). Values without a Matter device type, such as a single power value of a device that is no energy device, can't be shown sensibly.

Energy devices. Matter composes its energy device types from utility types: a PV system is also a power source and an electrical sensor; battery storage, a wallbox and a heat pump add device energy management. The bridge puts these on the device's own endpoint (matter.js lists them), and the heat pump's thermostat on an endpoint below it; the power source names both. Energy management only says what kind of device it is and that it is online: a wallbox's has no forecast (null), a battery's and heat pump's no adjustment capability, so a controller's power adjustment request is refused. A battery's AC and battery sides, which Matter describes as two, are one. A wallbox keeps the charging targets an app sets (and returns them when asked) while it runs, but plans nothing with them; its next-charge attributes stay unknown.

A home battery's power source is rechargeable: its charge state follows the power (charging while positive, full at 100 %, otherwise not charging), and unlike a sensor's battery it never warns or asks for replacement when it runs low. Its voltage, times and charging current are unknown, and its capacity, which Matter can't leave unknown, is left out.

What the apps do with a type is up to them, and only real hardware shows it:

• Smoke and CO alarm: it forwards an alarm state from Nexus, for example Loxone's fire and water alarm; it detects nothing itself and is no replacement for a certified smoke detector. Alexa announces smoke and CO alarms of Matter devices as proactive notifications.
• Water leak detector: Amazon's list of Matter device types has no Alexa interface for it, so Alexa may show it without routines; Google Home, Apple Home and Home Assistant support it.
• Door lock: Alexa asks for its own voice code before unlocking by voice (set in the Alexa app); Nexus keeps no PIN codes. Unlocking from any app is refused unless Allow unlocking is on for the lock.
• Rain sensor, water freeze detector, water valve, doorbell, wall switch and wall dimmer: newer Matter types (1.3 and later). Apps that don't know them yet may show them as an unknown device or not at all; Home Assistant shows them.
• Colour light: Alexa, Google Home and Apple Home set colours by hue and saturation or by x/y; both arrive as the same RGB value.
• Energy devices (meter, PV, battery, wallbox, heat pump): Matter 1.3 and newer types for energy dashboards. Which apps show them, and what they show, varies and changes with their updates; Home Assistant reads the power and energy measurements. A device an app doesn't know may be missing in it or shown as unknown.
• Button: apps that support Matter buttons (generic switches) offer presses as routine triggers; whether Alexa does for a bridged button could not be checked without an Echo.

How values convert

New signals suggest the unit and decimals of their value: °C with one decimal for temperatures and setpoints, % without decimals for humidity, brightness, position, fan speed and battery, K for color temperature, lx and hPa without decimals, and m³/h with one.

A command from an app updates the bridge at once (Matter needs that) and goes to the sensor. A state from Nexus updates the bridge and is never sent back as a command, so a sensor and an actuator of the same device can both be wired to Loxone without a loop. Nexus drops a value equal to the previous one, and the bridge only reports changes: a command that matches what the bridge shows (Alexa says "on" while it shows on) sends nothing. Wire the state actuator as well, so the bridge shows what Loxone did.

A heating thermostat (thermostat) stays in heat mode: a mode change from an app (off, auto) is accepted by the bridge but not passed on. The heating and cooling thermostat passes modes both ways.

Sensor and actuator params

Every sensor and actuator has one param:

A sensor for a device that doesn't exist, or whose type has no such command, goes into the error state with the reason (for example "Hall" is a plug (on/off), which gets no brightness commands); it follows devices removed while it runs. An actuator does the same, and each command it gets meanwhile fails with that message. Renaming never affects signals.

Catalog

One folder per device, labelled <name> (<type>), with the sensors first, then the actuators, e.g. Kitchen light: on/off from controllers and Kitchen light: brightness % to controllers. Every entry can be added as it is.

Pairing

The first app pairs while the bridge is not paired: in the Alexa app Devices → + → Add Device → Matter (in Google Home, Apple Home or Home Assistant: add a Matter device), then scan the QR code from the instance page or choose to type the 11-digit code. Alexa and Apple warn that the bridge is not certified (it uses the Matter test vendor id 0xFFF1); continue anyway. The devices then appear with their names.

• A second app (multi-admin). Run Open pairing window: for 15 minutes the bridge accepts another pairing with the same code, and the panel shows the QR code and counts down to the end. The answer shows the code too. Alternatively, share the bridge from an app that already has it (the apps call it sharing or linking a Matter device); that app then shows a code of its own. While that window is open the panel says so instead of showing the bridge's code (which doesn't work then), and Open pairing window refuses until it has closed.
• Removing an app. The Controllers table has a Remove button per app (or run Remove pairing with the fabric index the table shows). The bridge leaves that app's fabric at once; the app loses all the bridge's devices and its routines with them. Removing the bridge in the app itself works as well.
• Removing the last app resets the bridge to factory settings: it forgets every pairing and waits to be paired again, with the same code. The reset puts every device back to how it was created; the bridge then sets their names, each lock's Allow unlocking and the states Nexus sent again. The reset takes a fraction of a second; a request that still meets it is answered "the bridge is resetting … try again in a few seconds".
• The code (passcode and discriminator) is chosen once per instance and kept in the store (pairing). The keys and certificates of the pairings are kept there too (matter:bridge/…), so they survive restarts, config changes and updates, and travel in Nexus's backup.
• Device identity comes from the device's id (see Managing devices): renaming keeps it, removing and adding a device makes a new one. A config change restarts the instance; the pairing is kept.

Panel

The page refreshes by itself when the bridge pairs or a controller is added or removed, when a pairing window opens or closes (the 15-minute one, and one a paired app opens to share the bridge), when devices are added, edited or removed, and on new commands and states. The end of an unpaired bridge's 48-hour window shows at the next regular refresh (within 30 s).

Actions

Add, Edit and Remove device are described under Managing devices.

Networking

Matter finds devices by mDNS and talks to them over UDP, mostly IPv6. Nexus must run with host networking (network_mode: host, as in the provided compose.yaml); Docker's bridge network hides mDNS and IPv6 link-local addresses.

• Same network segment. The Echo (or Google hub, Apple TV, Home Assistant) and the Nexus host must be in the same VLAN. mDNS does not cross VLANs unless a reflector (an mDNS repeater on the router) is set up, and even then Matter often fails.
• IPv6. IPv6 must be enabled on the host's network interface. Link-local addresses (fe80::) are enough; no IPv6 from your provider is needed.
• Ports. UDP 5540 (or the configured port) and UDP 5353 (mDNS) inbound on the host's firewall (ufw allow 5540/udp, ufw allow 5353/udp; in firewalld, the zone of that interface). The bridge shares port 5353 with avahi on the host; that is fine.
• Wi-Fi. Some access points filter multicast between Wi-Fi and wired clients, or convert it ("multicast enhancement", "IGMP snooping" without a querier, "client isolation"). If the Echo is on Wi-Fi and pairing never finds the bridge, try turning those off.
• Several Matter programs on one host (Home Assistant's Matter Server, Matterbridge, a second bridge instance) each need their own UDP port.

Troubleshooting

The instance log shows matter.js's lines prefixed matter.js:: its notices as info, its warnings and errors as warnings and errors, its info lines as debug. Its debug lines are not logged.

Storage and writes

Everything the plugin keeps is in the instance's store, so in Nexus's database: the pairing code (pairing), the devices (devices), matter.js's data (matter:bridge/<context>, one key per storage context) and the remembered states (state:<device id>). Nothing is written to files.

Fabrics, sessions, access control, commissioning data, endpoint numbers and the pairing code are written at once. Device states (the attributes matter.js stores, and the remembered states) are merged: changes within 1.5 s become one write per key, and a stop writes what is pending. A crash loses at most the last 1.5 s of device states, never a pairing.

Measured with the plugin's tests (store writes):

Memory

One instance uses about 45–55 MB of JavaScript heap and adds about 180 MB (5 devices) to 230 MB (50 devices of all types) to the memory of the Nexus process (RSS), mostly matter.js itself and its own engine in the plugin's worker. The plugin asks for a heap limit of 256 MB (heapMb). On a small machine (1–2 GB) run a single instance; one bridge carries up to 50 devices.

Limits

Security notes

• While a pairing window is open, anyone on the same network who knows or guesses the code can pair and then switch the devices of this bridge. The window opens only while nothing is paired or after Open pairing window, and closes after 15 minutes.
• The pairing code is shown only on the instance page and in the action's answer, to logged-in users; it is never written to the log.
• Pairing keys live in Nexus's database and its encrypted backup. Restoring a backup on a second machine while the first one still runs puts two bridges with the same identity on the network; stop one of them.
• Every paired app can switch every device of the bridge. Put devices that must not be switched by voice into no bridge, or only as sensors.
• A door lock in the bridge can be locked by every paired app and anyone who can talk to them. Unlocking is refused unless Allow unlocking is on; with it on, an app's own protection (Alexa's voice code) is all that stands between a voice command and an open door. Wire the lock request to Loxone only where that is acceptable.

Development

npm run build -w @lox-nexus/plugin-matter-bridge   # dist/plugin.js (~6.5 MB) and dist/THIRD-PARTY-LICENSES.txt
node --conditions=@lox-nexus/source --import tsx --test "plugins/matter-bridge/src/**/*.test.ts"

• @matter/main (matter.js) is pinned to exactly 0.18.0; an update is a deliberate step, together with the Matter controller plugin. The bundle is not minified (matter.js relies on class names), replaces matter.js's Bun SQLite driver with a stub, and lists the licenses of all bundled packages (matter.js: Apache-2.0) in dist/THIRD-PARTY-LICENSES.txt.
• matter.js is configured in code: its storage is the plugin store (one store key per storage context, matter:<node>/<context path>, longer keys shortened with a hash), it has no file system, it doesn't trap process signals, and its log goes to the instance log without the ASCII-art QR code.
• matter.js reads ~/.matter/config.json and MATTER_* settings when it is loaded, if they exist; Nexus creates neither, and a plugin worker's environment is empty. (Turning this off would need matter.js's Node.js configuration loaded before matter.js itself, which a bundle and the tests can't guarantee.)
• The tests pair the bridge with a matter.js controller in the same process over UDP on free ports, with mDNS on the loopback interface (mdns.networkInterface = lo), so npm test doesn't announce test bridges to the LAN.