purpleair-local - GitLite

KO | EN

gitlite — search

#markdown #rag #chatbot #agents #proxy #windows #large-language-models #electron #open-source #graphql

purpleair-local

(★ 9)

Home Assistant custom integration for local-only polling of PurpleAir PA-II sensors. No cloud, no API key.

파일 탐색기

ZIP 다운로드

- configuration.yaml.example
- - test.yml
  - validate.yml
- PULL_REQUEST_TEMPLATE.md
- - __init__.py
  - api.py
  - aqi.py
  - binary_sensor.py
  - config_flow.py
  - const.py
  - coordinator.py
  - diagnostics.py
  - entity.py
  - manifest.json
  - models.py
  - sensor.py
  - strings.json
- - pa2_indoor_single_laser.json
  - pa2_outdoor_dual_laser.json
  - README.md
- __init__.py
- conftest.py
- test_api.py
- test_aqi.py
- test_binary_sensor.py
- test_config_flow.py
- test_coordinator.py
- test_diagnostics.py
- test_init.py
- test_models.py
- test_options_flow.py
- test_sensor.py
- test_translations.py
.gitignore
AGENTS.md
CLAUDE.md
CONTRIBUTING.md
DESIGN.md
docker-compose.yml
hacs.json
LICENSE
Makefile
pyproject.toml
README.md
requirements_test.txt
TODO.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![HACS Custom][hacs-shield]][hacs]
[![GitHub Release][releases-shield]][releases]
[![License][license-shield]](https://raw.githubusercontent.com/jpettitt/purpleair-local/main/LICENSE)
![Maintenance][maintenance-shield]
[![Validate][validate-shield]][validate]
[![Tests][tests-shield]][tests]

A Home Assistant custom integration that polls PurpleAir PA-II (and
compatible) sensors directly on the LAN — no cloud, no API key.

[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.][hacs-install-shield]][hacs-install]
&nbsp;
[![Open your Home Assistant instance and start setting up a new integration.][add-shield]][add]

See [DESIGN.md](DESIGN.md) for architecture and the decisions behind
the implementation.

## Why local

- Works with the internet down.
- No PurpleAir cloud rate limits, no API key, no third-party data sharing.
- Sub-minute polling is possible (sensor minimum is 10 s; we default to
  120 s to match the sensor's natural averaging cadence).

## What it provides

Per configured sensor:

- **PM1.0 / PM2.5 / PM10 mass concentration** (µg/m³, ATM density) —
  always a primary entity; channel A and channel B added on dual-laser
  units. Primary on dual is the simple A/B average for v0.1.
- **PM2.5 AQI** — one entity per enabled correction, using the
  2024-revised US EPA breakpoint table. Default: raw (no concentration
  correction) and EPA (Barkjohn 2021). Also available via the options
  flow: EPA extended (the five-piece version used by the AirNow Fire
  and Smoke Map, which stays accurate in heavy smoke where the linear
  form under-reports), AQandU, and LRAPA.
- **Temperature, humidity, dewpoint, pressure** — only when the sensor
  has a BME280 or BME680. BME680 values preferred when both are present.
  Note: the temperature reading runs a few degrees high. The BME sits
  inside the PurpleAir enclosure and picks up heat from the laser
  counters and the ESP processor; PurpleAir's own guidance for outdoor
  units is to subtract roughly 8 °F (≈ 4.4 °C) from the reported value.
- **VOC resistance** (Ω) — only when the sensor has a BME680.
- **Particle counts** in six size bins, primary only, disabled by
  default. Enable individually from the device page when you want them.
- **Diagnostics** — WiFi signal, uptime, free heap, firmware version,
  last reported timestamp. Free heap and firmware are disabled by
  default.
- **Online** binary sensor — reflects the coordinator's last poll status.
- **Channel disagreement** binary sensor — dual-laser only. Trips when
  both PurpleAir thresholds are crossed (default ≥5 µg/m³ AND ≥70 %),
  configurable in options.

Single-laser sensors (some indoor PA-II units) skip the channel-B
entities and the disagreement binary sensor automatically.

## Live entities (optional)

By default the integration reads the sensor's averaged endpoint, which
updates every two minutes. If you're driving an automation that needs to
react to a smoke plume quickly — shutting down mechanical ventilation,
closing a window vent — turn on **Add live (unaveraged) entities** in the
options flow.

This is additive. You get a second set of PM, AQI and particle-count
entities suffixed `_live`, polled every 15 seconds by default, *alongside*
the averaged ones. Nothing is replaced, so your existing history and
statistics keep accumulating from the averaged series.

Live entities are primary-channel only, and there are no live twins of
the temperature/humidity/pressure or diagnostic entities — the sensor
returns identical values for those on both endpoints.

**A failing cloud upload will stall the live endpoint.** Once every 120
seconds a PA-II connects out to the PurpleAir cloud; some units make a
second connection elsewhere too. Those connections block, and
`?live=true` waits behind them — the averaged entities are unaffected.
When they succeed this costs a few hundred milliseconds and you'll never
notice. When one *hangs* — packets dropped by a firewall, DNS trouble,
an endpoint that accepts the connection and never replies — live
requests hang with it, typically 15–35 seconds, once per cycle.

The integration absorbs this: live requests aren't retried (the retry
would land in the same stall), and short runs of failures keep serving
the last reading rather than dropping your entities to `unavailable`.

