Detailed guide to ES1 entities in Home Assistant

Airlytix exposes a rich set of entities in Home Assistant. This page explains what the main entities are, how the Good/Fair/Poor states work, and how to use the readings in daily life.

How ES1 decides Good, Fair, and Poor

ES1 combines raw sensor readings into simple text states so you can understand air quality at a glance.

• For each key metric (temperature, humidity, CO2, PM, VOC, NOx) there is a numeric sensor and a matching text sensor:
  • Temperature ↔ Temperature State
  • Humidity ↔ Humidity State
  • CO2 ↔ CO2 State
  • PM <1µm, PM <2.5µm, PM <4µm, PM <10µm ↔ their PM … State entities
  • VOC ↔ VOC State
  • NOX ↔ NOX State
• Each … State entity is set to good, fair, or poor based on configurable threshold entities in Home Assistant (see Configuration).

There is also a single overall State entity:

• If any per-sensor state is poor, overall State = poor.
• Else if any per-sensor state is fair, overall State = fair.
• Else overall State = good.

The overall State is what most users should put on dashboards or use to drive simple automations.

Indicator light and State

The front indicator light mirrors the overall State:

• good → green light
• fair → orange light
• poor → red light

In Home Assistant you will see:

• Indicator Light – a light entity for turning the front LED on/off and adjusting brightness.
• State – a text sensor with the values good, fair, or poor.

Most people will:

• Use the State entity in automations (for example, notify when State becomes poor).
• Use the Indicator Light entity to adjust brightness or turn the LED off at night.

Temperature and humidity

Temperature

• What it measures: Combined ambient temperature from the SHT4x and SEN55 sensors.
• Typical update rate: Every 30–60 seconds.
• Defaults for states (from firmware):
  • Good: 17–23°C
  • Fair: 13–24°C
  • Below 13°C or above 24°C is considered Poor by default.
• How to use it:
  • Keep most indoor spaces in the Good range for comfort.
  • Use automations to adjust heating/cooling based on temperature or Temperature State.

Humidity

• What it measures: Relative humidity (RH) from the combined humidity sensor.
• Typical update rate: Every 30–60 seconds.
• Defaults for states:
  • Good: 30–60%
  • Fair: 25–70%
  • Outside 25–70% is Poor.
• How to use it:
  • Aim to keep humidity in the Good range to avoid mould (too high) or dryness (too low).
  • Trigger dehumidifiers or ventilation when Humidity State is poor.

CO2

CO2 (Carbon Dioxide)

• What it measures: Indoor CO2 concentration in ppm, from the Sensirion SCD4x sensor.
• Typical update rate: Every 30 seconds.
• Defaults for states:
  • Good: 0–1000 ppm
  • Fair: 1000–1500 ppm
  • Above 1500 ppm is Poor.
• How to use it:
  • Under ~1000 ppm is generally comfortable for most people.
  • If CO2 State is often poor, consider increasing ventilation (opening windows, boosting mechanical ventilation, or running air exchange systems).

Particulate matter (PM)

ES1 exposes four particulate matter channels from the SEN55 sensor:

• PM <1µm Weight concentration
• PM <2.5µm Weight concentration
• PM <4µm Weight concentration
• PM <10µm Weight concentration

Each has a matching … State entity.

For PM2.5 (the most commonly used metric):

• Defaults for states:
  • Good: 0–20 (µg/m³-equivalent)
  • Fair: 20–50
  • Above 50 is Poor.
• How to use it:
  • Watch for spikes during cooking, candles, or outdoor pollution events.
  • Use automations to turn on air purifiers or close windows when PM levels are Poor.

Other PM channels follow similar patterns with wider ranges for larger particles. The exact defaults are configured in the firmware and can be adjusted via configuration entities.

VOC index

VOC (Volatile Organic Compounds) Index

• What it is: A relative index (roughly 1–500) from the SEN55 that tracks changes in VOCs (cleaners, cooking fumes, off‑gassing, etc.).
• How it works:
  • The sensor learns a baseline over time.
  • That baseline maps to a VOC index of about 100.
  • Higher numbers mean more VOCs relative to the recent past; lower numbers mean cleaner air.
