Documentation

HomeEaze Air Docs

Everything you need to understand how HomeEaze Air works under the hood — from the API to sensor physics.

🔌 API Overview

REST API

HomeEaze Air exposes a local REST API on your hub device. All requests are made over your local network — no cloud dependency required for data access.

ℹ️

The API is currently in pre-release. Endpoints and authentication methods may change before the public launch. Apply for the pilot programme to get early API access.

Base URL

http 
http://<hub-ip>:8080/api/v1

Authentication

All API requests require a bearer token obtained from the hub's local admin panel. Pass it in the Authorization header:

http 
Authorization: Bearer <your-token>

Key Endpoints

Method Endpoint Description
GET /rooms List all rooms and their latest readings
GET /rooms/:id Single room with full sensor detail
GET /rooms/:id/history Historical readings (supports ?from & ?to params)
GET /alerts All active and recent alerts
POST /alerts/:id/dismiss Dismiss a specific alert
GET /status Hub health, uptime, and firmware version

Example Response — GET /rooms/:id

json 
{
  "id": "bedroom",
  "name": "Bedroom",
  "updated_at": "2025-06-01T22:14:00Z",
  "readings": {
    "co2":      { "value": 1247, "unit": "ppm",    "status": "warn" },
    "pm25":     { "value": 8,    "unit": "µg/m³",  "status": "good" },
    "voc":      { "value": 0.18, "unit": "mg/m³",  "status": "good" },
    "temp":     { "value": 19.4, "unit": "°C",     "status": "good" },
    "humidity": { "value": 52,   "unit": "%",      "status": "good" }
  },
  "aqi": 62,
  "aqi_status": "moderate"
}

Status Values

good

Reading is within healthy range. No action needed.

warn

Reading is elevated. Consider ventilation or investigation.

poor

Reading exceeds safe thresholds. Action recommended.

unknown

Sensor offline or no recent data received.

📡 MQTT Overview

MQTT Integration

HomeEaze Air publishes all sensor readings to an MQTT broker in real time. This is the primary integration path for Home Assistant, Node-RED, and any other automation platform.

💡

MQTT is the recommended integration method for Home Assistant users. The hub auto-discovers the broker and publishes Home Assistant–compatible discovery payloads.

Broker Details

Built-in broker

The hub ships with an embedded Mosquitto broker running on port 1883. You can also point it at an external broker in Settings → MQTT.

TLS support

Encrypted connections are supported on port 8883 using your hub's self-signed certificate, or a certificate from your own CA.

Topic Structure

All topics are prefixed with homeeaze/air/. Sensor readings are published every 60 seconds by default (configurable down to 10 s).

topics 
homeeaze/air/<room-id>/co2
homeeaze/air/<room-id>/pm25
homeeaze/air/<room-id>/voc
homeeaze/air/<room-id>/temperature
homeeaze/air/<room-id>/humidity
homeeaze/air/<room-id>/aqi
homeeaze/air/<room-id>/state       ← full JSON payload
homeeaze/air/alerts                 ← alert events
homeeaze/air/hub/status             ← hub heartbeat

Payload Format

Individual sensor topics publish a simple numeric value as a plain string. The state topic publishes the full room JSON (same shape as the REST API).

mqtt 
Topic:   homeeaze/air/bedroom/co2
Payload: 1247

Topic:   homeeaze/air/bedroom/state
Payload: {"co2":1247,"pm25":8,"voc":0.18,"temp":19.4,"humidity":52,"aqi":62}

Home Assistant Auto-Discovery

When auto-discovery is enabled (default: on), the hub publishes Home Assistant MQTT discovery configs under the standard homeassistant/ prefix. All sensors appear automatically as entities in HA — no manual YAML required.

yaml 
# Discovery config published automatically by the hub
homeassistant/sensor/homeeaze_bedroom_co2/config
{
  "name": "Bedroom CO₂",
  "unique_id": "homeeaze_bedroom_co2",
  "state_topic": "homeeaze/air/bedroom/co2",
  "unit_of_measurement": "ppm",
  "device_class": "carbon_dioxide",
  "state_class": "measurement"
}
🎯 Sensor Accuracy

Sensor Accuracy & Methodology

We believe you should know exactly what's inside your sensor and how accurate it is. Here's the complete picture.

Sensor Specifications

Sensor Technology Range Accuracy Warm-up
CO₂ NDIR (non-dispersive infrared) 400 – 5,000 ppm ± 50 ppm ± 3% 60 s
PM2.5 Laser particle counter 0 – 999 μg/m³ ± 10 μg/m³ 30 s
VOC Metal oxide semiconductor (MOX) 0 – 10 mg/m³ Relative (see note) 48 h burn-in
Temperature Calibrated thermistor –10 – 60 °C ± 0.3 °C 5 s
Humidity Capacitive polymer 0 – 100% RH ± 2% RH 5 s

