Skip to main content

Mapping Blueprints

This page provides ready-to-use mapping examples for complex device setups. You can use these as reference when configuring entity mappings in the HAMH UI or when creating mapping profiles for import.

Composed Temperature + Humidity + Pressure Sensor​

Combines a temperature sensor with related humidity and pressure sensors into a single Matter composed device. Each sensor appears as a proper sub-device in Apple Home, Google Home, and Alexa.

Requirements: Enable the autoComposedDevices feature flag on the bridge.

{
  "entityId": "sensor.living_room_temperature",
  "humidityEntity": "sensor.living_room_humidity",
  "pressureEntity": "sensor.living_room_pressure",
  "batteryEntity": "sensor.living_room_battery"
}

With Power Monitoring​

If your sensor hub also reports power consumption:

{
  "entityId": "sensor.living_room_temperature",
  "humidityEntity": "sensor.living_room_humidity",
  "pressureEntity": "sensor.living_room_pressure",
  "batteryEntity": "sensor.living_room_battery",
  "powerEntity": "sensor.living_room_power",
  "energyEntity": "sensor.living_room_energy"
}

Composed Sub-Entities​

Group arbitrary Home Assistant entities under a single Matter device. Set composedEntities on the primary entity's mapping and each listed entity becomes a sub-device of the primary. The sub-entities are absorbed into the composed device and stop appearing as standalone Matter devices.

Unlike auto-mapping, which only pulls in humidity/pressure/battery/power sensors on the same HA device, this lets you pick any entities you want, and they do not need to match the bridge filter. You choose them from the full HA registry in the UI.

Requirements: Enable the autoComposedDevices feature flag on the bridge. Each sub-entity may set a matterDeviceType to control how it is exposed.

Example, a Hue Motion sensor exposed as one device with occupancy, illuminance, and temperature sub-devices:

{
  "entityId": "binary_sensor.hue_motion_occupancy",
  "composedEntities": [
    { "entityId": "sensor.hue_motion_illuminance", "matterDeviceType": "light_sensor" },
    { "entityId": "sensor.hue_motion_temperature", "matterDeviceType": "temperature_sensor" }
  ]
}

Air Purifier with Sensors​

Maps a fan entity as an air purifier with temperature, humidity, and HEPA filter monitoring.

Requirements: Enable the autoComposedDevices feature flag. Set matterDeviceType to air_purifier.

{
  "entityId": "fan.air_purifier",
  "matterDeviceType": "air_purifier",
  "temperatureEntity": "sensor.air_purifier_temperature",
  "humidityEntity": "sensor.air_purifier_humidity",
  "filterLifeEntity": "sensor.air_purifier_filter_life",
  "powerEntity": "sensor.air_purifier_power",
  "energyEntity": "sensor.air_purifier_energy"
}

Smart Plug with Energy Monitoring​

A switch with real-time power and cumulative energy measurement.

{
  "entityId": "switch.smart_plug",
  "powerEntity": "sensor.smart_plug_power",
  "energyEntity": "sensor.smart_plug_energy"
}

Dimmable Light with Energy Monitoring​

{
  "entityId": "light.kitchen_ceiling",
  "powerEntity": "sensor.kitchen_ceiling_power",
  "energyEntity": "sensor.kitchen_ceiling_energy"
}

Roborock Vacuum with Room Cleaning​

Maps a vacuum with room-specific cleaning buttons and a cleaning mode selector.

{
  "entityId": "vacuum.roborock_s7",
  "cleaningModeEntity": "select.roborock_s7_cleaning_mode",
  "suctionLevelEntity": "select.roborock_s7_suction_level",
  "mopIntensityEntity": "select.roborock_s7_mop_intensity",
  "roomEntities": [
    "button.roborock_s7_clean_kitchen",
    "button.roborock_s7_clean_living_room",
    "button.roborock_s7_clean_bedroom"
  ]
}

Dreame Vacuum Variant​

{
  "entityId": "vacuum.dreame_l20",
  "cleaningModeEntity": "select.dreame_l20_cleaning_mode",
  "suctionLevelEntity": "select.dreame_l20_suction_level",
  "mopIntensityEntity": "select.dreame_l20_water_volume",
  "roomEntities": [
    "button.dreame_l20_clean_kitchen",
    "button.dreame_l20_clean_bathroom"
  ]
}

Valetudo Vacuum​

{
  "entityId": "vacuum.valetudo_robot",
  "valetudoIdentifier": "valetudo_robot",
  "customServiceAreas": [
    { "areaId": 1, "label": "Kitchen" },
    { "areaId": 2, "label": "Living Room" }
  ]
}

Door Lock with PIN Disabled​

Useful when you have multiple locks and only want PIN protection on some.

{
  "entityId": "lock.front_door",
  "disableLockPin": true
}

Cover with Swapped Open/Close​

For covers where Home Assistant reports inverted position values.

{
  "entityId": "cover.garage_door",
  "coverSwapOpenClose": true
}

Using Mapping Profiles​

You can export and import mapping configurations as profiles via the HAMH UI or API:

  1. Export: Go to Bridge Settings → Export Mapping Profile
  2. Import: Go to Bridge Settings → Import Mapping Profile → Select entities to apply

A mapping profile bundles multiple entity mappings into a single JSON file that can be shared between installations.

Profile Format​

{
  "version": 1,
  "name": "My Home Setup",
  "description": "Mappings for all devices",
  "author": "username",
  "createdAt": "2025-01-01T00:00:00Z",
  "domains": ["sensor", "fan", "vacuum", "switch"],
  "entryCount": 4,
  "entries": [
    {
      "domain": "sensor",
      "entityIdPattern": "sensor.*_temperature",
      "humidityEntity": "sensor.*_humidity",
      "pressureEntity": "sensor.*_pressure"
    },
    {
      "domain": "fan",
      "entityIdPattern": "fan.air_purifier*",
      "matterDeviceType": "air_purifier",
      "temperatureEntity": "sensor.air_purifier_temperature"
    }
  ]
}
tip

Entity ID patterns in profiles use glob-style matching. Use * to match any characters within the entity ID.