A top bar, a footer, and thirteen places it can send you

The React interface in Stable 2.0.55 is built from a fixed shell: a top app bar, the main content area, a footer, and a language switcher pinned to the bottom right. At desktop width the navigation icons sit directly in the top bar; on a narrower screen the same items move into a drawer on the right. Clicking the logo, or Dashboard, always returns you to the root route /. The top bar also carries the Status Indicator, the light/dark toggle, and the entry point for System Logs — three things this part comes back to below.

Thirteen routes are registered behind that shell. An address that matches none of them lands on Not Found.

From an empty welcome card to three widgets you can rearrange

The dashboard starts by calling the detailed health API. With no bridge yet, it does not show the customizable widgets at all — it shows a welcome card instead, with three ways to create your first one: Bridge Wizard, Setup by Area and Manual Setup, plus an external Documentation link. These three are not maturity levels sitting one above another; they are different setup workflows for different starting points.

Once at least one bridge exists, the dashboard switches to the widget layout. When at least one fabric appears, a first-success message shows once; after you dismiss it, the browser remembers that under the local storage key hamh-first-success-dismissed. That is only a message in the interface — not a commissioning check, and not a guarantee of controller compatibility.

flowchart TD
  A["Dashboard loads, calls the health API"] --> B{"Does at least one
bridge exist?"}
  B -->|"no"| C["Welcome card: Bridge Wizard,
Setup by Area, Manual Setup"]
  B -->|"yes"| D["Widget layout: Status Overview,
Bridges, Quick Navigation"]
  C --> E["You create a bridge
through one of the three paths"]
  E --> D
  D --> F{"Has at least one
fabric appeared yet?"}
  F -->|"yes"| G["A first-success message shows once,
then is remembered in this browser"]
  F -->|"no"| H["No message.
This is the expected
pre-commissioning state"]

1. Step 1

   Read the status at the top first

   Expand the indicator and check the version, uptime, HA connection and WebSocket. With no bridge yet, No Bridges is the expected state, not a fault.

2. Step 2

   Choose a workflow

   For a first bridge, Bridge Wizard is usually the one to press. Choose Setup by Area only once your HA areas are fully planned, and Manual Setup only when you need the fine-grained schema.

3. Step 3

   Go back to the dashboard after creating

   Confirm the welcome card has been replaced by Status Overview, Bridges and Quick Navigation, and that the bridge count matches what you just created.

4. Step 4

   Verify with status only; do not rush into commissioning

   Confirm HA is Online, the bridge is running, and the device count is plausible before you move on to commissioning. Do not expose any pairing data while you are still touring the interface.

Three widgets you can show, reorder and reset

Once a bridge exists, a Customize Dashboard button appears to the right of the dashboard title. The dialog manages exactly three widgets. The eye button toggles visibility, the up and down buttons swap the order, Reset restores the default order and shows everything, and Done closes the dialog.

The setting lives in the current browser under the local storage key hamh-dashboard-widgets. It is not backend bridge configuration, it does not travel with a Matter Hub backup, and it does not sync to every browser you use. On load the code ignores unknown widgets and adds newly known widgets back into the order; corrupted local storage falls back to the default.

1. Step 1

   Open Customize Dashboard

   Go to the dashboard root page and press the customize icon to the right of the title. If the icon is not there, first confirm that at least one bridge exists.

2. Step 2

   Hide the blocks you do not need

   Press the eye to the left of a widget. An operations screen, for instance, can keep only Status Overview and Bridges. Hiding a widget does not stop the health refresh or a bridge.

3. Step 3

   Set the reading order

   Use Move up and Move down on the right to bring the block you read most often to the front; the first item cannot move up and the last cannot move down.

4. Step 4

   Test Reset

   If the layout is not what you expected, press Reset to restore stats → bridges → quickNav with everything visible, then press Done. This changes nothing in the backend.

Stats, the status indicator, and two refresh cadences

The four cards in Status Overview come from api/health/detailed: the total number of bridges (with a running/failed summary), the device count summed across all bridges, the summed fabric count, and the HA connection plus uptime. Once you are on the dashboard it refreshes every 15 seconds; the Status Indicator at the top calls api/health separately and refreshes every 30 seconds. The two can therefore disagree for a short while, and that on its own is not a reason to suspect corrupted data.

flowchart TD
  A["Health check runs"] --> B{"Is health error
or unhealthy?"}
  B -->|"yes"| Z1["Status: Error"]
  B -->|"no"| C{"Is any bridge
stopped or failed?"}
  C -->|"yes"| Z1
  C -->|"no"| D{"Has the WebSocket
dropped?"}
  D -->|"yes"| Z2["Status: Warning"]
  D -->|"no"| E{"No bridge yet, or not
every bridge running?"}
  E -->|"yes"| Z2
  E -->|"no"| Z3["Status: Success"]

With no bridge at all, the icon shows the matching state instead of pretending everything is running.

Bridge mini cards, ordering and bulk actions

The top of the Bridges widget holds Bridge Wizard, Create Bridge and Area Setup, along with Start All, Stop All and Restart All. While a bulk action runs, the buttons are disabled and the code also guards against double clicks; health is fetched again as soon as it finishes. These are real backend actions, not just a change to what the dashboard shows.

Mini cards are ordered by priority, smallest first, with a missing value treated as 100; the #1 and #2 you see are the current display order. Each card shows an icon, the name, running/stopped/failed, the device count and a non-zero fabric count, plus a warning count when there are failed entities. Click a card to open that bridge's details.

Nine Quick Navigation shortcuts

Quick Navigation does not replace the full top navigation. It turns the nine destinations you use most in day-to-day operations into cards: Bridges, Area Setup, Devices, Network Map, Health, Startup Order, Lock Credentials, Filter Reference and Settings. Standalone Devices and Plugins stay reachable from the top navigation, but they are not part of this set of nine.

If you hide the Quick Navigation widget, the top navigation still works; on a phone, open the drawer on the right first. A narrower interface does not mean a feature has been removed.

Interface preferences, the log dialog, and two banners that look worse than they are

The fixed Language button in the bottom right opens a list of 14 languages: English, Deutsch, Français, Español, Italiano, Magyar, Simplified Chinese, Traditional Chinese, Japanese, ไทย, Svenska, Türkçe, Русский and Português (Brasil). Selecting Traditional Chinese maps to zh-TW. Switching affects the interface translation only — it does not change the HA language, a bridge identity, or a display name inside a controller.

The moon/sun icon at the top switches between dark and light. On the desktop layout the icon shows directly; on the mobile layout the drawer shows "Dark Mode" or "Light Mode" as text. The theme is a browser UI preference; it does not change a bridge, a device or the contents of a log.

1. Step 1

   Switch language

   Press the Language button in the bottom right and pick your language from the list. If some strings are still untranslated, the translation for that pinned version may simply not cover them yet — that is not evidence the backend version is wrong.

2. Step 2

   Choose a theme

   On the desktop layout press the theme icon at the top; on the mobile layout open the menu on the right and pick Dark or Light Mode. Check the contrast and the readability.

3. Step 3

   Tell browser preferences apart from backend data

   Checking from a different browser, the language, the widgets or the theme may differ. Do not read that difference as a lost backup.

4. Step 4

   Redact sensitive content when you report a translation issue

   Give only the pinned version, where the string appears, and the wording you expect. Do not attach full System Logs, live URLs or commissioning screens.

System Logs: filter, search, refresh and clear

The Bug Report icon at the top opens the System Logs dialog. By default error, warn and info are selected, and it asks api/logs for at most 500 entries; you can select several of error/warn/info/debug, type a search string, and refresh by hand. With Auto on it refreshes every 5 seconds; the Auto/Manual chip switches between the two.

Each entry shows a timestamp, a level, a message and optional context. Delete sends a DELETE request to the log API and empties the current log — a real, irreversible action, so do not press it before you have preserved the evidence of the fault. Close only closes the dialog; it clears nothing.

Version mismatch and Connection lost

When the frontend and backend versions differ, the app layout shows a yellow Version mismatch banner with a Reload button. That usually means the browser is still holding old frontend assets; press Reload first to get the latest UI. Do not rebuild a bridge or change storage because of it. If it is still there after a reload, check the proxy cache, Ingress and the actual backend version.

When the global WebSocket is not connected, a red banner reads "Connection lost, data may be outdated. Reconnecting…" The WebSocket picks ws/wss from the protocol of the current page, builds api/ws from the document base, and retries about 3 seconds after a drop. The data on screen may be stale while that lasts, so pause bulk actions and configuration changes.

flowchart TD
  A["Something looks wrong
in the interface"] --> B{"Is the banner
Version mismatch?"}
  B -->|"yes"| B1["Press Reload first.
Still there? Check the proxy
cache and the backend version"]
  B -->|"no"| C{"Is the banner
Connection lost?"}
  C -->|"yes"| C1["Wait for the automatic
reconnect. Pause bulk actions
and configuration changes"]
  C -->|"no"| D{"Does Status show
HA Offline?"}
  D -->|"yes"| D1["Go to Health and check the
Home Assistant service connection"]
  D -->|"no"| E["UI Online, HA Online, but a
controller says No Response:
check the bridge, fabric,
session and mDNS layer"]

Decide the bridge's boundaries before you press Create

A standard Matter bridge is one Matter node holding an aggregator and several device endpoints. Decide first which set of HA entities it serves and which external controllers matter to you. Stable 2.0.55 supports several bridges, and multi-fabric on a single bridge — but controller device-type support, product maturity, and the Stable release channel itself are three separate facts, and none of them proves the other two.

For your first bridge, pick a small number of devices that are not safety-critical and are easy to watch. A large bridge can be unstable on some controllers, and the interface will suggest splitting it when that becomes necessary. You can split by area, by domain, or around a controller-specific workaround; no single approach suits every home.

Ten templates, six stages, and four profiles that recommend rather than guarantee

A template is a starting point with the filter, icon and some feature flags prefilled — not a guarantee of controller support. After picking one in the Wizard you still go through the controller profile and the review; the full Create Bridge page can also start from a template, which you then edit in the form or in JSON.

Security & Locks is only a standard entity-filter template, not the Security Plugin, which Stable still marks experimental — similar names do not mean the same feature. The Google Home Optimized wildcard covers "all devices" by default, which may be wider than you expect; narrow it in the full editor after choosing the template, or switch to an area or a label instead.

The six Wizard stages

Template and Controller can be skipped; Bridge name is required; the filter must not be left as an empty include; Review shows a configuration summary and the network preflight, and ends with Create Bridge or Add Another.

flowchart LR
  T["1 Template
skippable"] --> C["2 Controller
skippable"]
  C --> I["3 Bridge Info
name + port required"]
  I --> F["4 Entity Filter
cannot be an empty include"]
  F --> FL["5 Feature Flags"]
  FL --> R["6 Review
summary + network preflight"]
  R --> D1["Create Bridge"]
  R --> D2["Add Another
resets the form"]

1. Step 1

   Open the Wizard and pick a template

   On the Dashboard, press "Bridge Wizard." Choose whichever of the ten templates is closest to your goal, or press Skip Template and start from a blank configuration. Do not infer that every device is supported just because a controller's name appears in a template's name.

2. Step 2

   Pick a controller profile

   Choose one of Apple Home, Google Home, Amazon Alexa or Multi-Controller, or skip. A profile only merges in recommended feature flags — it does not commission anything for you and does not verify device types.

3. Step 3

   Fill in Bridge Info

   Enter a name you can recognize that carries no sensitive location information. Keep the next free port the Wizard fetched for you; if the target is Alexa, plan 5540 for this first bridge. Leave Server Mode unchecked on an ordinary bridge.

4. Step 4

   Set an explicit filter

   The Wizard lets you edit Pattern, Domain, Area, Label and exclude only when you chose Skip Template; with any non-Server Mode template, the template filter is read-only inside the Wizard, and you change it in the full editor after the bridge exists. For a first test pick a single area or domain, or an explicit pattern, and add an exclude for entities you do not need to expose.

5. Step 5

   Review the four Wizard flags

   Adjust Auto Compose Devices, Auto Force Sync, Invert Cover Direction and Include Hidden Entities to suit what you need. Flags the controller profile already recommends are merged into the display — do not switch them all on in pursuit of "the most features."

6. Step 6

   Review, preflight, then Create or Add Another

   Cross-check the name, port, include, exclude, Server Mode and flags. Expand the network remediation and deal with every fail and warn first. Press Create Bridge only when the summary and the preflight match your plan; if you use Add Another, go back to Bridges every time and confirm the bridge really exists.

Controller profiles: recommended settings, not a support matrix

A profile's flags override and merge into the template's current values. If you deselect the profile, the Wizard does not restore every earlier flag — read the final result on Review. For workarounds that exclude each other, such as Alexa-only brightness behavior, isolate them on a controller-specific bridge instead of assuming Multi-Controller can satisfy both at once.

Guards on an empty filter, and the preview before you create

Switching filter type also clears pattern strings that no longer apply, so a leftover value cannot leak into the Domain or Area matcher. Server Mode forces an entity ID pattern; the screen warns you to narrow it to exactly one entity, and the first entity becomes the primary. The upstream bridge schema technically allows one Server Mode node up to ten device endpoints, but more than one is experimental-in-Stable — the Wizard's "exactly one" guidance is the safer product path.

The full Manual Editor shows a Filter Preview and reminds you how labels are meant to be used. Confirm the expected entity count, the vacuum, large-match and unsupported-domain warnings, and whether a sensitive device slipped in. If the result is zero, do not blank the include and hope for the best — go back to the area, label or pattern identifiers and fix them one at a time.

Ports, bulk creation by area, the full schema, and importing a bridge you already have

The Wizard calls api/matter/next-port when it opens, falling back to 5540 if that fails. The Manual Create page scans used ports from 5540 upward and takes the first free one. Area Setup fetches the next port once, then increments it for every area it creates. Every bridge port has to be unique; the full editor blocks Save when the port is already used by another bridge.

The PreflightPanel calls api/network and sorts the diagnostic results into passed, warnings and failed. Every problem expands into a "How to fix": where an add-on option exists it shows that option and the matching container flag, and reminds you to restart the add-on after changing a start option; everything else has to be fixed on the host or the network. Preflight is advisory and does not block Create on its own, so treating a fail as something to fix first is your own decision to make.

flowchart TD
  A["Planning a new bridge's port"] --> B{"Will this bridge be
commissioned to Alexa?"}
  B -->|"yes"| C{"Is port 5540
already taken?"}
  C -->|"no"| D["Set port to 5540.
Create this bridge first"]
  C -->|"yes"| E["Reassign the bridge holding
5540, only if it is not
already commissioned"]
  B -->|"no"| F["Accept the next free port
the Wizard or editor offers"]

1. Step 1

   Allocate 5540 first

   If any bridge is meant for Alexa, create it first and give it port 5540. Let every other bridge take the automatic free port.

2. Step 2

   Read the pass/warn/fail summary

   Wait for the network preflight to finish on the Wizard's Review stage. No data, or a server you cannot reach, must not be read as everything passing.

3. Step 3

   Expand every How to fix

   Use the advice to tell an add-on option, a container flag and a host or network problem apart; do not copy an example interface name blindly.

4. Step 4

   Rerun Review after you fix it

   When a start option is involved, restart the service completely, then go back to the Wizard and fetch the diagnostics again. Create only once you confirm the errors are gone.

Area Setup: several bridges by HA area, in one pass

Area Setup loads from api/matter/areas/summary every area holding at least one entity that is "enabled, not currently unavailable, and in a domain the API supports"; the entity count on each card uses the same eligibility rule, with up to four main domains shown. You can Select All or Clear, tick areas one by one, and pick one of the four controller profiles. Areas that fail the eligibility rule are left out entirely.

On create, each area becomes one area matcher with no exclude, auto battery/humidity/pressure mapping enabled by default, and then the controller profile flags merged in. The program creates them in order, with ports counting up from the next free port; even if one fails, the remaining areas still go ahead, and the end shows separate success and error entries plus a partial summary.

1. Step 1

   Tidy your Home Assistant areas first

   In HA, confirm the entities you want to expose are in the right area, and that the area holds no sensitive device that should stay private. Area Setup has no per-entity exclude of its own.

2. Step 2

   Pick a controller profile

   Choose your main controller or leave it unselected, remembering that this only merges flags. If Alexa needs 5540, do not create a batch of bridges that all expect to be commissioned to Alexa first.

3. Step 3

   Select a small number of areas

   Tick one or two to begin with and read the entity and domain summary. Select All can create a lot of bridges at once, which a low-resource host especially has to avoid.

4. Step 4

   Press Create Bridges and watch the progress

   The progress bar updates per area. Do not leave the page or click again; each result is listed as a success or an error.

5. Step 5

   Handle partial results

   Record the failed areas and a redacted error summary; go back to Bridges and cross-check the ones that succeeded, so a re-run does not create duplicates. After fixing the port or the filter, redo only the failed items.

Manual Setup: the full form and JSON

The Manual Create page can also start from one of the ten templates, then hands over to the bridge config editor. It opens on the Fields Editor and you can switch to the JSON Editor; both validate against the same schema. The page also shows the Filter Preview and Bridge Icon Upload. The icon can be a built-in type, or a custom image handled through the admin interface — never use an image that carries a street address or identifying information.

The editor shows warnings for Server Mode, for several entities, for Vacuum OnOff, and for Auto Force Sync combined with Auto Composed Devices. None of these is forbidden outright, but read the warning through before you save. The icon is held by a separate component when you switch between Fields and JSON; while editing JSON, still avoid pasting any secret — BridgeConfig itself should never contain an HA token or pairing data.

Importing an existing bridge: preview first, decide about overwrite second

Besides the three create workflows, the Import dialog on the Bridges page reads a bridge export JSON. Once you pick the file, the frontend parses it and calls the preview API first; if parsing or the preview fails, it only shows an error and imports nothing. The preview lists the export time, the format version, each bridge name, port and filter rule count, and whether it already exists.

Every previewed item is ticked by default, and you can Select All, Select None or clear them one at a time. overwriteExisting defaults to false; while it is off, an item that already exists is skipped rather than quietly overwritten. Before turning overwrite on you need a current full backup, and you should first compare the port, the filter, the identity suffix and the feature flags. An older format shown as migrated together with its source version means it was converted to the current format on import — not that every difference in meaning has been checked by a person.

1. Step 1

   Verify where the file came from

   Use only an export JSON you control and have scanned yourself. Do not import a configuration handed to you in a chat or on a forum, and do not attach an export to anything public.

2. Step 2

   Read the whole preview

   Cross-check the exported time, the source format, the bridge names, ports and filter rules. When you see an older-version migration, save a separate backup first and compare item by item.

3. Step 3

   Untick what you do not need

   Untick any bridge that already exists or does not fit your port plan. Select None takes you safely back to zero selected, and the Import button is disabled at that point.

4. Step 4

   Choose overwrite carefully

   Keep the default off, so existing items are skipped. Turn it on only when you mean to replace them, have a backup, and understand the effect on identity and on the filter.

5. Step 5

   Cross-check the result after the import

   The dialog summarizes how many were imported, skipped and failed. Open each bridge's details and check the status and the device count; a partial success is not a reason to press Import on the whole batch again.

The symptoms that come up, and what actually causes them

Where to go from here