Commissioning to Amazon Alexa
Plan your first bridge around the Stable 2.0.55 Alexa compatibility rules: use 5540 for the first commissioning, keep the device count under control, and treat the cover, light and vacuum flags as workarounds you can roll back.
Your first Alexa bridge needs its own plan
Home Assistant Matter Hub is a bridge; Alexa is a Matter controller. When Alexa onboards it, Alexa does not understand the Home Assistant Dashboard or every HA domain — it builds Alexa devices from the Matter device types and clusters the bridge declares. Upstream states plainly for Stable 2.0.55 that Alexa only completes commissioning on port 5540, so the first time you hand any bridge to Alexa, the target bridge has to be the one currently using 5540.
The port rule, the device count and the feature flags are three different things: 5540 solves first-commissioning compatibility; about 80–100 bridged devices is the practical controller planning range the upstream documentation describes, not a hard limit in the Matter protocol; the Alexa flags only address specific UI and command differences. Do not use one of them to explain every failure.
The Alexa checklist before you start
| Item | Required check | What to do first if it fails |
|---|---|---|
| Alexa app / account | The app is up to date, signed in to the target Amazon account, and you can manage the right Home. | Fix the account and the home first; do not open a commissioning window. |
| Compatible Echo / controller | Confirm against Amazon's official Matter documentation that the Echo you are using can act as a Matter controller. | Do not assume support just because you own an Alexa voice device. |
| Port of the first bridge | The bridge you plan to onboard to Alexa first uses 5540, and no other process holds that port. | Stop creating duplicate bridges; work out what holds the port and which bridge takes precedence. |
| Local network | The Echo, your phone and Matter Hub can discover each other on the local network over IPv6 and mDNS. | Fix the VLAN, multicast and network interfaces; do not set up port forwarding. |
| Scale and contents | Start with a small number of basic types, far below the practical limit, and preview them in Devices and the filter. | Split the bridge or exclude unsupported types; do not expose all of HA at once. |
Why the first commissioning has to use 5540
The pinned v2.0.55 documentation states it plainly: after Alexa completes AddNOC on another port, the commissioning still rolls back; only a bridge currently on 5540 can finish Alexa commissioning. In practice, keep the core Alexa bridge permanently on UDP 5540 and onboard a small set of devices to it; other controllers can join bridges on other ports, or join this core bridge as an additional fabric. None of this means that opening a firewall port lets you commission remotely.
- 5540 is a local Matter service port; do not forward it to the internet and do not expose it publicly.
- If a bridge on the same host already uses 5540, do not let a second one fight for the same port; decide first which one is the core Alexa bridge.
- Changing the port after commissioning adds variables. Back up first, assess every fabric and pick a maintenance window, instead of switching ports casually for a test.
- Treat a not-on-5540 warning as an Alexa compatibility risk first; it does not mean other controllers are bound to fail.
About 80–100 devices is a practical planning figure
When the upstream documentation gives about 80–100 bridged devices as practical controller-scale guidance for Alexa, read it as a planning range — not a guaranteed figure, not an exact hard limit, and not the theoretical maximum number of endpoints Matter Hub can build. Real capacity depends on the Echo model and its software, endpoint complexity, cluster count, subscriptions, network quality, and the devices already in the same Alexa Home.
| Scale stage | Approach | What to watch |
|---|---|---|
| Baseline | Start with a small number of basic lights and switches. | Commissioning time, how complete discovery is, and control and state latency. |
| Expand batch by batch | Add a limited number of endpoints of the same kind per batch. | Whether they all appear in the Alexa app, whether voice names collide, and whether subscriptions stay stable. |
| Close to the practical range | Plan the bridge split well below the point where things break. | Echo resources, recovery after a restart, and whether one error drags everything down. |
| Past the range | Do not cite the upstream range as a promise that it works; split bridges by area or type and verify one bridge at a time. | A multi-bridge and port strategy also needs real testing against Alexa. |
Read the device count as the number of bridged devices and endpoints Alexa actually builds, not as a direct conversion from your Home Assistant entity count; a composed device can carry several endpoints, and some HA entities will not map at all. When you write results down, record counts and types only, never internal identifiers.
Compatibility flags for cover, light and vacuum
| What it is for | Intended behavior in Stable 2.0.55 | Cost / limits |
|---|---|---|
| Cover as dimmable light | Exposes a cover that Alexa renders poorly with dimmable-light semantics, so on/off and percentage control work. | The device type and the voice semantics are no longer a curtain; other controllers may show it as a light, so it suits an Alexa-only bridge. |
| alexaPreserveBrightnessOnTurnOn | Keeps the existing brightness when Alexa turns a light on, so turn on does not overwrite the brightness at the same time. | The manifest marks it Alexa yes, Apple and Google no; do not treat it as a general cross-controller improvement. |
| vacuumOnOff | Gives the controller a simplified on/off control path for a vacuum. | That is not the same as full room cleaning, modes, progress or return-to-dock; verify Alexa support item by item. |
| vacuumIncludeUnnamedRooms | Includes rooms with no usable name in the vacuum's service-area mapping. | It can produce entries you cannot tell apart; give your areas clean names in HA first. |
Change one feature flag at a time, capture a secret-free record of the configuration before you save, and after the restart test the Alexa app, voice, HA state and the other fabrics. A workaround that changes device semantics, such as cover-as-light, suits a separate Alexa bridge best; if the same bridge also serves Apple or Google, fixing Alexa can break how the other controllers render it.
Stable does not mean Alexa supports every type
| Fact layer | Conclusion | Promises you cannot extend |
|---|---|---|
| Release channel | This chapter is pinned to Matter Hub Stable v2.0.55 and the pinned Stable add-on. | It does not cover Alpha or Testing, or the later callback architecture. |
| Product maturity | The standard bridge and the existing flags above are in Stable. | Server Mode, the Camera and Security plugins and some Matter 1.4 types are still experimental inside Stable. |
| Alexa support | Amazon publishes the list of Matter devices Alexa supports; upstream adds a handful of Alexa workarounds. | A flag existing does not let you claim the device is certified by Amazon, or that every attribute is complete. |
| Scale | About 80–100 is a practical controller planning range with an upstream source behind it. | It is not a minimum guarantee, an exact limit, or an SLA shared by every Echo. |
Build and commission the core Alexa bridge
Reserve 5540 and the core contents
In Matter Hub, create or edit the bridge you will hand to Alexa first, and confirm it uses 5540 with no conflict; keep the filter to a small set of known basic devices.
Start it and run the Matter Hub preflight
Confirm the bridge is running, that Devices shows no failed mappings, and that the underlying HA entities still respond. Back up the persistent data, and freeze the port, the names and the structure for the duration of commissioning.
Open the commissioning window
Display this session's QR code from the target bridge. Do not screenshot it, forward it, log it, or paste the manual pairing data into anything you send to Amazon support.
Add a Matter device in the Alexa app
In the add flow under Devices, choose Add Matter device or whatever the current app calls the same entry point, scan the local QR code, pick the target Home and keep the app in the foreground.
Wait for the bridged devices to be discovered
Once onboarding finishes, let Alexa complete device discovery; do not run Force Sync, change the filter or restart the Echo at this point. Confirm the small baseline set appears.
Test the app, voice and state in both directions
Operate one device from the Alexa app and one by voice, then operate one from HA and confirm Alexa updates. Record the types and the results, never any internal identifier.
Expand in small batches, or split
Add a few devices of the same kind at a time; if you need the cover-as-light or vacuum workarounds, test them on an Alexa-only bridge first, so you do not change the semantics for other fabrics.
Common Alexa pitfalls
A not-on-5540 warning appears
Stop the first onboarding and check whether this is your first Alexa bridge. If it has not been commissioned yet, re-plan so the core bridge uses 5540; if a fabric already exists, do not swap the port outright — back up first and assess the impact.
The Alexa app cannot find the bridge
Confirm the Echo supports Matter, that the window is still open, and that the IPv6 and mDNS path between the Echo, your phone and Matter Hub works. Do not work around local discovery with public forwarding or by sharing the QR code.
Only some devices are discovered
Compare Devices, the filter and Alexa's official device-type support; check whether you are close to the practical scale, whether names are duplicated, or whether the endpoints are too complex. Work in batches instead of resetting everything.
A cover has no usable control
Check what Alexa's native cover rendering can and cannot do first; if you are considering cover-as-dimmable-light, put it on an Alexa-only bridge and accept that the type becomes a light.
Brightness jumps when the light turns on
Only test alexaPreserveBrightnessOnTurnOn when you can reproduce Alexa overwriting the brightness on turn on; controller support for this flag is Alexa yes, not a cross-platform setting.
The vacuum only has on/off, or its rooms are incomplete
Basic on/off does not mean full vacuum support. Cross-check the vacuum flags, the area names and Alexa's official capabilities; record rooms, modes and progress one by one as yes, partial or unknown.
FAQ
Does Alexa commissioning have to happen on 5540?
Is 80–100 devices a guaranteed capacity?
Does cover as light affect Apple or Google?
Does turning on alexaPreserveBrightnessOnTurnOn improve every controller?
If Alexa shows a vacuum card, does that mean room cleaning is fully supported?
Pinned-version and official Amazon sources
- v2.0.55 Bridge Configuration (5540 and the practical 80–100 scale)
- Matter Hub v2.0.55 README and release notes
- v2.0.55 feature flags
- Pinned add-on changelog
- Amazon Alexa Smart Home: Matter support
- Amazon Help: Connect Your Matter Device to Alexa
Use the 80–100 figure only as upstream practical scale planning, not as an official Amazon hard limit or a guaranteed capacity.