Matter

What Matter is

Matter is an open connectivity standard for the smart home, shepherded by the Connectivity Standards Alliance with backing from big names like Google, Apple, and Amazon. Its whole point is cross-ecosystem compatibility: a Matter product can answer to several different controllers at once, and it does so entirely on your local network — no cloud round-trip required.

Where Zigbee and Z-Wave are radio protocols of their own, Matter is more of an application-layer control protocol that rides on top of ordinary IP networking (IPv6). The transport underneath can be Wi-Fi, wired Ethernet, or Thread, depending on what the device supports.

In Matter terms, WoowTech plays the role of a controller, the same job filled by a Google Nest speaker, an Apple HomePod, or a Samsung SmartThings Station.

Concepts worth knowing

Thread, briefly

Thread is a low-power wireless mesh built for the smart home. It gives Matter devices an IP-addressable way to talk that doesn't rely on Wi-Fi. Think of it as one of the transport choices Matter can use.

Thread does not imply Matter

A device speaking Thread is not automatically a Matter device. Some Thread products instead use Apple HomeKit or a vendor's own protocol. Don't infer Matter support from a Thread badge — look for the actual Matter logo printed on the box.

Commissioning and Bluetooth

Commissioning is the act of enrolling a device into a controller. To make that first handshake easy, most Matter gadgets carry a Bluetooth radio. The Bluetooth link is only used to hand the device its network credentials; once it's on the network, day-to-day control flows over Wi-Fi or Thread. WoowTech leans on the Companion app's Bluetooth for commissioning rather than the server's own radio, which sidesteps conflicts — so you bring your phone near the device during setup.

Joining several fabrics

One of Matter's headline tricks is that a single device can belong to multiple controllers simultaneously — Google Home, Apple Home, and WoowTech all at the same time. The spec calls for devices to support at least five such fabrics concurrently.

Which installs are supported

Running the Matter Server app (it used to be called the Matter add-on) on WoowTech OS is the recommended and currently the only officially supported setup. If you run WoowTech Container, you'll need to launch a separate Docker image of the Matter server yourself; that route is unsupported. Note that 32-bit platforms can't run the Matter Server app.

Adding a device

Before you start

On the WoowTech side:

• Update WoowTech to the newest release.
• Add the Matter integration from Settings > Devices & services.
• For a standard WoowTech OS box, choosing Submit installs the official Matter Server app and connects to it. Container users point the integration at their own external server.

On the device side:

• Confirm both the Matter logo and a Wi-Fi or Thread logo on the packaging.
• Find the pairing QR code or the numeric setup code, and ideally photograph it. Without that code you cannot re-commission the device after a factory reset.

On your phone:

For Android:

• Android 8.1 at minimum, 12 or newer strongly preferred.
• The latest WoowTech Companion app from the Play Store.
• Location permission set to Allow all the time.
• If you're adding Thread devices, a Thread border router on the network (a WoowTech OpenThread Border Router, Nest Hub 2nd gen, or Nest Wi-Fi Pro, among others).

For iPhone:

• iOS 16 or later.
• The latest WoowTech Companion app.
• For Thread devices, a border router such as a HomePod mini/2nd-gen, Apple TV 4K, or WoowTech OpenThread Border Router.

For a Wi-Fi Matter device, make sure your phone is on the same 2.4 GHz network the device will join.

Walkthrough on iOS

1. Launch the WoowTech app.
2. Open Settings > Matter.
3. Tap Add device.
4. Pick No, it's new.
5. Scan the QR code, or use More options to key in the setup code manually.
6. Tap Add to WoowTech to kick off commissioning.
7. Accept the uncertified-accessory warning if one appears.
8. Give the accessory a name if prompted (this is just an internal label).
9. Tap Done.

Walkthrough on Android

1. Power the device up and put it into pairing mode if that's required.
2. Either respond to the system pop-up that offers to scan a QR code, or open Settings > Matter in the app yourself.
3. Choose Add device, then Add Matter device, then No, it's new.
4. Scan the QR code, or pick Setup without QR-code.
5. Let commissioning finish.
6. Check the result under Settings > Matter > Devices.
7. Rename with the pencil icon if you like.

Sharing devices between platforms

Pulling in a device already on Google/Apple Home

If a device is already enrolled in Google Home or Apple Home, you can hand it to WoowTech too:

1. Open the WoowTech app.
2. Go to Settings > Matter.
3. Tap Add device.
4. Choose Yes, it's already in use and name the controller that currently holds it.
5. Follow that platform's prompts.
6. You'll get a confirmation once it's joined.

Matter bridges

Hubs such as the SwitchBot Hub 2, Aqara Hub M2, Ikea Dirigera, and Philips Hue Bridge act as Matter bridges: they expose devices from a non-Matter ecosystem to WoowTech over a local link while you keep using the vendor's own app as well. The bridge itself is commissioned like any other Matter device.

Be aware that bridging can trim the feature set. Philips Hue over Matter, for example, exposes only a limited slice of functionality compared with WoowTech's native Hue integration, so capabilities like entertainment-mode streaming and dynamic scenes may not come through.

Pushing a WoowTech device out to another platform

1. Open Settings > Matter and pick Devices.
2. Select the device.
3. Choose Share device.
4. Present the resulting QR or sharing code to the other platform's app.
5. Finish that platform's setup flow.
6. Confirm the new controller appears under the three-dot menu > Manage fabrics.

Removing a device

To detach a device from a particular controller:

1. Go to Settings > Matter > Devices.
2. Select the device.
3. Open the three-dot menu next to Share device.
4. Pick Manage fabrics.
5. Remove the controller you no longer want.
6. If you removed Apple Home, also delete its entry from the Apple Keychain.

