Turn "which entities get bridged" into a rule you can predict

The Filter Engine decides whether an entity in the Home Assistant registry is even eligible for this one bridge to build a Matter endpoint from. It is not the room filter inside a controller, and it changes nothing in Home Assistant itself — it only controls the candidate set for the bridge you have open. Include every entity outright in a house with lights, diagnostic sensors, scripts and integrations from several brands, and you tend to push out things you never meant to expose, or that no controller supports anyway.

The dependable order is: write the include conditions first, then the always-exclude conditions, and check the result in the Preview last. The whole decision can be written as one sentence: an entity is a candidate when Include is empty or evaluates true, and nothing in Exclude matches it. An empty Include array places no restriction at all; only a non-empty Include is evaluated against includeMode. Exclude, on the other hand, always removes an entity the instant any single rule inside it matches — there is no ALL setting for Exclude.

includeMode applies to Include only, and defaults to any when you leave it out. Exclude calls the matcher test with no mode at all, so it always behaves as any. ALL does not mean the several values of one matcher are ANDed together — each row still carries exactly one type and one value, and ALL requires every row, not every value, to succeed.

Hidden entities are a second, separate layer of the decision. Even when a matcher matches, an entity Home Assistant marks as hidden is skipped by default; it only comes in once the bridge's includeHiddenEntities feature flag is turned on. An entity marked disabled in Entity Mapping should likewise not be treated as a usable endpoint. The filter, the hidden flag, and the Entity Mapping disable are three separate switches — do not run them together as if they were one.

flowchart TD
  A["Entity in the Home Assistant registry"] --> B{"Is Include empty?"}
  B -->|"yes, treated as included"| E{"Does any Exclude rule match?"}
  B -->|"no"| C{"Include Mode ANY or ALL satisfied?"}
  C -->|"no"| X["Not a candidate for this bridge"]
  C -->|"yes"| E
  E -->|"yes"| X
  E -->|"no"| F{"Hidden entity, and includeHiddenEntities is off?"}
  F -->|"yes"| X
  F -->|"no"| G["Candidate entity for this bridge"]

Sixteen matcher types, and which one you actually want

Every type below checks exactly one field, and the exact behavior differs more than the short names suggest — the difference between a substring and a wildcard match, for instance, decides whether a rename quietly breaks your rule.

Regex, labels, and the any-field haystack

The label matchers first look the value up by display name, case-insensitively, and turn it into a label_id when they find one. When they do not, the code normalizes your input: it strips combining diacritics, lowercases, turns every non-alphanumeric character into an underscore, and clears leading and trailing underscores. The most reliable route stays copying the real label_id from Filter Reference in the sidebar, so a renamed label cannot change what the rule does.

The haystack for any_field_regex is one line of key=value fields joined by spaces. You can express OR with alternation, and require one entity to satisfy several fields at once with a positive lookahead — documented as (?=.*domain=light)(?=.*area=demo_room). Label arrays are joined with commas, so test any boundary construct against your real slugs. The engine builds the rule with new RegExp(pattern) and adds no case-insensitive flag; cover casing explicitly in the pattern when you need it.

flowchart TD
  A["An invalid regex pattern"] --> B{"Where is this matcher used?"}
  B -->|"Include, mode all"| C["This row never matches"]
  C --> D["The whole Include ALL fails"]
  B -->|"Exclude"| E["This row never matches"]
  E --> F["The exclude guard you expected silently does nothing"]

Build the rule, then trust the Preview over your memory

1. Step 1

   Open the bridge edit page

   Select the target bridge on Bridges and open Edit. Write down the current Include, Exclude and includeMode first, and do not change feature flags at the same time.

2. Step 2

   Choose the Include Mode

   Under Include or exclude entities, set Include Mode to any or all. ANY suits "any one of these categories"; ALL suits "all of these conditions at once."

3. Step 3

   Add Include rows one at a time

   Use the Include add control, then pick a Type and fill in a Value for each row. Copy label, area, and platform values from Filter Reference in the sidebar rather than guessing them from the displayed text.

4. Step 4

   Add Exclude guards

   Put the categories you should not expose into Exclude — a category of diagnostic, say, or an explicit test-entity pattern. A single Exclude match beats Include.

5. Step 5

   Check Preview Matching Entities

   Wait about 800 ms for the automatic refresh, or press Preview Matching Entities. Check the count, the domain chips, the names, and the entity_ids; the preview lists at most the first 100 rows, and total is the real number of matches.

6. Step 6

   Save and verify

   Press Save only once the preview matches what you expect and the form is valid. Then check the actual endpoints and the failed entities back on Bridge / Devices — do not treat "the controller shows it immediately" as your only success criterion.

