US Drought Monitor smart home integration, free and open source
Drought level of your county from the US Drought Monitor: categories D0 to D4, changes, triggers.
Published by guim31
- Devices
- Version 1.0.0
- Requires Gladys >=5.3.0
- ★ 0
The drought level of your county, from the US Drought Monitor (USDM), the weekly drought map of the United States produced by the National Drought Mitigation Center (University of Nebraska-Lincoln), the USDA and NOAA. One device per county you follow, with its drought category, the share of the county in each category and the change over 1 and 4 weeks; scene triggers when the drought gets worse, reaches a level or improves; a sentence ready for a notification; and a dashboard widget in the colours of the USDM map.
The USDM describes drought; it does not set water restrictions: they are decided by your city, county or water utility.
What you get
- one device per county, with its level (0 to 5), its category ("D2 · Severe drought"), the share of the county in D1 or worse, D2 or worse, D3 or worse and D4, the change over 1 and 4 weeks and the date of the map;
- three scene triggers: the drought gets worse, reaches a level, improves;
- a scene action that returns the latest map in one sentence;
- a dashboard widget with the shares of each category as a strip in the official USDM colours.
Requirements
- Gladys Assistant 5.3 or later.
- Internet access from Gladys (the USDM data services, no account, no key).
- The 5-digit FIPS code of your county (see below).
Configuration
- Find the FIPS code of your county: 2 digits for the state, 3 for the county. Harris County, Texas is 48201; Los Angeles County, California is 06037. The US Census lists them all (https://www.census.gov/library/reference/code-lists/ansi.html), and a search for "FIPS code" and your county name gives it too.
- In the Configuration tab, type the codes, separated by commas, and save.
- Create the devices in the Discover tab.
Settings
- County FIPS codes — 10 counties at most. A code the USDM does not know is reported in the status of the integration, and no device is offered for it. A 4-digit code is read with a leading zero (6037 is 06037).
- Share needed for a category — the level of a county is the strongest category covering at least this share of its area, 1 % by default. The USDM draws its categories on a map: in a large county, a sliver of D3 on its edge says little about your house. Choose "Any share" to follow the strongest category touching the county, or a higher share to follow the most of it.
- Language of the feature names — names of the new features, and language of their texts (categories, changes, dates, scene variables and summary).
Devices
| Feature | Content |
|---|---|
| Drought level (0–5) | 0 no drought, 1 D0 abnormally dry, 2 D1 moderate, 3 D2 severe, 4 D3 extreme, 5 D4 exceptional |
| Drought category | "D2 · Severe drought", "No drought" |
| Area in D1 or worse | share of the county in drought, in % |
| Area in D2/D3 or worse | share of the county in D2 or worse, D3 or worse, in % |
| Area in D4 | share of the county in exceptional drought, in % |
| Change over 1 / 4 weeks | "D1 → D2, worse · D1+ +12.5 pts": levels, and change of the D1+ share in points |
| Map date | the Tuesday the map describes |
D0 (abnormally dry) is not a drought for the USDM: it marks an area going into or coming out of drought. It is a level of its own here.
The shares follow the USDM: "D2 or worse" includes D3 and D4. The level, category and shares keep their history.
Dashboard widget
US drought: the county chosen (or the first one followed), with its name in Gladys, a strip cut in the share of each category in the colours of the USDM legend (dark red D4, red D3, orange D2, tan D1, yellow D0, grey without drought), the category, the shares and the changes, and the map date. Each block can be hidden in the widget settings.
Scene triggers
- Drought gets worse — a new weekly map puts the county in a stronger category than the previous map.
- Drought reaches a level — a new map puts the county in the chosen category (D0 to D4) or a stronger one, coming from a weaker one.
- Drought improves — a new map puts the county in a weaker category.
Each trigger can be limited to one county. They fire once per new map (Thursday) and never on the first map read, which only sets the reference. Variables: county, category (none, D0 to D4), previous category, category name, level (0–5), area in D1 or worse, map date.
Scene action
Drought: get the county map in one sentence returns, for the chosen county (or the first one followed), a sentence such as "Harris County, TX, map of Nov 3, 2026: D3 · Extreme drought, 83.2% of the county in drought (D1+). Worse than 4 weeks ago.", and the category, level, shares and map date for the following actions.
Scene examples
- Drought reaches D2 → notification "Think about watering restrictions: check your city's rules."
- Every Thursday evening → get the sentence and send it on Telegram.
- Drought improves → turn the garden watering schedule back to normal.
Data sources, licence and quotas
- US Drought Monitor data services,
usdmdataservices.unl.edu, county statistics in percent of area. No account, no key, no documented quota. - The map is drawn with the data of Tuesday and published on Thursday. The integration reads each county once a day, and every 3 hours from Thursday afternoon (UTC) until the new map is there: a few requests per county and per day.
- "The U.S. Drought Monitor is jointly produced by the National Drought Mitigation Center at the University of Nebraska-Lincoln, the United States Department of Agriculture, and the National Oceanic and Atmospheric Administration. Map courtesy of NDMC."
- Not affiliated with the US Drought Monitor, the NDMC, the USDA or NOAA.
Troubleshooting
- No device in the Discover tab — check the FIPS codes: a code the USDM does not know is named in the status of the integration.
- "Cannot be read" status — the USDM data services do not answer; the integration tries again every hour and keeps the last map for three weeks.
- Logs: the integration logs page of Gladys;
LOG_LEVEL=debugfor the detail of each read.
Limits
- United States only, county level (no city or ZIP code).
- Weekly data: the map of Thursday describes the Tuesday before.
- Water restrictions are not part of the USDM: ask your city or water utility.
- After three weeks without a new map, the devices stop receiving values.
Configuration settings
These are the settings US Drought Monitor asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your counties | section | No | Type the 5-digit FIPS code of each county to follow (Harris County, Texas: 48201): one device per county, with its drought category, the share of its area in each category and the change over 1 and 4 weeks. Save, then create the devices in the Discover tab. |
| Sources and limits | section | No | Map of the US Drought Monitor (NDMC, USDA, NOAA), read without an account, published every Thursday with the data of Tuesday. It does not set water restrictions: they depend on your city or water utility. Not affiliated with the US Drought Monitor. |
| County FIPS codes | string | No | 5 digits each, separated by commas, 10 at most. |
| Share needed for a category | select | No | The level of a county is the strongest category covering at least this share of its area. |
| Language of the feature names | select | No | Names given to the new features, and language of their texts (categories, changes, dates, scene variables and summary). |
How to install US Drought Monitor in Gladys
- In Gladys, open Integrations: US Drought Monitor appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-us-drought:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-us-drought.
US Drought Monitor requires Gladys >=5.3.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
US Drought Monitor is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation