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"
}

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.