Filter Preview runs the same matcher logic against the current Home Assistant entity, device, state, and label registries, and sorts the result by entity_id. It also flags a large entity count, an unsupported domain, or a vacuum situation; those hints are planning information and never rewrite the configuration on their own.

Rules that stay maintainable

One configuration object, three separate jobs

Bridge settings carry three kinds of responsibility at once: the filter you just finished, the runtime parameters that pin the Matter node's identity and session behavior, and the workarounds you switch on for one controller's particular quirk. These fields can change endpoint identity, cluster composition, sync frequency, or the meaning of a control command — so get a working baseline bridge first, then change one related option at a time.

flowchart TD
  A["One BridgeConfig"] --> B["Candidate filter
include / exclude / includeMode"]
  A --> C["Runtime identity and session
serialNumberSuffix, uniqueIdSuffix,
stableIdentity, sessionMaxAgeHours"]
  A --> D["Controller-specific workarounds
coverSwapOpenClose,
alexaPreserveBrightnessOnTurnOn, vacuumOnOff"]

The schema sets additionalProperties: false on the top level and on the filter, so a misspelled field is not a comment you can ignore — it is a validation error. The feature flag schema does not spell out additionalProperties false, but you still should not add keys the source never defines. The form hands the icon to a separate Bridge Icon component, so it is kept when you switch between the form and JSON views.

Visibility, composition, sync, and naming flags

A feature flag is a workaround sized for one controller, not a switch to turn on everywhere

Controller profiles are a starting suggestion, not a live guarantee

Controller profiles are a suggested combination applied at create time, not a running compatibility check. Apple, Google, and Amazon Alexa differ in what Matter Hub recommends turning on for each, and the source is explicit that these differences are not interchangeable:

Once a profile is applied it is still an ordinary BridgeConfig, and you still have to verify it against your actual controller and device types — the profile name is a starting point, never a promise.

Five mechanisms, three different layers — do not turn them all on to fix one symptom

flowchart TD
  R["Something about a controller connection looks wrong"] --> Q1{"HA entity_id renamed?"}
  Q1 -->|"yes"| M1["stableIdentity anchors endpoint id to unique_id"]
  R --> Q2{"A subscription dropped entirely?"}
  Q2 -->|"yes"| M2["fastSessionRecovery re-announces after 5s, not 60"]
  R --> Q3{"Subscribed, but silent for about 45 minutes?"}
  Q3 -->|"yes"| M3["wedgeWatchdog rotates that one session"]
  R --> Q4{"A session is simply older than your limit?"}
  Q4 -->|"yes"| M4["sessionMaxAgeHours rotates by age, 0 = off"]

These mechanisms work at different layers: identity gives device continuity across an HA rename; session rotation, fast recovery, and the watchdog deal with the Matter connection and its subscriptions; autoForceSync deals with pushing state, which is a fifth mechanism again and not drawn above. Do not turn them all on and then try to work out which one helped. A home bridge serving several controllers should especially start from neutral settings, with controller-specific workarounds split onto their own bridge.

Match the smallest setting to the confirmed symptom

Switch safely between the field editor and raw JSON

1. Step 1

   Back up the current configuration

   Export from the existing bridge first, or record the non-secret settings some safe way, and confirm the persisted data has a backup you can restore from. Never paste identifying data from a live environment into a document or a ticket.

2. Step 2

   Open Edit and switch to JSON

   On the bridge edit page, press the editor toggle in the top right to move from the Fields Editor to the JSON Editor. Keep the required name, port, filter.include, and filter.exclude.

3. Step 3

   Add only keys the schema defines

   Check the structure with documentation placeholders, for example "countryCode": "<COUNTRY_CODE>". Write booleans as true/false, and the debounce and session-age fields as numbers — never a number inside quotes.

4. Step 4

   Read the live validation output

   Fix errors in JSON syntax, required fields, enums, minimum and maximum values, and additional properties. If another bridge already uses the port, the custom validation blocks the save as well.

5. Step 5

   Switch back to the form and cross-check

   Confirm the fields still show the values you expect. Check in particular that vacuumOnOff is explicitly true only where Alexa needs it, and that the icon has been kept by its own separate control.

6. Step 6

   Save one set of changes at a time

   After you press Save, verify at the layer that flag belongs to: for identity, check continuity across a rename; for session, check Health; for cover, fan, and vacuum, check a single test device. An identity suffix that only applies after a restart needs a downtime window arranged first.

The pitfalls that actually happen, filter and bridge settings both

Filter Engine and bridge settings, the questions that recur

Where to go from here