⛈️ WX (Weather Alerts)

WX (Weather Alerts) is a MeshMonitor Script Auto Responder that provides NOAA/NWS weather alert bulletins for a configured latitude/longitude over Meshtastic, MeshCore, or any other mesh network MeshMonitor supports.

This repository contains:

• mm_wx.py — the MeshMonitor script (runtime)
• docs/ — GitHub Pages documentation (display only)

---

What this does

WX supports TWO modes:

1. Automatic alerts (recommended)

   • Uses MeshMonitor Timer Triggers (Timed Events) to run the script on a schedule
   • Script dedupes alerts and only posts when something is NEW, UPDATED, or CLEARED

2. On-demand commands

   • !wx summary
   • !wx detail N
   • !wx help

Design goals:

• KISS: location is configured as latitude/longitude
• Lightweight messages that work well over LoRa
• No NOAA audio rebroadcast — this is text-based alerting using official NWS data

---

Repository layout

.
├── mm_wx.py              # Runtime script used by MeshMonitor
├── docs/                 # GitHub Pages documentation
│   ├── index.html
│   ├── index.js
│   └── assets/           # Screenshots/images for docs + README
└── README.md

---

IMPORTANT: Which file do I use?

Use this file in MeshMonitor

mm_wx.py

This is the only file MeshMonitor should execute.

Do NOT run this file

docs/index.js

index.js only displays the script on a web page.

---

Installing mm_wx.py

MeshMonitor script requirements (high level):

• Script must be in /data/scripts/
• Script must output valid JSON to stdout with response or responses
• Must complete within the MeshMonitor timeout window
• Must be executable

Copy the script into the MeshMonitor container:

/data/scripts/mm_wx.py

Make it executable:

chmod +x /data/scripts/mm_wx.py

---

Recommended install (pin to a release tag)

For stable deployments, install from a release tag (replace vX.Y.Z with the latest release tag):

docker exec -it meshmonitor sh -lc "
wget -O /data/scripts/mm_wx.py https://raw.githubusercontent.com/maxhayim/meshmonitor-mx-weather-alerts/vX.Y.Z/mm_wx.py &&
chmod +x /data/scripts/mm_wx.py &&
python3 -m py_compile /data/scripts/mm_wx.py &&
echo OK
"

Using a pinned tag (instead of main) ensures your container always runs the exact released version.

---

Configuration (inside mm_wx.py)

Edit these constants near the top of mm_wx.py:

Required:

• WX_LAT
• WX_LON
• WX_LOCATION_LABEL — human-readable city, place, or zip code shown in every alert header (summary, detail, NEW/UPDATED/CLEARED bulletins, help). Without this, alerts on a shared mesh channel or across multiple WX deployments give no clue which location they're for.

Optional:

• WX_SEVERITIES_ALLOW
• WX_EVENTS_BLOCK
• WX_TIMER_SILENT_NOCHANGE
• WX_STATE_PATH
• WX_TIMER_SCHEDULE_NOTE (documentation only)
• WX_USER_AGENT (recommended to include contact info)

Recommended (network resilience / mesh noise control):

• HTTP_RETRIES (default: 3)
• HTTP_RETRY_SLEEP_SECONDS (default: 2)
• TIMER_SILENT_ON_FETCH_ERROR (recommended ON to avoid mesh spam during transient DNS/network issues)

---

Automatic Alerts (Timer Triggers / Timed Events) — RECOMMENDED

MeshMonitor can run scripts automatically using Timer Triggers (Timed Events). When the timer fires, MeshMonitor executes the script and sends the script output to the configured channel.

Step-by-step setup

1. Open MeshMonitor
2. Go to Info → Automation
3. Scroll to Timer Triggers (Timed Events)
4. Add a timer:
   • Name: WX (Weather Alerts)
   • Schedule: */5 * * * * (every 5 minutes)
   • Script: mm_wx.py
   • Channel: 0 (Primary) or any desired channel
   • Enabled: On
5. Click Add Timer
6. Click Save

---

How deduplication works (no mesh spam)

• On each timer run, WX (Weather Alerts) fetches active alerts for the configured latitude/longitude

• Each alert is fingerprinted (ID + timestamps)

• State is stored persistently in:

  /data/wx_state.json

• Messages are only sent when alerts are:

  • NEW (not previously active)
  • UPDATED (timing or content changed)
  • CLEARED (previously active but no longer present)

If you want a heartbeat message even when nothing changes, set:

WX_TIMER_SILENT_NOCHANGE = False

(Default behavior is silent when there are no changes.)

---

MeshMonitor Auto Responder configuration (optional)

If you want on-demand commands in addition to automatic alerts, create Auto Responder rules.

Recommended settings for all triggers:

• Response Type: Script
• Script Path: /data/scripts/mm_wx.py
• Channel: Direct Messages (recommended to start)
• Enable Multiline: ON
• Verify Response: OFF

