meshcore-bot/docs/weather-service.md

Weather Service

Provides scheduled weather forecasts, weather alerts, and lightning detection.

---

Quick Start

1. Configure Bot - Edit config.ini:

[Weather_Service]
enabled = true

# Your location (required)
my_position_lat = 47.6062
my_position_lon = -122.3321

# Daily forecast time
# Or "sunrise" / "sunset"
weather_alarm = 6:00

# Channels
weather_channel = #weather
alerts_channel = #weather

2. Restart Bot - Daily forecasts start automatically

---

Configuration

Do not put a # comment on the same line as a value. The bot's config parser does not strip inline comments, so poll_rain_nowcast_interval = 900000 # every 15 min is read as the literal string "900000 # every 15 min", getint() raises, and the whole weather service fails to load — no forecasts and no alerts, with only one Failed to load service weather_service line in the log. Inline comments cannot simply be enabled either: # is a legitimate value character here (weather_channel = #weather, flood_scope = #west), so switching them on would blank every channel and scope instead. Put comments on their own line, as below.

Basic Settings

[Weather_Service]
enabled = true
# Your latitude (required)
my_position_lat = 47.6062
# Your longitude (required)
my_position_lon = -122.3321
# Time for daily forecast (HH:MM or sunrise/sunset)
weather_alarm = 6:00
# Channel for forecasts
weather_channel = #weather
# Channel for weather alerts
alerts_channel = #weather

Alert Polling

# Poll NOAA for alerts (default: true)
weather_alerts_enabled = true
# Check every 10 minutes (milliseconds)
poll_weather_alerts_interval = 600000

Set weather_alerts_enabled = false to stop alert monitoring on its own. Daily forecasts, rain nowcasts, storm detection and the weather commands are unaffected, and poll_weather_alerts_interval is then ignored.

Rain Nowcast (Proactive)

Automatically posts a heads-up when rain is about to start at your position:

# Auto-announce incoming rain (opt-in; default: false)
rain_nowcast_enabled = true
# rain_channel = #weather              # Defaults to weather_channel
# Check every 15 minutes (milliseconds)
poll_rain_nowcast_interval = 900000
# Only announce if rain starts within 60 min
rain_nowcast_lead_minutes = 60
# Cooldown between pushes
rain_nowcast_renotify_minutes = 30
# rain_nowcast_announce_ending = true  # Also announce when rain is about to stop
# rain_nowcast_threshold_mm = 0.1      # Sensitivity (mm per 15-min bucket)

Posts both a starting heads-up (rain incoming) and, by default, an ending one (rain about to stop):

🌧️ Heads up — Rain starting in ~25min near Nashville, TN
🌧️ Heads up — Rain ending in ~20min near Nashville, TN

Each fires once per rain episode. Set rain_nowcast_announce_ending = false to only announce incoming rain.

Lightning Detection (Optional)

Requires paho-mqtt library.

# Aggregate lightning every 10 minutes
blitz_collection_interval = 600000

# Define detection area (optional)
blitz_area_min_lat = 47.0
blitz_area_min_lon = -123.0
blitz_area_max_lat = 48.0
blitz_area_max_lon = -121.0

---

Features

Daily Weather Forecast

Sends forecast to weather_channel at configured time:

Example Output:

🌤️ Daily Weather: Seattle: ☀️Clear 68°F NNE8mph | Tomorrow: 🌧️Light Rain 55-72°F

Data Includes:

• Current conditions with emoji
• Temperature
• Wind speed and direction
• Tomorrow's forecast

Scheduling Options:

• Fixed time: weather_alarm = 6:00 (24-hour format)
• Sunrise: weather_alarm = sunrise
• Sunset: weather_alarm = sunset

weather_alarm fires once a day. For more than one forecast a day, or a forecast for a location other than the bot's own position, schedule the wx command instead with a {cmd:...} placeholder:

[Scheduled_Messages]
0 6,12,18 * * * = Public:{cmd:wx Seattle}

That accepts any cron schedule and any location, and works the same way for aqi and other commands. sunrise/sunset are not expressible as cron, so keep using weather_alarm for those.

Rain Nowcast (Proactive)

Watches your position and posts a heads-up to rain_channel (default: weather_channel) when precipitation is about to start, using Open-Meteo's 15-minutely forecast — the same engine as the rain/nowcast command.

Example Output:

🌧️ Heads up — Rain starting in ~25min near Seattle
🌨️ Heads up — Snow starting in ~40min (steady) near Seattle