VOC values are relative indices, not absolute concentrations. They're most useful as trend indicators and for triggering alerts on rapid spikes (e.g. cleaning products, gas leaks).

CO₂: NDIR vs. eCO₂

HomeEaze Air uses true NDIR CO₂ sensors — not estimated eCO₂ derived from VOC. NDIR measures the actual infrared absorption of CO₂ molecules, making it the gold standard for accuracy. Cheap sensors that advertise "CO₂" readings under £30 almost always use eCO₂ estimation, which can be off by 300–500 ppm.

⚠️

NDIR sensors require self-calibration over their first 7 days of operation. Place your sensor in a well-ventilated space for at least one hour per day during this period to allow automatic baseline calibration.

PM2.5: Laser Particle Counting

Our laser particle counter uses 650 nm laser scattering to count and size particles in real time. The PM2.5 channel counts particles between 0.3 and 2.5 μm in diameter. Readings are averaged over 10-second windows to reduce noise from transient dust events.

What affects PM2.5 accuracy

  • Cooking (frying, toast) can cause temporary 50–200× spikes
  • High humidity (> 85% RH) causes particle coalescence — readings may read lower than actual
  • Sensor intake should be kept clear of dust accumulation — clean every 6 months

WHO & UK thresholds used

  • Good: 0–10 μg/m³ (WHO annual guideline)
  • Moderate: 10–25 μg/m³
  • Elevated: 25–50 μg/m³ (UK legal limit)
  • Poor: > 50 μg/m³

Temperature Compensation

All sensor readings are automatically cross-compensated for temperature and humidity drift. The CO₂ sensor applies a built-in pressure/temperature correction at every reading cycle. Humidity readings are cross-checked against the thermistor output to flag implausible combinations.

🏡 UK/EU Homes

Why UK & EU Homes Are Different

HomeEaze Air is built specifically for UK and EU homes. This section explains why home construction and ventilation norms mean standard US-centric air quality advice often doesn't apply.

No Central HVAC — The Key Difference

In the US, roughly 90% of homes use forced-air HVAC systems. Air is continuously circulated throughout the whole home, which means pollutants mix, temperatures equalise, and a single central sensor gives a broadly representative picture.

UK and EU homes overwhelmingly rely on room-by-room heating (radiators, heat pumps) with no forced-air circulation. Each room is effectively an isolated air environment — especially when doors are closed.

🏠

In a typical UK home, a closed bedroom can reach 2,000 ppm CO₂ while the living room reads 500 ppm — simultaneously, in the same house. A hallway sensor would tell you neither.

Post-2016 Airtight New Builds

UK Building Regulations Part F (2021 revision) and equivalent EU standards now mandate much stricter airtightness targets for new builds. Modern UK homes can achieve under 3 m³/h/m² air permeability — excellent for energy efficiency, but a significant challenge for air quality:

The airtight problem

  • No background air leakage means CO₂ and humidity accumulate faster
  • VOC off-gassing from new materials (paint, carpets, adhesives) has nowhere to go
  • Mechanical ventilation (MVHR) is required but may be set incorrectly

Older UK housing stock

  • Pre-1980 homes often have high air permeability — CO₂ dilutes quickly
  • Draughts make heating less efficient but naturally ventilate rooms
  • Damp and mould risk is higher due to poor insulation and condensation

UK-Specific Thresholds

HomeEaze Air uses UK and EU regulatory thresholds — not US EPA standards — for all alert levels and reporting. Key differences:

Metric UK / WHO threshold US EPA equivalent Why it differs
PM2.5 (annual) 10 μg/m³ (WHO 2021) 12 μg/m³ (EPA 2024) UK follows more recent WHO guidelines
CO₂ (occupied room) 1,000 ppm (CIBSE guidance) 1,000 ppm (ASHRAE 62.1) Same threshold, different enforcement context
Humidity 40–60% RH (Building Regs) 30–50% RH (ASHRAE) UK climate is more humid; 30% RH is unrealistically dry for UK homes

MVHR & Ventilation Awareness

If your home has Mechanical Ventilation with Heat Recovery (MVHR), HomeEaze Air can detect when ventilation is working correctly by monitoring CO₂ decay rates after occupancy. Slower-than-expected decay may indicate a blocked filter or incorrectly configured airflow rate — a common issue in newly built homes.

🗺️ Multi-Room Logic

Multi-Room Intelligence

