Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Alpha Features Guide

This guide covers features available in the Alpha version of Home-Assistant-Matter-Hub.

Installing the Alpha Version

Home Assistant Add-on

  1. Add the repository: https://github.com/riddix/home-assistant-addons

  2. Install Home-Assistant-Matter-Hub (Alpha) from the Add-on Store

  3. The Alpha add-on runs independently from the stable version

Docker

Use the alpha tag instead of latest:

docker run -d \
  --name home-assistant-matter-hub-alpha \
  --network host \
  -v /path/to/data:/data \
  -e HAMH_HOME_ASSISTANT_URL=http://homeassistant.local:8123 \
  -e HAMH_HOME_ASSISTANT_ACCESS_TOKEN=your_token \
  ghcr.io/riddix/home-assistant-matter-hub:alpha

Features Now in Stable (v2.0.20)

The following features have graduated from Alpha to Stable:

New in v2.0.20:

Previously promoted in v2.0.19:

Previously promoted (v2.0.17/v2.0.18):

Current Alpha Features

Dashboard Landing Page

The application now opens with a dashboard overview instead of the bridges list. The dashboard provides a compact summary of your system at a glance:

The dashboard fetches data from /api/health/detailed and refreshes every 15 seconds.

Bridge Wizard Feature Flags

The Bridge Wizard now has a 5-step flow: Template → Bridge Info → Entity Filter → Feature Flags → Review & Create. The new Feature Flags step lets you enable common flags directly during bridge creation:

When a template is selected, its flags are pre-filled but can be adjusted in this step. All other flags remain available in the full bridge editor after creation.

Entity Autocomplete

All entity ID input fields in the Entity Mapping dialog now use an autocomplete component with search-as-you-type suggestions. This replaces the previous plain text fields where users had to type entity IDs from memory.

How it works:

Affected fields: Entity ID, Humidity Sensor, Pressure Sensor, Battery Sensor, Filter Life Sensor, Cleaning Mode Entity, Power Sensor, Energy Sensor.

Light Transition Time

Matter controllers can send transition times with light commands (brightness changes, color temperature changes, hue/saturation changes). These transition times are now forwarded to Home Assistant as the transition parameter in light.turn_on service calls.

Supported commands:

Unit conversion: Matter uses tenths of a second (e.g., transitionTime: 10 = 1 second). Home Assistant uses seconds as a float. The conversion is transition = transitionTime / 10.

Backward compatible: Transition times of 0 or null are not forwarded, preserving current behavior (instant changes). Only non-zero transition times are included in the HA service call.

Auto Composed Devices (Master Toggle)

Feature Flag: autoComposedDevices (default: false)

A master toggle that automatically combines related Home Assistant entities from the same physical device into Matter endpoints. When enabled, it activates all auto-mapping sub-features at once: battery, humidity, pressure, power, and energy mapping.

For temperature sensors with auto-mapped humidity/pressure/battery, this flag creates real Matter Composed Devices — a BridgedNodeEndpoint parent with separate sub-endpoints for each sensor type. Each sub-endpoint uses its correct Matter device type, which is required for Apple Home, Google Home, and Amazon Alexa to properly recognize and display humidity and pressure readings.

For switches/lights with auto-mapped power/energy, the clusters are added directly to the switch endpoint (flat mapping), since ElectricalPowerMeasurement and ElectricalEnergyMeasurement are valid optional clusters on those device types.

How It Works

The feature operates in two phases during bridge initialization:

Phase 1 — Entity Discovery (BridgeRegistry.preCalculateAutoAssignments)

Before any Matter endpoints are created, the bridge registry scans the full Home Assistant entity and device registry (not just filtered bridge entities) to find related sensor entities that belong to the same HA device (device_id). It searches for:

Sensor TypeHA Domaindevice_classTarget Entity Domains
Batterysensor.*batteryAll domains
Humiditysensor.*humiditysensor.temperature
Pressuresensor.*atmospheric_pressuresensor.temperature
Powersensor.*powerswitch, light
Energysensor.*energyswitch, light