How It Works:

1. Polls every poll_rain_nowcast_interval (default 15 min)
2. Announces when rain is expected within rain_nowcast_lead_minutes (default 60)
3. Fires once per rain episode — re-arms only after the forecast clears
4. A rain_nowcast_renotify_minutes cooldown (default 30) absorbs forecast flapping
5. (steady) marks prolonged rain (continues past the look-ahead window)

Works worldwide (no API key). Set rain_nowcast_enabled = false to disable.

Weather Alerts (US Only)

Monitors NOAA weather alerts and posts new alerts to alerts_channel. Set weather_alerts_enabled = false to disable, as with the rain nowcast above:

Example Output:

🟡Wind Adv Seattle til 9PM by NWS SEA https://is.gd/abc123

Alert Types:

• Warnings (tornado, severe thunderstorm, etc.)
• Watches (winter storm, flood, etc.)
• Advisories (wind, fog, etc.)
• Statements (special weather)

Compact Format:

• Severity emoji (🔴🟠🟡⚪)
• Event type and location
• Expiration time
• Issuing office
• Shortened URL for details

Lightning Detection (Optional)

Monitors real-time lightning strikes via Blitzortung MQTT:

Example Output:

🌩️ Bellevue (15km NE)

How It Works:

1. Connects to Blitzortung MQTT broker
2. Filters strikes within configured blitz_area
3. Aggregates strikes every blitz_collection_interval
4. Reports areas with 10+ strikes

---

Weather Data Source

Uses Open-Meteo API (free, no API key required).

Temperature Units: Inherited from [Weather] section (see Weather command docs):

[Weather]
# fahrenheit or celsius
temperature_unit = fahrenheit
# mph, kmh, ms or kn
wind_speed_unit = mph
# inch or mm
precipitation_unit = inch

---

Alerts (US Only)

Weather alerts use NOAA API which is US-only. For other countries:

• Daily forecasts work worldwide via Open-Meteo
• Weather alerts won't be available
• Lightning detection works worldwide via Blitzortung

The service stops polling on its own once the NOAA API reports no coverage, so leaving alerts enabled outside the US is harmless; weather_alerts_enabled = false skips the attempt entirely.

---

Troubleshooting

Service Not Starting

Check logs:

tail -f meshcore_bot.log | grep WeatherService

Common issues:

• Missing my_position_lat or my_position_lon
• Invalid coordinates
• enabled = false

No Daily Forecasts

1. Check alarm time - Service logs "Next forecast at HH:MM:SS"
2. Check channel - Verify weather_channel exists
3. Check position - Coordinates must be valid

No Weather Alerts

1. US only - NOAA alerts only work in the United States
2. Check polling - Service logs "Starting weather alerts polling". If it logs "Weather alert polling disabled" instead, weather_alerts_enabled is false
3. New alerts only - Only alerts issued since last check are sent

Lightning Not Working

1. Check dependencies: pip install paho-mqtt
2. Check area config - All 4 coordinates required (min/max lat/lon)
3. Check MQTT connection - Service logs "Connected to Blitzortung MQTT"

---

Advanced

Sunrise/Sunset Forecasts

When using weather_alarm = sunrise or sunset:

• Calculates time based on your coordinates
• Updates daily for seasonal changes
• Uses local timezone automatically

Alert Deduplication

Alerts are tracked by ID to prevent duplicates. The service maintains a list of seen alert IDs and only sends new alerts.

Lightning Strike Bucketing

Strikes are grouped by:

• Direction (heading from your location)
• Distance (grouped in 10km buckets)

Example: All strikes 50-60km to the NE are counted as one area.

---

FAQ

Q: Do I need an API key? A: No. Open-Meteo is free and doesn't require an API key.

Q: Can I get alerts for other countries? A: Daily forecasts work worldwide. Weather alerts are currently US-only (NOAA). If you would like added, let me know.

Q: How accurate are the forecasts? A: Open-Meteo uses data from national weather services (NOAA, DWD, etc.). Accuracy varies by location.

Q: Can I change temperature units? A: Yes, set temperature_unit (and wind_speed_unit, precipitation_unit) in the [Weather] section. The wx and gwx commands use the same settings, NOAA replies included.

Q: Does lightning detection work worldwide? A: Yes. Blitzortung has global coverage.

Q: Why do I need to define a lightning detection area? A: To filter strikes. Without an area, you'd get alerts for the entire globe.