HomeEaze Air isn't a collection of independent sensors. The hub analyses readings across all rooms together to find patterns, spot drift, and generate contextual alerts that a single-sensor system could never produce.

Room Scoring

Each room receives a composite AQI score (0–100) calculated from a weighted combination of all five sensor inputs. Weights are tuned for UK indoor air quality norms:

Sensor Weighting Rationale
PM2.5 35% Most direct health impact; cooking spikes are common in UK kitchens
CO₂ 30% Primary indicator of ventilation quality in sealed UK rooms
VOC 20% Catches chemical events (cleaning, painting) not reflected in CO₂/PM
Humidity 10% Mould risk indicator, especially important in UK bathrooms and bedrooms
Temperature 5% Comfort factor; extreme temperatures affect pollutant behaviour

Home Score

The overall Home Score is a weighted average of all room scores, with bedrooms weighted more heavily (×1.5) because adults spend ~8 hours per night there and CO₂ accumulation during sleep has well-documented effects on cognitive performance and sleep quality.

Cross-Room Correlation

The hub analyses readings across rooms to identify patterns that single-room systems miss:

🍳 Cooking drift detection

PM2.5 spikes in the kitchen that appear 5–15 minutes later in adjacent rooms indicate that particle drift is occurring — the system alerts you to close internal doors during cooking.

🌙 Overnight CO₂ accumulation

Bedrooms with CO₂ that rises steadily after lights-out are flagged for ventilation advice, taking into account occupancy count and room volume (set during onboarding).

🚿 Humidity spread monitoring

If bathroom humidity above 70% RH spreads to the adjacent bedroom within 30 minutes, the system alerts you to improve bathroom ventilation before mould risk escalates.

🔧 Sensor drift detection

Readings that diverge significantly from nearby room sensors without a plausible cause (door open, occupancy change) are flagged as potential sensor calibration drift.

Alert Intelligence

Alerts are generated by a rule engine that considers context before triggering a notification. Naive threshold alerts produce alert fatigue — HomeEaze Air avoids this:

💡

A PM2.5 reading of 80 μg/m³ in the kitchen at 7:00 pm is expected behaviour — the system suppresses that alert. The same reading at 2:00 am is unusual and would trigger a notification immediately.

Alert Suppression Rules

Rule Description
Time-of-day context Kitchen PM2.5 alerts suppressed during typical cooking windows (07:00–09:00, 12:00–14:00, 17:00–20:00)
Rapid decay Spikes that resolve within 10 minutes without intervention are not escalated
Duplicate suppression The same alert type won't re-fire within 1 hour for the same room
Multi-sensor confirmation VOC alerts require a concurrent PM2.5 or CO₂ anomaly to avoid false positives from the MOX sensor
ℹ️

All suppression rules and thresholds are configurable per room via the hub's settings panel. You can also create custom automation triggers using the REST API or MQTT.

🗺️ Roadmap

Thread / Matter Roadmap

HomeEaze Air's connectivity roadmap is a staged transition from Wi-Fi to Thread/Matter. Early adopter hardware won't be stranded — backwards compatibility is a design requirement.

⚠️

This roadmap is conceptual and pre-production. It describes the intended migration path rather than a guaranteed release schedule.

Phase 1 — Current

Active
  • Wi-Fi room sensors (802.11 b/g/n, 2.4 GHz)
  • MQTT over Wi-Fi with Home Assistant auto-discovery
  • Full local REST API
  • CSV and JSON data export

Phase 2 — Planned

Planned
  • Hardware revision with Thread-capable radio
  • Matter device attestation
  • Dual-stack Thread + Wi-Fi operation during migration period
  • Continued MQTT and local API support through the hub layer

Phase 3 — Planned

Planned
  • Hub-level Thread border router support
  • Full Thread mesh for supported devices
  • Matter OTA workflows
  • Broader direct ecosystem support through Matter clusters

Why Thread and Matter

Thread

  • Mesh networking between room sensors
  • Lower power than always-on Wi-Fi
  • No single point of failure at the edge
  • Resilient 2.4 GHz 802.15.4 mesh

Matter

  • Common application layer across Apple, Google, Amazon, HA
  • Universal interoperability without abandoning local-first
  • Long-term standards-based deployment

Matter Sensor Clusters

Planned Matter cluster coverage:

matter
AirQuality
CarbonDioxideConcentrationMeasurement
PM25ConcentrationMeasurement
TotalVolatileOrganicCompoundsConcentrationMeasurement
TemperatureMeasurement
RelativeHumidityMeasurement
💡

Early adopter Wi-Fi units will continue to work with MQTT and the local API. Thread-capable hardware will also support Matter over Wi-Fi where platform support makes that practical — no stranded devices.