Phase 2 — Endpoint Construction (LegacyEndpoint.create)

When each Matter endpoint is created, the auto-mapping logic runs in a strict order:

  1. Skip check — If this entity was already consumed as a sub-entity (e.g., a humidity sensor already merged into a temperature endpoint), it is skipped entirely. No duplicate Matter endpoint is created.

  2. Auto-assign in order (only if device_id is present and no manual mapping exists):

    • Humidity → Temperature sensor

    • Pressure → Temperature sensor

    • Battery → Any entity (done last so battery goes to the combined sensor, not separately)

    • Power → Switch/Light

    • Energy → Switch/Light

  3. Composed device check — If autoComposedDevices is enabled and this is a temperature sensor with auto-mapped humidity or pressure, a ComposedSensorEndpoint is created instead of a flat endpoint. This produces a BridgedNodeEndpoint parent with separate sub-endpoints:

    BridgedNodeEndpoint (parent)
├── BridgedDeviceBasicInformation + PowerSource (battery)
├── TemperatureSensorDevice (0x0302) sub-endpoint
├── HumiditySensorDevice (0x0307) sub-endpoint
└── PressureSensorDevice (0x0305) sub-endpoint

    Each sub-endpoint has its own HomeAssistantEntityBehavior and reads directly from its own HA entity state.

  4. Flat endpoint fallback — For switches/lights or if autoComposedDevices is not enabled, createLegacyEndpointType() adds the extra clusters directly to the primary endpoint type.

Implementation Details

Flag Wiring (BridgeRegistry)

Each sub-feature check (isAutoBatteryMappingEnabled(), isAutoHumidityMappingEnabled(), isAutoPressureMappingEnabled()) was extended to also check the master flag:

isAutoBatteryMappingEnabled(): boolean {
  return (
    this.dataProvider.featureFlags?.autoBatteryMapping === true ||
    this.dataProvider.featureFlags?.autoComposedDevices === true
  );
}

Power and energy auto-mapping runs unconditionally for switch/light domains (no feature flag gate) because it only applies to domains where it’s always beneficial.

Entity Resolution (BridgeRegistry.findBatteryEntityForDevice, etc.)

All find*EntityForDevice() methods search the full HA registry (this.registry.entities), not the filtered bridge entity list. This is critical because:

Duplicate Prevention

Each auto-assigned entity is tracked in a Set (_usedBatteryEntities, _usedHumidityEntities, etc.). Before creating any endpoint, LegacyEndpoint.create() checks if the entity was already consumed. If so, it’s skipped:

if (
  registry.isAutoBatteryMappingEnabled() &&
  registry.isBatteryEntityUsed(entityId)
) {
  return; // Skip — already merged into another endpoint
}

Matter Cluster Mapping

The auto-assigned entities are passed as effectiveMapping fields to createLegacyEndpointType(), which adds the corresponding Matter server behaviors:

Mapping FieldMatter ClusterServer Behavior
batteryEntityPowerSource (0x002F)PowerSourceServer
humidityEntityRelativeHumidityMeasurement (0x0405)HumidityMeasurementServer
pressureEntityPressureMeasurement (0x0403)PressureMeasurementServer
powerEntityElectricalPowerMeasurement (0x0090)ElectricalPowerMeasurementServer
energyEntityElectricalEnergyMeasurement (0x0091)ElectricalEnergyMeasurementServer

Each server behavior independently subscribes to its source entity’s state changes and updates its Matter attributes accordingly.

Example: Shelly Plug S with Power Monitoring

Home Assistant entities (same device_id):

Without autoComposedDevices (3 separate Matter endpoints):

With autoComposedDevices (1 composed Matter endpoint):

Example: Aqara Temperature/Humidity/Pressure Sensor

Home Assistant entities (same device_id):

Without autoComposedDevices (4 separate Matter endpoints):

With autoComposedDevices (1 composed Matter device with 3 sub-endpoints):

Controller behavior:

ControllerTemperatureHumidityPressureBattery
Apple Home✅✅❌ (unsupported device type)✅
Google Home✅✅✅✅
Amazon Alexa✅ (separate)✅ (separate)?✅