But if you're seeing gaps, it's worth fixing at the source. Open
`http://<sensor-ip>/json` and compare two fields:

- `httpsends` — upload attempts
- `httpsuccess` — successful uploads

If `httpsends` is climbing faster than `httpsuccess`, that sensor has a
failing outbound connection, and that's your stall.

**The most common cause is a stale Data Processor.** PurpleAir lets you
forward readings to a third party (Weather Underground and similar), and
that's configured **in your PurpleAir account on their website, not on
the sensor** — so there's nothing about it on the device's own config
page. If that target has gone away, the sensor still tries it every
cycle and waits for the timeout, stalling live requests the whole time.
A sensor here was doing exactly this against a long-dead Weather
Underground link, stalling live for up to 36 seconds every cycle.

Sensors with a Data Processor set also report `response` — the HTTP
client error code for that target, e.g. `-11` for a read timeout — plus
a `latency` for it. If you see that, check your Data Processor settings
on the PurpleAir site and remove anything you no longer use.

Other causes are a firewall blocking the sensor's outbound HTTPS, or DNS
trouble. Fixing the failing target removes the stall at source; the
integration's handling just stops it becoming an outage in the meantime.

**Live readings are noisy.** The firmware reports whole µg/m³, so at low
concentrations the AQI can swing between 4 and 13 from one reading to the
next with no real change in air quality. Measured on a PA-II, a new PM
value only appears every ~19 seconds anyway (up to 43), so polling faster
than the 15 s default mostly returns repeats. Trigger on a sustained
change, not a single reading:

```yaml
automation:
  - alias: Shut down MVHR on outdoor smoke
    trigger:
      - platform: numeric_state
        entity_id: sensor.outdoor_0119_pm2_5_live
        above: 35
        for: "00:01:00"   # sustained, so one noisy sample can't trip it
    action:
      - action: fan.turn_off
        target:
          entity_id: fan.mvhr
```

## Install

The quick way — two clicks if your Home Assistant browser session is
already authenticated:

[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.][hacs-install-shield]][hacs-install]
&nbsp;
[![Open your Home Assistant instance and start setting up a new integration.][add-shield]][add]

The first button opens HACS pointed at this repo (you'll still need to
click **Download** in HACS and then restart Home Assistant). The second
button opens the integration's config flow once it's installed.

The manual equivalent:

1. HACS → Integrations → ⋮ → Custom repositories.
2. Add `https://github.com/jpettitt/purpleair-local` as an Integration.
3. Install "PurpleAir Local" from the list, then restart Home Assistant.
4. Settings → Devices & Services → Add Integration → "PurpleAir Local".
5. Enter the sensor's IP. Repeat for each sensor.

If a sensor's IP later changes (DHCP), edit it from the integration's
**Configure** screen — the integration verifies the SensorId still
matches and updates the host in place. No need to delete and re-add.

## Dashboard examples

Each AQI entity carries two extra attributes that any card supporting
templates can read:

