The WxAlerts integration puts the alert feed into Home Assistant as entities: a binary sensor that turns on the moment a warning is issued for your county, a severity sensor for dashboards, map markers per live hazard, and a lightning flash counter around each place you care about.
It is push, not polling. The integration holds one MQTT connection to the public feed, so an alert arrives when the NWS publishes it and disappears when the NWS ends it. There is no poll interval to tune and no gap between the warning and your automation firing.
Before you start
| Home Assistant | 2024.12.0 or newer |
| Current release | 0.2.1 |
| Source | github.com/wxalerts/WxAlerts-HA |
| Account needed | None, because the feed is public and read-only |
| Outbound access | wss://mqtt.wxalerts.org/mqtt on port 443, plus one call to api.weather.gov during setup |
You do not need the Home Assistant MQTT integration, and you do not need a broker of your own. The integration brings its own client.
Install through HACS
- In Home Assistant, open HACS → ⋮ → Custom repositories.
- Add
https://github.com/wxalerts/WxAlerts-HAwith type Integration. - Install WxAlerts, then restart Home Assistant.
- Go to Settings → Devices & Services → Add Integration and search for WxAlerts.
To install by hand instead, copy custom_components/wxalerts/ from the repo
into your config directory’s custom_components/ and restart.
Setup
The setup form asks for zones, the Home Assistant zones you already have for home, the cabin, a parent’s house. Pick one or more, and choose whether you want NWS alerts, GLM lightning, or both.
Each zone is resolved once, when you save:
- Its coordinates go to
api.weather.govto find the county, which becomes a six-digit SAME code, the same code a weather radio is programmed with. This is the only HTTP call the integration ever makes; nothing is polled afterwards. - A five-character geohash is computed locally from the coordinates. That is the lightning box.
Only one WxAlerts entry exists per Home Assistant instance. One MQTT connection is the whole budget, so adding a second place means adding a zone to the existing entry, not adding the integration again.
When setup refuses
“Select at least one zone.” Nothing was picked.
“None of the selected zones have usable coordinates.” A selected zone has no latitude/longitude attribute. Zones created from a device tracker sometimes land in this state.
“No selected zone resolved to a US county, so alerts cannot be delivered.” Every zone you picked is offshore, marine, or outside the US, and NWS alerts were left on. Those places have no SAME code and never will. Turn NWS alerts off and run lightning-only.
“WxAlerts is already configured.” See above: change zones in the options instead.
Options
Settings → Devices & Services → WxAlerts → Configure:
| Option | Default | What it does |
|---|---|---|
| Zones to watch | zone.home |
The places to follow. Re-resolved on save. |
| NWS alerts | on | Subscribe to the county alert tree. Off removes every alert entity. |
| GLM lightning | on | Subscribe to the lightning tree. Off removes the flash sensors. |
| Lightning box size | 4 | Geohash characters, 3–5. See below. |
| Lightning window | 15 min | Rolling window, 5–60 minutes, that the flash count covers. |
| Per-phenomenon binary sensors | on | The tornado / severe thunderstorm / flash flood set. |
Saving options reloads the entry, which reconnects and repopulates every entity
from the retained feed, so expect a couple of seconds of unavailable, not a
gap in coverage.
Picking a lightning box size
The lightning topic tree is one geohash character per level, so the box size is literally how many levels you subscribe to. Bigger box, more flashes, earlier warning of something approaching, and more noise from storms that will never reach you.
| Characters | Box | Reads as |
|---|---|---|
| 3 | ~156 km | Regional: a line of storms two counties away still counts |
| 4 | ~39 km | County scale, the default |
| 5 | ~4.9 km | Neighborhood: essentially overhead |
Upgrading
From 0.2.0 to 0.2.1: remove and re-add the integration. The lightning
sensor used to be identified by its geohash prefix, which moved whenever you
changed the box size; it is now keyed to the zone. The old entity lingers as
unavailable until you remove the entry.
From 0.1.0: 0.2.0 was a rewrite. Configuration moved from hand-entered NWS zone codes to Home Assistant zones, and no entity, option or event payload carries over. Remove the old integration before installing.