Bridging PurpleAir Air Quality Sensors into Smart Home Matter Ecosystems

Note

  • Published: November 6, 2026

  • Authors: Written by Gemini 3.8 Flash, Co-Authored & Reviewed by Carlos Santos (@carlkidcrypto)

  • Estimated Reading Time: 5 minutes

  • Tags: Purpleair • Matter • Smart-Home • Home-Assistant • Apple-Home • Iot

Smart home automation ecosystems like Apple Home, Home Assistant, Google Home, and Amazon Alexa have historically relied on proprietary cloud integrations, custom plugins, or fragile web scrapers to incorporate outdoor and indoor air quality data. When APIs undergo breaking changes, smart home dashboards and ventilation automations often fail silently.

The Connectivity Standards Alliance (CSA) Matter specification solves vendor lock-in by establishing a unified, IP-based application layer for smart home devices. With the introduction of standardized sensor device types, environmental monitors can now report particulate matter and ambient conditions directly to any certified Matter controller over local networks.

To bring PurpleAir’s rich environmental telemetry into this standard, purpleair-matterbridge operates as a dedicated Matterbridge plugin. It translates local or remote PurpleAir sensor telemetry into fully certified, locally bridged Matter devices.

In this tutorial, we will examine the Matter device hierarchy, configure the purpleair-matterbridge plugin, deploy the bridge using Docker with host networking, and commission PurpleAir sensors into Apple Home and Home Assistant.

Understanding the Matter Air Quality Architecture

The Matter specification defines discrete clusters and device types for environmental sensing:

  • Air Quality Sensor Device Type (0x002C): Represents dedicated air quality sensing accessories.

  • Air Quality Measurement Cluster (0x005B): Exposes a standardized discrete categorical enumeration (AirQualityEnum: 0=Unknown, 1=Good, 2=Fair, 3=Moderate, 4=Poor, 5=Very Poor, 6=Extremely Poor) rather than a raw numeric score.

  • Concentration Measurement Clusters: Standardized clusters for discrete particulate densities, including PM1.0, PM2.5, and PM10 in micrograms per cubic meter (ug/m3).

  • Environmental Sensing Clusters: Exposes temperature (Cluster 0x0402), relative humidity (Cluster 0x0405), and atmospheric pressure (Cluster 0x0403).

The purpleair-matterbridge plugin maps PurpleAir telemetry into standard Matter endpoints:

Matterbridge Root Node (Endpoint 0)
 └── Bridged Node Endpoint
      ├── Device Type: Air Quality Sensor (0x002C)
      ├── Cluster: AirQuality (0x005B) -> AirQualityEnum (0..6)
      ├── Cluster: PM2.5 Measurement -> Measured ug/m3
      ├── Cluster: TemperatureMeasurement (0x0402) -> Ambient deg C
      ├── Cluster: RelativeHumidityMeasurement (0x0405) -> % RH
      └── Cluster: PressureMeasurement (0x0403) -> hPa

Each discovered PurpleAir sensor receives a deterministic Matter node identity (purpleair-<sensor_index>) and a clean MAC-based display name (e.g. purple-air-84-a1-4b), ensuring persistence across container updates and controller reboots.

Plugin Configuration and Architecture

The bridge consumes an HTTP feed populated by purpleair_data_logger or a local polling daemon. By default, the plugin listens for sensor payloads at http://127.0.0.1:9855/matter/sensors.

Create a configuration file named purpleair-matterbridge.config.json:

{
  "name": "purpleair-matterbridge",
  "type": "DynamicPlatform",
  "feedUrl": "http://127.0.0.1:9855/matter/sensors",
  "pollIntervalSeconds": 30,
  "requestTimeoutSeconds": 10,
  "debug": false
}

The configuration schema validates supported platform parameters: feedUrl, pollIntervalSeconds, requestTimeoutSeconds, and debug logging flags.

Important

Stale Telemetry Handling: On a failed poll or missing sensor entry in the HTTP feed, purpleair-matterbridge intentionally preserves its last-known-good readings in memory without marking the sensor offline in Matterbridge. This prevents momentary network blips from triggering false device-unavailable states. In production, configure separate container health checks or feed freshness monitoring to catch prolonged upstream outages.

Next, create the logger configuration file purpleair-settings.json in your project directory. For local LAN sensor polling:

{
  "your_ipv4_address": [
    "192.168.1.100"
  ]
}

Deploying with Docker & Host Networking

Matter commissioning relies heavily on IPv6 link-local addressing and multicast DNS (mDNS / DNS-SD on UDP port 5353) to discover uncommissioned accessories. Standard Docker bridge networks isolate multicast traffic, preventing Apple Home or Home Assistant from discovering the bridge.