- `category` — a stable snake-case label for the current band
  (`good`, `moderate`, `unhealthy`, etc., or the UK DAQI form
  `low_1` … `very_high_10` if you've selected that scheme).
- `category_color` — the official hex colour for that band.

The colour scheme is per-user, selected in the integration's options
flow. Default is US EPA (AirNow); EU EAQI and UK DAQI are available.

### Mushroom — icon coloured by AQI

[mushroom-template-card](https://github.com/piitaya/lovelace-mushroom)
is the lightest-weight way to get a coloured icon next to the AQI
number. Pick the entity for whichever correction you want
(`_aqi_raw`, `_aqi_epa`, `_aqi_aqandu`, `_aqi_lrapa`).

```yaml
type: custom:mushroom-template-card
entity: sensor.outdoor_0119_aqi_epa
icon: mdi:weather-hazy
icon_color: |
  {{ state_attr('sensor.outdoor_0119_aqi_epa', 'category_color') }}
primary: |
  {{ states('sensor.outdoor_0119_aqi_epa') }} AQI
secondary: |
  {{ state_attr('sensor.outdoor_0119_aqi_epa', 'category')
       | replace('_', ' ') | title }}
```

### apexcharts-card — coloured line, banded background, or both

[apexcharts-card](https://github.com/RomRider/apexcharts-card) has a
built-in `color_threshold` for series so the line itself changes
colour as the AQI moves through the bands:

```yaml
type: custom:apexcharts-card
header:
  show: true
  title: Outdoor AQI (24h)
graph_span: 24h
series:
  - entity: sensor.outdoor_0119_aqi_epa
    name: AQI (EPA)
    type: line
    stroke_width: 3
    color_threshold:
      - value: 0
        color: "#00e400"
      - value: 51
        color: "#ffff00"
      - value: 101
        color: "#ff7e00"
      - value: 151
        color: "#ff0000"
      - value: 201
        color: "#8f3f97"
      - value: 301
        color: "#7e0023"
```

For a single-point sparkline coloured by the *current* band, drive
the colour from the entity attribute directly (apexcharts evaluates
`EVAL:` strings as JS against the `hass` object):

```yaml
type: custom:apexcharts-card
chart_type: radialBar
series:
  - entity: sensor.outdoor_0119_aqi_epa
    color: |
      EVAL:hass.states['sensor.outdoor_0119_aqi_epa'].attributes.category_color
```

### button-card — full tile with the category as a background

[custom:button-card](https://github.com/custom-cards/button-card) lets
you push the category colour all the way to the card background for a
glanceable indoor/outdoor at-a-glance:

```yaml
type: custom:button-card
entity: sensor.outdoor_0119_aqi_epa
name: Outdoor AQI
show_state: true
styles:
  card:
    - background-color: "[[[ return entity.attributes.category_color ]]]"
    - color: white
    - font-weight: bold
    - padding: 16px
  state:
    - font-size: 2em
```

### Built-in cards

The standard HA Entity / Tile cards don't take templates in their
`color` field today, so for the built-ins you'll either use one of
the custom cards above or wrap a template sensor — see [HA's template
sensor docs](https://www.home-assistant.io/integrations/template/) for
the pattern.

## Development

### Test suite

```sh
python3 -m venv .venv
.venv/bin/pip install -r requirements_test.txt
make test
```

### Local HA testbed (Docker)

A `docker-compose.yml` at the repo root mounts
`custom_components/purpleair_local/` read-only into a disposable Home
Assistant container, so edits to the integration are picked up by HA on
the next reload. Requires Docker (Desktop or compatible).

```sh
make ha-up        # boots HA at http://localhost:8123 (first start ~1 min)
make ha-logs      # tail container logs
make ha-restart   # restart HA after editing the integration
make ha-down      # stop, keep config
make ha-reset     # wipe runtime config — back to the onboarding screen
```

First boot walks through HA's user-creation flow; after that, add the
integration from **Settings → Devices & Services → Add Integration →
"PurpleAir Local"**. Runtime data (database, secrets, logs) lives under
`.dev/ha-config/` and is gitignored.

## License

MIT.

[hacs-shield]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge
[hacs]: https://github.com/hacs/integration
[releases-shield]: https://img.shields.io/github/v/release/jpettitt/purpleair-local?style=for-the-badge
[releases]: https://github.com/jpettitt/purpleair-local/releases
[license-shield]: https://img.shields.io/github/license/jpettitt/purpleair-local?style=for-the-badge
[maintenance-shield]: https://img.shields.io/maintenance/yes/2026?style=for-the-badge
[validate-shield]: https://img.shields.io/github/actions/workflow/status/jpettitt/purpleair-local/validate.yml?label=Validate&style=for-the-badge
[validate]: https://github.com/jpettitt/purpleair-local/actions/workflows/validate.yml
[tests-shield]: https://img.shields.io/github/actions/workflow/status/jpettitt/purpleair-local/test.yml?label=Tests&style=for-the-badge
[tests]: https://github.com/jpettitt/purpleair-local/actions/workflows/test.yml
[hacs-install-shield]: https://my.home-assistant.io/badges/hacs_repository.svg
[hacs-install]: https://my.home-assistant.io/redirect/hacs_repository/?owner=jpettitt&repository=purpleair-local&category=integration
[add-shield]: https://my.home-assistant.io/badges/config_flow_start.svg
[add]: https://my.home-assistant.io/redirect/config_flow_start/?domain=purpleair_local