Device mapping 2: sensors and energy
Use the full Stable 2.0.55 matrix to read sensor, binary_sensor and weather, covering temperature and humidity, pressure, air quality, safety detection, power, energy, battery, utility meter and EVSE, and tell the difference between a controller that will not display a value and source data that is wrong.
A sensor value that builds is not a value the controller will show
A sensor entity is not like a light, which has only a few obvious controls. A Home Assistant sensor can be a temperature, a pressure, an illuminance, a flow rate, a pollutant, instantaneous power, accumulated energy or a battery percentage; a binary_sensor can be a door or window, motion, occupancy, smoke, a leak or a plain boolean state. Matter Hub picks the endpoint from device_class first, and the controller then decides whether it shows that device type and cluster.
That produces three different outcomes. Matter Hub skips an unsupported device class outright; or the endpoint is healthy but the controller does not support that type; or the controller has a tile and shows an implausible number because the source unit, state or linked entity is wrong. Work out which layer you are in before you start troubleshooting.
electrical_utility_meter is an opt-in Matter 1.4 override inside Stable, and the pinned sources do not mark it experimental; controller support is listed separately, and you cannot derive it from the release channel or the specification version.Safety sensors only give you notifications and automation signals. They do not replace the smoke, gas, leak or freeze protection equipment that regulations require. The energy and EVSE types likewise only bridge Home Assistant states and commands; they are not billing-grade metering and not a charging safety controller.
Where sensor, binary_sensor and weather come in
| domain | Automatic result | If it does not match |
|---|---|---|
sensor | Maps to a measurement or energy endpoint by device_class; some capabilities then depend on the mapping. | An unknown device_class is logged as an entity warning and skipped; with no class at all, it does not guess either. |
binary_sensor | Picks Contact, Motion, Occupancy, Smoke/CO or a plain OnOff Sensor from device_class. | An unknown class falls back to OnOff Sensor; it never becomes a safety alarm on its own. |
weather | WeatherDevice combines the current temperature, humidity, pressure and whichever other attributes are available. | A controller may show only some of them; weather is not a general Matter surface for forecast data. |
On a sensor, temperature builds a Temperature Sensor; humidity and moisture both map to Relative Humidity, and the second suits the 0–100% soil-moisture meaning; illuminance maps to Light Sensor; pressure and atmospheric_pressure map to Pressure; volume_flow_rate maps to Flow. PM2.5, PM10 and CO2 are not override names in the Entity Mapping picker, but the v2.0.55 automatic path still has endpoint implementations for them; the matrix in this chapter lists the complete override set the manifest defines, so do not confuse automatic support with the override options.
On a binary_sensor, door, garage_door, opening and window become Contact; motion / moving become Motion; occupancy / presence become Occupancy; smoke becomes Smoke Alarm; carbon_monoxide / gas become CO Alarm. cold and moisture use the detector contact variants. battery_charging, light, plug, power and running use OnOff Sensor; the rest, including battery, connectivity, heat, lock, problem, safety, sound, tamper, update and vibration, use Contact.
battery / battery_level attribute or a linked batteryEntity, a Power Source is added wherever a matching variant exists. When a mains-powered device wrongly reports a battery, use disableBatteryMapping so the controller does not show a fake low battery indefinitely.Temperature, humidity, pressure, illuminance and flow
A Temperature Sensor can use humidityEntity, pressureEntity and batteryEntity to build a flat multi-measurement endpoint. v2.0.55 puts the Temperature, Humidity and Pressure device types all into the descriptor, which gives controllers such as SmartThings a better chance of recognizing each one. The available combinations are temperature with humidity, temperature with pressure, temperature with humidity and pressure, and each of those with a battery.
The bridge flags autoHumidityMapping, autoPressureMapping and autoBatteryMapping can find linked entities on the same HA device; autoComposedDevices may build a composed device structure instead. These flags are in Stable at maturity stable, but whether the automatic link is correct depends on the HA device registry. Similar names do not mean the same piece of hardware, so cross-check which device an entity belongs to, and its unit, before you save.
| override | What the measurement means | Controller notes from the pinned matrix |
|---|---|---|
temperature_sensor | Temperature | Apple, Google, Alexa and Aqara yes. |
humidity_sensor | Relative humidity, or a percentage moisture value | Yes on all four main controllers. |
pressure_sensor | Pressure / atmospheric pressure | Google and Aqara yes; Apple and Alexa no. |
light_sensor | Illuminance | Apple, Google and Alexa yes; Aqara unknown. |
flow_sensor | Volume flow rate | Google yes; Apple and Alexa no; Aqara unknown. |
Before data reaches Matter it still has to match the unit meaning of the HA device class. If a temperature looks an order of magnitude off, a humidity falls outside 0–100, or a pressure is implausible, fix the source integration or the template sensor first; do not just relabel it with an override.
The full air-quality and rare-pollutant table
Air quality is not a single cluster. AQI, CO, CO2, TVOC, NO₂, O₃, formaldehyde, radon, PM1, PM2.5 and PM10 each measure something different. The complete air-related set in the Matter override picker is below; even when a controller does not display one of them, the endpoint can still be healthy.
| override | Recommended source | Controller support snapshot |
|---|---|---|
air_quality_sensor | The AQI device class | Apple no; Google, Alexa and Aqara yes. |
carbon_monoxide_sensor | A numeric CO measurement, not a binary alarm | Apple partial (an alarm rather than a reading), Google no, Alexa partial, Aqara yes. |
tvoc_sensor | volatile_organic_compounds or parts | Apple and Google no; Alexa partial; Aqara yes. |
nitrogen_dioxide_sensor | NO₂ | Apple and Google no; Alexa partial; Aqara yes. |
ozone_sensor | O₃ | Apple and Google no; Alexa partial; Aqara yes. |
formaldehyde_sensor | Formaldehyde (HCHO); usually needs an explicit override | Apple and Google no; Alexa partial; Aqara yes. |
radon_sensor | Radon | Apple and Google no; Alexa partial; Aqara yes. |
pm1_sensor | PM1 | Apple and Google no; Alexa partial; Aqara yes. |
carbon_monoxide_sensor, which carries a CO value, is not the same as smoke_co_alarm, which detects a dangerous condition. The first reports a concentration; the second reports an alarm event. Forcing a concentration sensor into an alarm can give you the wrong alarm semantics, and turning a binary smoke detector into a reading loses the alerting display.
Contact, motion, occupancy, smoke, leak and weather detection
| override | Suitable state | Key controller support |
|---|---|---|
contact_sensor | Open / closed, in contact / separated | Apple, Google, Alexa and Aqara yes. |
motion_sensor | Momentary motion / PIR | Yes on all four main controllers. |
occupancy_sensor | Room occupancy / presence | Apple partial; Google, Alexa and Aqara yes. |
smoke_co_alarm | A binary smoke or CO alarm | Apple, Alexa and Aqara yes; Google no. |
water_leak_detector | A water leak | Apple, Alexa and Aqara yes; Google no. |
water_freeze_detector | Freezing risk | Aqara yes; Apple, Google and Alexa no. |
rain_sensor | Rainfall | Aqara yes; Apple, Google and Alexa no, and Alexa may reject this newer type. |
A Smoke/CO Alarm can use the mapping's faultEntity so that a problem or safety binary sensor on the same device drives the hardware fault alert; that fault entity is not necessarily absorbed, and it can keep its own endpoint. This is a device fault signal, not an active alarm. Choose the wrong one and the controller treats a maintenance problem as a fire, or the other way round.
Door, window and motion sensors need no control commands, so verify them with read-only state changes. Do not create a real hazard in order to test a leak or smoke endpoint; you can use documented test entities in a Home Assistant development or test environment, but this chapter provides no data from a live environment.
Power, energy, battery, utility and EVSE
The power, energy, voltage and current device classes map to electrical_meter by default, because the pinned sources say Google and SmartThings can display an Electrical Meter. electrical_sensor is the legacy SolarPower alias; solar_power is for generation. Choosing consumption or generation has to match the sign convention and the meaning of the source.
| override | What it is for | Maturity / controller caveat |
|---|---|---|
electrical_meter | A consumption device for power, energy, voltage and current | stable; Google yes, Apple and Alexa no, Aqara unknown; the source note says SmartThings can display it. |
electrical_sensor | The legacy SolarPower type | stable; Apple and Google no, Alexa and Aqara unknown. |
solar_power | Generation | stable; Apple and Google no, Alexa and Aqara unknown; the source note says SmartThings can display it on its own. |
electrical_utility_meter | Matter 1.4 Meter Identification plus the measurement clusters | Opt-in inside Stable, and not marked experimental by the sources; Apple, Google and Alexa no, Aqara unknown, SmartThings yes. |
battery_storage | Storage with charge and discharge power or energy; a plain percentage is a lighter battery source instead | stable; Aqara yes, no on the other three main platforms. |
evse | Electric vehicle supply equipment | stable; Aqara yes, Apple, Google and Alexa no; a bridged EVSE can break Alexa recognition, so keep it off an Alexa bridge. |
An Electrical Meter can fold powerEntity, energyEntity, voltageEntity and currentEntity into the same endpoint. A Utility Meter can also carry meter serial and point of delivery fields; this site uses text placeholders only and puts no real identifying data anywhere. Battery Storage becomes a fuller ESS once you add batteryPowerEntity and batteryEnergyEntity; cross-check the charge and discharge directions against the source definition.
EVSE can carry both state and control, but controller support is a clear limit. Do not treat a Matter tile as electrical protection, load management or a basis for billing; any remote start or stop must follow the safety rules of the charging equipment and of the installation site.
Build a sensor mapping you can verify
Confirm the device class and the unit on the HA entity page
Go to Settings → Devices & services → Entities, confirm the source is a sensor, a binary_sensor or weather, and note the device class, the unit and the normal range. Documents use placeholders such as
sensor.example_temperatureonly.Look at the automatic result in Devices
Search for the entity and confirm first whether it has already been mapped automatically, composed or skipped. If it shows an unsupported device class, fix the HA source first rather than rushing to apply an override whose meaning does not fit.
Cross-check the linked entities
If you add a humidity, pressure, battery or power measurement, confirm they belong to the same physical device and that the units are compatible. Add one link at a time, so you can always tell which value caused the problem.
Pick an override and read the controller caveat
Override only when the automatic type does not fit and the meaning is unambiguous. For rare types such as utility meter, freeze, rain and EVSE, accept up front that a controller may not display them at all.
Verify the endpoint on the bridge details page
Confirm there is no failed entity, and compare the value Matter Hub shows against Home Assistant. Observe safety detection read-only; do not create smoke, a leak or any other real hazard.
Verify in the controller UI last
When a controller shows nothing, go back to the support matrix in this chapter. If it says no or unknown, keep HA as the primary view rather than commissioning the device again and again.
Troubleshooting sensors and energy
The sensor is skipped
Look at the entity warning and the device class. v2.0.55 skips an unknown sensor class rather than guessing; building an HA template sensor with the correct device class and unit is safer than forcing the wrong Matter type.
A binary sensor turns into a plain On/Off
An unknown or unset binary_sensor class falls back to OnOff Sensor. If it really is a door, motion, occupancy or smoke sensor, fix the device class in HA first, then look at the endpoint again.
Only one of temperature, humidity and pressure shows
Confirm the mapping's humidityEntity / pressureEntity have values and are available, and whether the descriptor lists more than one device type; then check whether the controller supports that measurement. Apple and Alexa are no for pressure.
The controller shows a fake low battery
If the source is a mains-powered device that wrongly reports a battery, use
disableBatteryMappingon that entity. Confirm first that a real battery sensor has not actually failed.Power and energy values are mixed together
Check the device class for W and for the accumulated energy unit, and confirm powerEntity and energyEntity have not been swapped. Do not guess from the name; go by the HA attributes and the statistics semantics.
Alexa breaks after commissioning because of EVSE or a newer detector
Exclude thinly supported types such as EVSE, rain and freeze from the Alexa-only bridge, then watch whether it recovers. Do not delete other healthy fabrics over it; locate the problem with the smallest possible filter change first.
FAQ
Does weather send a full forecast to a Matter controller?
Why does a moisture sensor map to humidity?
Can a CO sensor and a Smoke/CO Alarm be swapped?
Why can electrical_utility_meter not be treated as broadly supported?
Can I change a sensor the controller does not support into a contact sensor?
Stable 2.0.55 pinned sources
- The complete HomeAssistantDomain enum
- The complete override and controller support matrix
- sensor: the automatic device class mapping
- binary_sensor: the automatic mapping
- The weather endpoint implementation
- Pinned Add-on mirror
Every source is pinned to an exact commit. What a platform displays can change with controller firmware and app updates; this chapter states only the support snapshot you can verify inside pinned v2.0.55.