To ensure seamless discovery, run the container with host networking:

# docker-compose.yml
services:
  purpleair-matterbridge:
    image: carlkidcrypto/purpleair-matterbridge-images:2026.11.3-0
    container_name: purpleair-matterbridge
    restart: unless-stopped
    network_mode: host
    environment:
      - PURPLEAIR_LOGGER_MODE=local
      - PURPLEAIR_SETTINGS_FILE=/config/purpleair-settings.json
      - NODE_ENV=production
    volumes:
      - ./purpleair-settings.json:/config/purpleair-settings.json:ro
      - ./purpleair-matterbridge.config.json:/data/.matterbridge/purpleair-matterbridge.config.json:ro
      - matterbridge-data:/data
      - logger-data:/data/logger

volumes:
  matterbridge-data:
  logger-data:

Key deployment details:

  • Host Network Mode (network_mode: host): Binds container sockets directly to the host interface (such as eth0 or wlan0), enabling native mDNS broadcasts and IPv6 neighbor discovery.

  • Published Container Image: Uses the official multi-architecture build carlkidcrypto/purpleair-matterbridge-images pinned to a release tag (or updated dynamically via docker/update_pa_matterbridge.sh).

  • Persistent Data Paths: The container runs with HOME=/data. Mounting matterbridge-data at /data and logger-data at /data/logger preserves Matter fabric pairing keys and logger state across image recreations.

  • Logger Mode: Configured via PURPLEAIR_LOGGER_MODE as plain local (for LAN sensor queries) or remote (for cloud API queries) without leading dashes.

Launch the stack:

docker compose up -d

Commissioning into Smart Home Ecosystems

Once started, Matterbridge generates a unique QR code and a manual 11-digit numeric pairing code (e.g., 3497-011-2983) in the container logs:

docker logs -f purpleair-matterbridge

Pairing Steps:

  1. Apple Home:

    • Open Apple Home on iPhone or iPad connected to your local Wi-Fi.

    • Tap + -> Add Accessory.

    • Scan the console QR code or enter the 11-digit pairing code manually.

    • Assign the bridge to a room (e.g. “Outdoor” or “Living Room”). All underlying PurpleAir monitors appear automatically as child sensors.

  2. Home Assistant:

    • Navigate to Settings -> Devices & Services -> Matter.

    • Select Add Device -> Add Matter Device.

    • Home Assistant uses the mobile companion app or Thread/Wi-Fi commissioner to bind the device into your local fabric.

Automation Recipes

With PurpleAir sensors exposed as native Matter devices, you can trigger home automations locally without relying on cloud services. Telemetry updates reflect the combined sampling interval of the logger (e.g., 60 seconds) and the bridge feed polling interval (e.g., 30 seconds), propagating state transitions within approximately 30 to 90 seconds.

Automated Energy Recovery Ventilator (ERV) Quarantine

When outdoor wildfire smoke causes PM2.5 to spike, immediately shut off fresh air dampers and activate indoor HEPA filtration:

# Home Assistant Automation Recipe
alias: "HVAC: Wildfire Smoke Protection"
trigger:
  - platform: numeric_state
    entity_id: sensor.purple_air_outdoor_pm2_5
    above: 35.0  # EPA Moderate threshold
action:
  - service: switch.turn_off
    target:
      entity_id: switch.erv_fresh_air_intake
  - service: fan.set_preset_mode
    target:
      entity_id: fan.main_hvac_air_purifier
    data:
      preset_mode: "high"

Window Ventilation Alerts

If indoor air quality degrades while outdoor air remains clean, notify smart displays or smart speakers to suggest opening windows:

alias: "Alert: Open Windows for Fresh Air"
trigger:
  - platform: numeric_state
    entity_id: sensor.purple_air_indoor_pm2_5
    above: 20.0
condition:
  - condition: numeric_state
    entity_id: sensor.purple_air_outdoor_pm2_5
    below: 10.0
action:
  - service: notify.living_room_speaker
    data:
      message: "Indoor air quality is declining. Outdoor air is clean."

Summary & What’s Next

The purpleair-matterbridge project bridges the gap between environmental monitoring and local smart home control. By embracing open Matter standards and local network discovery, users eliminate cloud dependencies and unlock resilient home automations.

In our next blog post, we will rotate back to ezsnmp, diving deep into MPLS and Segment Routing Label Switched Path (LSP) telemetry and path auditing with high-speed C++17 SNMP bindings.

Warning

AI-generated content may contain misinformation or mistakes. A human does review this, but we are only human.