Sources: Apple Support — Matter accessories (lists supported sensor types), matter.js ECOSYSTEMS.md (tested device type matrix).

Configuration

Enable via bridge configuration JSON or the UI:

{
  "featureFlags": {
    "autoComposedDevices": true
  }
}

Or enable individual sub-features selectively:

{
  "featureFlags": {
    "autoBatteryMapping": true,
    "autoHumidityMapping": true,
    "autoPressureMapping": true
  }
}

Note: autoComposedDevices is a pure OR with each sub-flag. It never overrides an explicitly disabled sub-flag — it only adds. If autoComposedDevices: true, all sub-features are treated as enabled regardless of their individual values.

Force Sync for Composed Devices

When autoForceSync is enabled, the periodic force sync now recursively traverses all sub-endpoints of composed devices. Previously, only direct children of the aggregator were synced, which meant sub-endpoints of ComposedSensorEndpoint (temperature, humidity, pressure sensors) were missed during force sync cycles. This fix ensures that all sensor readings within composed devices stay in sync with controllers.

Relevant Source Files

FilePurpose
packages/common/src/bridge-data.tsAllBridgeFeatureFlags type definition
packages/common/src/schemas/bridge-config-schema.tsJSON schema for UI form generation
packages/backend/src/services/bridges/bridge-registry.tsEntity discovery, flag checks, find*EntityForDevice()
packages/backend/src/matter/endpoints/legacy/legacy-endpoint.tsAuto-assign logic, skip-if-used checks
packages/backend/src/matter/endpoints/legacy/create-legacy-endpoint-type.tsEndpoint type construction (flat mapping fallback)
packages/backend/src/matter/endpoints/composed/composed-sensor-endpoint.tsComposed device factory (BridgedNodeEndpoint + sub-endpoints)
packages/backend/src/services/bridges/bridge.tsForce sync logic with recursive sub-endpoint traversal

Live Diagnostics (WebSocket Event Streaming)

Real-time diagnostic event streaming integrated into the Health Dashboard. Emits events for bridge lifecycle changes (start/stop) with more event types planned. Events are streamed via WebSocket to subscribed clients.

How to use:

Event types: bridge_started, bridge_stopped, state_update, command_received, entity_error, session_opened, session_closed, subscription_changed

WebSocket protocol:

// Subscribe
{ "type": "subscribe_diagnostics" }

// Receive initial snapshot
{ "type": "diagnostic_snapshot", "data": { "bridges": [...], "recentEvents": [...], "system": {...} } }

// Receive live events
{ "type": "diagnostic_event", "data": { "id": "diag_1", "timestamp": 1740000000000, "type": "bridge_started", "message": "Bridge started", "bridgeId": "...", "bridgeName": "..." } }

// Unsubscribe
{ "type": "unsubscribe_diagnostics" }

Live Diagnostics Dashboard Improvements

Bridge Cards (v2.1.0-alpha.10+):

Thermostat Auto-Resume Fix

Issue: When a thermostat was off and you asked a voice assistant to “set temperature to 20°C”, it only worked if the new temperature was different from the current setpoint. If already at 20°C, nothing happened.

Fix: The thermostat now intercepts all setpoint writes via overridden class setters, not just value changes. When a write occurs while systemMode is Off, the device automatically resumes to Heat/Cool mode.

Works with: Google Home, Alexa, Apple Home

Technical details:

Vacuum “Docked” State Fix

Issue: Vacuums showed “Paused” instead of “Docked” when idle and charging in their dock.

Fix: Corrected the operational state mapping logic in VacuumRvcOperationalStateServer. Now properly detects charging state for vacuums that report idle while docked and charging (Ecovacs, some Roborock models).

Detection logic:

Controller behavior:

Memory Leak & Stability Fixes

Issue: Long-running bridges could experience Out-Of-Memory (OOM) errors due to improper endpoint disposal.

Fix: Fixed endpoint cleanup in disposal methods:

Battery Sensor Log Spam Fix