To wipe the device from WoowTech completely, open its three-dot menu and choose Delete.

Device information page

Each device's info panel surfaces diagnostic details:

• Network type — Thread or Wi-Fi.
• Device type — one of:
• End device (radio always listening)
• Sleepy end device (battery-powered, wakes only periodically)
• Routing end device (relays traffic for its neighbors)
• Bridge
• Network details — the network name it joined, its IPv6 addresses, and an IPv4 address where supported.

Firmware updates over the air

Matter OTA updates are optional per device. When a device advertises the capability, WoowTech creates an update entity for it. Update metadata comes from the CSA's Distributed Compliance Ledger, which WoowTech polls every 12 hours by default.

Caveat: OTA updates fail when a Thread device sits behind an Apple border router; you'll see a "Target node did not process the update file" message instead, because of how those routers forward mDNS packets.

Actions

The integration exposes these automation actions:

• matter.water_heater_boost
• matter.set_lock_user
• matter.clear_lock_user
• matter.get_lock_info
• matter.get_lock_users
• matter.set_lock_credential
• matter.clear_lock_credential
• matter.get_lock_credential_status

Water-heater boost

matter.water_heater_boost runs a temporary heating boost:

• Duration in seconds (required)
• An emergency-boost flag (boolean)
• A temporary target temperature in Celsius

Lock user and credential management

Matter locks that implement the Door Lock cluster can have their users and credentials managed through the actions above. Not every lock supports this, so call matter.get_lock_info first to confirm what a given lock can do.

• matter.set_lock_user — create or update a user. User types include unrestricted, schedule-restricted, programming, non-access, forced, disposable, expiring, and remote-only; credential rules can demand one, two, or three credentials.
• matter.clear_lock_user — delete a user and its credentials; passing index 65534 wipes every user at once.
• matter.get_lock_info — report the lock's capabilities; needs no extra data.
• matter.get_lock_users — list every user with status, type, and linked credentials.
• matter.set_lock_credential — add or update a credential (PIN, RFID, fingerprint, finger-vein, or facial), with the slot chosen automatically.
• matter.clear_lock_credential — drop a specific credential by type and index.
• matter.get_lock_credential_status — query a credential slot and the controller that owns it.

Triggering automations from buttons

Devices with button inputs — such as the Tuo Smart Button, the Inovelli VTM31SN dimmer, or an Innovation Matters pushbutton module — can drive automations. See the event integration's documentation for how to build button-press automations.

Trying it without real hardware

No Matter device on hand? You can flash a supported ESP32 dev board with example Matter firmware straight from the browser:

1. Use Chrome or Microsoft Edge.
2. Open the Matter example-apps web flasher at https://nabucasa.github.io/matter-example-apps/.
3. Plug the ESP32 in over USB.
4. Pick a sample app (the Lighting app on an M5STAMP C3 is a good starting point).
5. Click Connect, choose the serial port, and let the firmware install.
6. Open the device console and generate a pairing code with matter onboardingcodes ble.
7. Commission it by scanning that QR code in the Companion app.

Android users must register test devices in the Google Developer Console first; iOS users will just see the usual uncertified-device prompt during commissioning.

Troubleshooting

Downloading diagnostics

For the whole integration: Settings > Devices & services > Matter card menu > Download diagnostics.

For one device: Settings > Devices & services > Matter > pick the device > device menu > Download diagnostics.

The downloaded file holds device attributes, cluster data, and network info, with sensitive fields redacted.

General guidance

• Thread-based Matter devices want WoowTech OS 10 or newer.
• Keep Thread devices within reach of a border router on the same home network.
• Begin with a test device before scaling up.
• Accept that being an early adopter occasionally means rough edges.
• Let IPv6 and multicast traffic move freely; under Settings > System > Network > IPv6, choose Automatic or Static.
• Favor a flat, simple network layout.
• Steer clear of VLANs, multicast filtering, and IGMP snooping where you can, and make sure your Matter devices and WoowTech share the same VLAN.

The commission button is missing

The "Commission using the Companion app" button shows up only inside the mobile app, never in a browser. Double-check your phone meets the minimum OS version.

"Matter is unavailable" on Android

• Give Google Play Services up to 24 hours to pull down its Matter modules.
• Confirm Android 8.1+ (12+ recommended) with a normal Google account.
• Make sure Google Play Services is fully updated.
• Verify Matter support under Settings > Google > Devices & Sharing.
• Reinstall the WoowTech Companion app, and consider installing Google Home to nudge the modules into downloading.
• Fall back to Google's developer troubleshooting guide if needed.

Android stuck on "checking network connectivity"

• Recheck the prerequisites and minimum requirements.
• For a Thread device, hold the phone near both the border router and the device.
• For a Wi-Fi device, confirm the phone is on the same 2.4 GHz network.

"Device requires a border router"

Thread-only devices need a Thread border router present — a WoowTech OpenThread Border Router, Nest Hub 2nd gen, Nest Wi-Fi Pro, HomePod mini, or Apple TV 4K — and the Thread credentials synced from WoowTech onto your Android phone.

"Target node did not process the update file"

This is the Apple-border-router OTA limitation. Work around it by:

• Adding a non-Apple border router such as the WoowTech OpenThread Border Router.
• Powering the Apple border routers off for at least 30 minutes before retrying.
• Letting the devices join the non-Apple border router's network.

Commissioning failures or random drop-offs

Usually a network-configuration symptom:

• Move the Matter devices onto the same VLAN as WoowTech.
• Make sure Thread-only devices reach a Thread network with an accessible border router.
• Review multicast-optimization settings on your router or access points.
• Flatten and simplify the topology.

Related documentation

• Thread integration
• HomeKit controller integration
• Adding HomeKit devices over Thread
• Debug logs and diagnostics