• Defaults for states:
  • Good: 0–150
  • Fair: 150–250
  • Above 250 is Poor.
• How to use it:
  • Use VOC as a trigger for local air quality events (e.g. cleaning, painting, cooking).
  • Example automation: if VOC State becomes poor, run an air purifier and send a notification.
  • For more technical detail on how the VOC index is calculated, see the “Advanced” section below.

NOx index

NOX (Nitrogen Oxides) Index

• What it is: A relative index (roughly 1–500) for nitrogen oxides, often produced by gas cooking or combustion.
• How it works:
  • The baseline is mapped to a NOx index of about 1.
  • Higher numbers indicate more NOx compared to that baseline.
• Defaults for states:
  • Good: 0–20
  • Fair: 20–100
  • Above 100 is Poor.
• How to use it:
  • Particularly useful near gas stoves or garages.
  • Example automation: if NOX State becomes poor while you are cooking, boost kitchen extraction or remind yourself to open a window.
  • For more technical detail on how the NOx index is calculated, see the “Advanced” section below.

Light, sound, pressure, and diagnostics

Ambient light and CCT

• Ambient Light (illuminance in lux): helps automate lighting and understand how bright a space is.
• Ambient Light CCT (Correlated Color Temperature in Kelvin): describes whether the light is warm or cool.

Typical usage:

• Use illuminance to turn lights on/off or adjust brightness automatically.
• Use CCT to tune lighting scenes (warm in the evening, cooler white during the day).

Sound level

• Ambient Sound Level (LAeq_1min): average sound level over 1 minute.
• Ambient Sound Level (LApeak_1min): loudest peak within that minute.

These can help you:

• Track how noisy a space is over time.
• Build automations such as quiet‑hours notifications or adaptive soundscapes.

For more detail on how ES1 calculates these A‑weighted sound levels, see the “Advanced” section below.

Pressure and diagnostics

• Pressure: atmospheric pressure in hPa (from DPS310), useful mainly for curiosity or weather dashboards.
• Uptime: how long ES1 has been running since last restart.
• WiFi Signal dB / WiFi Signal Percent: RSSI and a derived percentage, helpful for debugging connectivity.

If you see frequent disconnects or very low WiFi percentages, consider improving WiFi coverage where ES1 is installed.

For details on how to tune the Good/Fair/Poor bands and apply offsets, see the Configuration page.

Advanced: how measurements are calculated

This section is for users who want more detail on how ES1 derives some of its measurements.

Sound level (LAeq_1min and LApeak_1min)

ES1 measures sound using an I²S digital microphone at 48 kHz and converts the raw samples into dB values:

• The microphone sends 24-bit PCM samples to the ESP32.
• Samples are scaled into the range -1.0 to +1.0.
• An IIR filter (a cascade of biquad sections) shapes the signal to approximate the A‑weighting curve used in sound level meters.
• For Ambient Sound Level (LAeq_1min):
  • ES1 squares each filtered sample, accumulates the energy for the measurement duration (60 s), and divides by the number of samples.
  • It converts this average energy to decibels with 10 * log10(energy) and applies calibration terms:
    • A small correction so that a full‑scale sine wave corresponds to 0 dBFS.
    • Microphone sensitivity and reference level to get dB SPL (e.g. relative to 94 dB).
    • An optional manual offset.
  • The result is an A‑weighted equivalent continuous sound level over 1 minute: LAeq_1min.
• For Ambient Sound Level (LApeak_1min):
  • ES1 tracks the maximum absolute value of the filtered samples within the 60 s window.
  • It converts that peak value to dB with 20 * log10(peak) and applies the same calibration terms.
  • The result is the highest A‑weighted peak sound level in that minute: LApeak_1min.

This means short, loud events (slamming doors, dropped objects) will mainly affect LApeak_1min, while LAeq_1min represents the overall noise exposure over the full minute.

VOC index (Sensirion Gas Index Algorithm)