Rule 1 — WX summary

Trigger regex:

^!wx$

Response Type: Script
Script path:

/data/scripts/mm_wx.py

Rule 2 — WX detail

Trigger regex:

^!wx\s+detail\s+([0-9]+)$

Response Type: Script
Script path:

/data/scripts/mm_wx.py

Rule 3 — WX help

Trigger regex:

^!wx\s+help$

Response Type: Script
Script path:

/data/scripts/mm_wx.py

---

Example Triggers

!wx
!wx detail 1
!wx help

---

Screenshots

---

Packaging / Dependencies (PEP 668 safe)

WX (Weather Alerts) uses Python standard library only.

There are no pip or third-party dependencies, which avoids issues with PEP 668 / externally-managed Python environments inside containers.

If your MeshMonitor container has Python 3, the script will run without installing anything.

---

DNS / Connectivity Troubleshooting (Docker)

If WX (Weather Alerts) reports DNS failures, connection errors, or cannot reach api.weather.gov, the issue is almost always Docker or host DNS configuration (or transient resolver/network events).

Verify DNS inside the container

docker exec -it meshmonitor sh -lc "getent hosts api.weather.gov || true; echo '---'; cat /etc/resolv.conf"

Verify outbound HTTPS from the container

docker exec -it meshmonitor sh -lc "wget -S -O- --timeout=10 https://api.weather.gov/alerts/active?point=25.7617,-80.1918 2>&1 | head -n 20"

If DNS resolves and HTTPS works, but you still see occasional URL error: [Errno -3] Try again, this is typically a transient DNS condition. The script includes retry/backoff, and you can keep timer runs quiet via TIMER_SILENT_ON_FETCH_ERROR.

Recommended docker-compose DNS override

Add the following to your MeshMonitor service in docker-compose.yml:

services:
  meshmonitor:
    dns:
      - 1.1.1.1
      - 8.8.8.8

Redeploy:

docker compose up -d

Host-level Docker daemon DNS (if needed)

Create or edit /etc/docker/daemon.json:

{
  "dns": ["1.1.1.1", "8.8.8.8"]
}

Restart Docker:

sudo systemctl restart docker

---

NWS API notes

• WX (Weather Alerts) queries active alerts by point:
  • https://api.weather.gov/alerts/active?point=LAT,LON
• The National Weather Service may rate-limit or block generic clients.
• Keep WX_USER_AGENT set to a real identifier with contact information.

---

Maintenance / Reinstall (Advanced)

These steps are only needed if you are upgrading versions, changing core configuration (e.g. latitude/longitude), or troubleshooting unexpected behavior.

This is not required for normal operation.

---

Disable WX (Weather Alerts) in MeshMonitor

1. Open MeshMonitor
2. Go to Info → Automation
3. Under Timer Triggers (Timed Events):
   • Disable the WX (Weather Alerts) timer
4. (Optional) Remove Auto Responder rules for:
   • ^!wx$
   • ^!wx\s+detail\s+([0-9]+)$
   • ^!wx\s+help$
5. Click Save

---

Remove script and state (inside container)

Enter the MeshMonitor container:

docker exec -it meshmonitor sh

Remove the WX runtime script:

rm -f /data/scripts/mm_wx.py

Remove the persistent deduplication state:

rm -f /data/wx_state.json

Exit the container:

exit

---

Reinstall WX (Weather Alerts)

Recommended: reinstall from a release tag (replace vX.Y.Z with the latest release tag):

docker exec -it meshmonitor sh -lc "
wget -O /data/scripts/mm_wx.py https://raw.githubusercontent.com/maxhayim/meshmonitor-mx-weather-alerts/vX.Y.Z/mm_wx.py &&
chmod +x /data/scripts/mm_wx.py &&
python3 -m py_compile /data/scripts/mm_wx.py &&
echo OK
"

Then re-enable the WX (Weather Alerts) Timer Trigger in MeshMonitor and click Save.

On the next timer run, WX will rebuild its state and resume normal operation.

---

Inspiration & references

• NOAA / NWS Weather Radio alerting concepts (SAME / UGC-style targeting)
• Inspired by SkywarnPlus

WX (Weather Alerts) is not affiliated with NOAA and does not rebroadcast NOAA audio.
It provides text-based alerting for Meshtastic, MeshCore, and any other mesh network MeshMonitor supports, using official NWS alert data.

---

License

This project is licensed under the MIT License.

See the LICENSE file for details.
Full license text: https://opensource.org/licenses/MIT

---

Contributing

Pull requests are welcome. Open an issue first to discuss ideas or report bugs.

---

Acknowledgments

• MeshMonitor built by Yeraze
• Shout out and inspired by SkywarnPlus

Discover other community-contributed scripts for MeshMonitor: https://meshmonitor.org/user-scripts.html