Issue: Logs were flooded with “No battery entity found” messages for devices without battery sensors.

Fix:

The following sections document features that are now in stable but provide detailed usage instructions.

1. Full Backup & Restore System

Create complete backups of your configuration as ZIP files, including all bridges and entity mappings.

Features:

Using Backup:

  1. Go to the Bridges page

  2. Click Download Backup to create a ZIP backup

  3. To restore, click Restore from Backup and select a ZIP file

  4. Preview the contents and select which bridges to restore

  5. Choose options (overwrite existing, include mappings)

  6. Click Restore

2. Filter Preview

Preview which entities will match your filter configuration before saving.

Features:

3. Smoke/CO Detector Support

Binary sensors with smoke, carbon_monoxide, or gas device class are now mapped to Matter Smoke CO Alarm devices.

Supported Device Classes:

4. Dark Mode Toggle

Switch between light and dark themes directly from the UI.

Using Dark Mode:

5. Device List Sorting

Sort the endpoint/device list by different criteria.

Sort Options:

6. Health Monitoring Dashboard

The Health Dashboard provides real-time monitoring of your bridges and fabric connections.

Accessing the Dashboard:

Features:

2. Automatic Bridge Recovery

Failed bridges are automatically restarted to ensure maximum uptime.

How it works:

Recovery Status Indicators:

3. Bridge Wizard

The Bridge Wizard simplifies creating multiple bridges with automatic configuration.

Using the Wizard:

  1. Go to the Bridges page

  2. Click the Wizard button

  3. Follow the guided steps:

    • Enter bridge name

    • Select entities using filters

    • Port is automatically assigned

  4. Create multiple bridges in one session

  5. Review and confirm before creation

Automatic Port Assignment:

4. Water Valve Support

Control water valves through Matter.

Supported Features:

Controller Support:

5. Health Check API

REST API endpoints for monitoring and Kubernetes integration.

Endpoints:

EndpointDescription
GET /api/healthBasic health status
GET /api/health/detailedDetailed status with bridge info
GET /api/health/liveKubernetes liveness probe
GET /api/health/readyKubernetes readiness probe

Example Response (/api/health):

{
  "status": "healthy",
  "version": "2.0.0-alpha.1",
  "uptime": 3600,
  "services": {
    "homeAssistant": { "connected": true },
    "bridges": { "total": 2, "running": 2, "failed": 0 }
  }
}

6. WebSocket Live Updates

Real-time updates without polling.

Connecting:

const ws = new WebSocket('ws://your-hamh-host:8482/api/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update:', data);
};

Event Types:

7. Entity Mapping Customization

Override Matter device types and names per entity.

Use Cases:

Tips for Alpha Testing

1. Backup Your Data

Before upgrading to Alpha, backup your configuration:

# Docker
cp -r /path/to/data /path/to/data-backup

# Home Assistant Add-on
# Data is stored in /config/home-assistant-matter-hub

2. Run Alpha Separately

You can run both Stable and Alpha versions simultaneously:

3. Reporting Issues

When reporting Alpha issues, please include:

4. Common Alpha Issues

Bridge not starting:

Entities not appearing:

Controller not connecting:

Configuration Tips

Optimal Bridge Setup

{
  "name": "Living Room",
  "port": 5540,
  "filter": {
    "include": [
      { "type": "area", "value": "living_room" }
    ],
    "exclude": [
      { "type": "entity_category", "value": "diagnostic" },
      { "type": "entity_category", "value": "config" }
    ]
  }
}

Multiple Bridges Strategy

  1. By Area: One bridge per room/area

  2. By Controller: Separate bridges for different ecosystems

  3. By Device Type: Group similar devices together

Performance Recommendations

Reverting to Stable

If you encounter issues with Alpha:

  1. Stop the Alpha add-on/container

  2. Install the Stable version

  3. Your paired devices should reconnect automatically

  4. Some new features may not be available

Acknowledgments

Special thanks to the community members who help improve this project by reporting issues and providing detailed information:

Getting Started
Bridge Configuration
Guides
Migration from t0bst4r to RiDDiX Fork