The VOC index is computed by the Sensirion SEN55 using their Gas Index Algorithm.

Key characteristics:

• The raw gas sensor signal is first temperature/humidity compensated on the module.
• The Gas Index Algorithm then maintains a moving baseline over many hours (about a day) to represent “typical” air in that location.
• That baseline is mapped to an index value of roughly 100.
• The algorithm runs on the microcontroller and outputs an index between about 1 and 500:
  • Values above 100 mean VOC levels higher than the recent baseline (for example from cooking, cleaning products, or off‑gassing).
  • Values below 100 mean cleaner air than the recent baseline (for example after strong ventilation or filtration).
• The algorithm adapts its gain based on recent events so that both small and large VOC changes remain visible.

Important implications:

• The VOC index is relative, not an absolute concentration (like mg/m³). It is best used to detect changes and trigger local actions rather than to compare different buildings.
• The index needs time to learn the environment. Expect it to stabilise over the first hours to days after installation or major changes.

NOx index

The NOx index from the SEN55 is built on a similar Gas Index Algorithm but tuned for oxidising gases such as nitrogen oxides.

• The baseline is mapped to a NOx index of about 1.
• The output range is again roughly 1–500:
  • Values close to 1 indicate low NOx levels, comparable to fresh outdoor air.
  • Higher values indicate more NOx relative to the baseline, for example when cooking with gas or running combustion appliances.
• Unlike the VOC index, the NOx algorithm typically uses a more fixed gain (changes are usually slower and smaller), so the mapping from events to index changes is more stable over time.

As with VOC, the NOx index is relative. It is useful for detecting and reacting to events (for example, boosting extraction during gas cooking) rather than for absolute regulatory reporting.

CO2 (SCD4x)

ES1 measures CO2 using a Sensirion SCD4x sensor configured in low‑power periodic mode:

• The SCD4x is an NDIR (non‑dispersive infrared) CO2 sensor. It shines infrared light through a small gas chamber and measures how much light is absorbed at a CO2‑specific wavelength.
• ES1 reads a new CO2 value roughly every 30 seconds.
• Ambient pressure from the DPS310 pressure sensor is passed to the SCD4x as a compensation value. This slightly improves accuracy at non‑standard pressures.
• Automatic Self‑Calibration (ASC) is enabled by default:
  • Over days, the sensor assumes it occasionally sees fresh outdoor‑like air (~400 ppm CO2).
  • It slowly adjusts its internal baseline so that minimum readings align with that fresh‑air reference.

For most home environments this produces stable long‑term readings. In spaces that are occupied 24/7 and rarely vented to outdoor levels, ASC can drift; in those cases you may want to periodically ensure ES1 sees fresh air.

Based on the SCD4x datasheet, you can typically expect CO2 accuracy on the order of ±(50 ppm + 5% of the reading) under normal indoor conditions. This is more than sufficient for home comfort and ventilation decisions, but it is not a laboratory calibration device.

Particulate matter (PM) from SEN55

The SEN55 PM sensor uses a small optical chamber and a laser/LED to measure airborne particles:

• Air is drawn through an optical path.
• Particles passing the beam scatter light; the sensor measures the intensity and pattern of this scattering.
• Built‑in algorithms estimate size distribution and convert that into mass concentrations for four size fractions:
  • PM1.0 (particles smaller than 1 µm)
  • PM2.5 (smaller than 2.5 µm)
  • PM4.0 (smaller than 4 µm)
  • PM10 (smaller than 10 µm)
• ES1 polls the SEN55 every 10 seconds.
• The SEN55 applies its own temperature/humidity compensation to reduce artefacts in high humidity.

Notes for interpretation:

• The PM channels are related, not independent; PM10 includes larger particles as well as everything smaller.
• The reported “weight concentration” is an estimate based on scattering, not a direct gravimetric measurement. It is well‑suited to tracking relative changes and meeting typical indoor air quality needs.
• ES1’s PM thresholds are chosen to roughly align with common guideline values but can be tuned on the Configuration page.