+
+ Everything you need to understand and configure MeshAI's monitoring and alerting systems.
+
+
+ {/* Stream Gauges */}
+
+ What You're Looking At
+
+ MeshAI watches river and stream levels at gauges you configure. Each gauge reports two things:
+
+
+ Water Level (Gage Height) — how high the water is, measured in feet. Important: this is NOT the depth of the river. It's the height above a fixed measuring point that's different at every gauge. A reading of "10 feet" at one gauge means something completely different than "10 feet" at another. You can only compare readings from the SAME gauge over time.
+
+
+ Flow (Discharge) — how much water is moving past the gauge, in cubic feet per second (CFS). Think of it as the river's "throughput." For scale:
+
+
+ - A small creek: 50-200 CFS
+ - A mid-size river: 1,000-5,000 CFS
+ - A big river in spring runoff: 10,000+ CFS
+
+
+ When Does It Flood?
+
+ Flood levels are set by the National Weather Service, not USGS. NWS looks at each specific gauge location and decides "at what water level does the road flood? At what level do buildings get water?" Those levels are different everywhere.
+
+ Action Stage — water is rising, time to start paying attention. Usually still inside the riverbanks.
+ Minor Flood — low-lying roads start getting water on them. NWS issues a Flood Advisory.
+ Moderate Flood — water in buildings near the river. Some people need to evacuate. NWS issues a Flood Warning.
+ Major Flood — widespread flooding. Many people evacuating. Serious property damage.
+
+ MeshAI automatically looks up the flood levels for your gauge from NWS when you add a site. Some remote gauges don't have flood levels assigned — for those, you set them manually if you know what water levels cause problems in your area.
+
+
+ Low Water / Drought
+
+ There's no official "drought stage" for most gauges. If you need to monitor low water (irrigation, fish habitat), set a manual low-water threshold based on what you know about your local river.
+
+
+ Setting It Up
+
+ - Find your gauge at waterdata.usgs.gov/nwis
+ - Copy the site number (like 13090500)
+ - Add it in Config → Environmental → USGS
+ - MeshAI auto-fills the gauge name and flood levels from NWS
+
+ If NWS flood levels don't populate, your gauge may not have them. Set manual thresholds if you know your local conditions.
+
+ Learn More
+
+ - USGS Water Data — find gauges near you
+ - NWS Water Prediction Service — flood forecasts and thresholds
+ - Understanding Streamflow — USGS explainer
+
+
+
+ {/* Wildfire */}
+
+ What You're Looking At
+
+ MeshAI tracks active wildfire perimeters from the National Interagency Fire Center (NIFC). For each fire, you see the name, size, how much is contained, and how far it is from your mesh nodes.
+
+
+ Fire Size — How Big Is It?
+
+ For reference, 1,000 acres is about 1.5 square miles.
+
+ Containment — Is It Under Control?
+
+ Containment means the percentage of the fire's edge where firefighters have built a control line (a cleared strip to stop the fire from spreading further). It does NOT mean the fire is out inside that line.
+
+
+ - 0-30% — Essentially uncontrolled. The fire goes where it wants.
+ - 50% — Good progress, but half the edge can still grow.
+ - 80%+ — Well controlled. Major growth unlikely.
+ - 100% — The edge is fully controlled. But the fire may STILL be actively burning inside. "100% contained" does NOT mean "out."
+
+
+ How Far Away Should I Worry?
+ Under 5 km (3 miles), <>Immediate threat. This is evacuation-order range. Embers can fly this far in wind.],
+ [<> 5-15 km (3-10 miles), <>Prepare. The fire could reach you in hours under bad conditions. Have a plan.],
+ [<> 15-30 km (10-20 miles), <>Watch. Smoke is likely. Wind shifts could change things fast.],
+ [<> Over 30 km (20 miles), <>Awareness. Keep an eye on it, but no immediate threat.],
+ ]}
+ />
+
+ How fast can a fire travel? In grass with wind: up to 14 mph. In heavy timber: 1-6 mph. A fire 10 miles away could theoretically reach you in 1-2 hours under worst-case conditions, but typical spread is much slower.
+
+
+ Which Matters More — Size or Distance?
+
+ Distance is the immediate concern. A small uncontained fire 10 km away is more dangerous right now than a huge fire 50 km away. But big fires have more energy and can grow fast under wind shifts — keep watching them.
+
+
+ Setting It Up
+
+ Just configure your state code (like US-ID for Idaho) in Config → Environmental → Fires. MeshAI polls NIFC every 10 minutes for active fires in that state and computes the distance to your mesh nodes automatically.
+
+
+ Learn More
+
+ - InciWeb — detailed incident information
+ - NIFC Fire Map — raw perimeter data
+ - Ready.gov Wildfires — preparedness guide
+
+
+
+ {/* FIRMS */}
+
+ What You're Looking At
+
+ NASA's VIIRS satellites orbit the Earth and look for heat signatures on the ground. When they see something hot — a fire, a factory, a sunlit building — they flag it as a "hotspot." MeshAI checks these detections for your area.
+
+
+ Why this matters: satellite hotspots show up hours before official fire perimeters are mapped. If a new fire starts near your mesh, the satellite might see it before anyone on the ground reports it.
+
+
+ Confidence — Is It Really a Fire?
+ Each detection gets a confidence rating:
+
+
+ Recommendation: Set the filter to "Nominal + High." If you include "Low" you'll get alerts for every hot parking lot on a summer day.
+
+
+ FRP — How Intense Is It?
+ FRP (Fire Radiative Power) measures the heat output in megawatts. Think of it as "how hot is this thing":
+
+ Setting the minimum FRP to 5 MW filters out most industrial and agricultural false alarms.
+
+ New Ignition Detection
+
+ MeshAI cross-references satellite hotspots against known NIFC fire perimeters. If a hotspot is NOT near any known fire, it gets flagged as a potential new ignition — maybe a new fire just started. These get elevated priority regardless of confidence level.
+
+
+ Timing
+
+ Satellite data arrives 1-3 hours after the satellite passes overhead. Each location gets observed about 6 times per day across all satellites, so there are multi-hour gaps. This is not real-time — it's "pretty recent."
+
+
+ Getting an API Key
+
+ - Go to FIRMS API page
+ - Click "Get MAP_KEY"
+ - Register for a free Earthdata account
+ - Your key arrives by email
+ - Enter it in Config → Environmental → FIRMS
+
+
+ Learn More
+
+ - FIRMS Fire Map — see hotspots on a map
+ - FIRMS FAQ — how it works
+
+
+
+ {/* Weather Alerts */}
+
+ What You're Looking At
+
+ MeshAI watches for NWS (National Weather Service) alerts affecting your area — warnings, watches, and advisories.
+
+
+ Alert Severity — How Serious Is It?
+
+
+ When Should I Act? (Urgency)
+
+
+ How Sure Are They? (Certainty)
+
+
+ These Are Separate Scales
+
+ A single alert has all three. A hurricane warning for next week is "Severe + Future + Likely." A tornado spotted on the ground is "Extreme + Immediate + Observed." An air quality advisory is "Minor + Expected + Possible."
+
+
+ What Minimum Severity Should I Set?
+ Moderate ✓, 'Watches, Advisories, and Warnings', 'Special Weather Statements'],
+ ['Severe', 'Only Warnings — things happening NOW', 'Watches (which give you hours of advance warning)'],
+ ['Extreme', 'Only the rarest events', 'Most Tornado and Severe Thunderstorm Warnings'],
+ ]}
+ />
+
+ Moderate is recommended. It catches Watches (advance warning that conditions may worsen) and Advisories (conditions exist but aren't severe) while filtering out the informational stuff.
+
+
+ Finding Your NWS Zone
+
+ - Go to weather.gov
+ - Enter your location
+ - Find your zone code at NWS Zone Map
+ - Zone codes look like: IDZ016, UTZ040, etc.
+
+
+ The User-Agent Field
+
+ NWS wants to know who's using their API — not for approval, just so they can contact you if something breaks. You make it up:
+
+ (meshai, you@email.com)
+ No registration. No waiting. Just type it in.
+
+ Learn More
+
+ - NWS Active Alerts — see current alerts
+ - NWS API Docs — technical details
+
+
+
+ {/* Solar & Geomagnetic */}
+
+ What You're Looking At
+
+ MeshAI tracks space weather — solar activity and its effects on Earth's magnetic field. This matters for radio operators because the sun directly controls how well HF radio works, and major solar events can affect all radio communications.
+
+
+ Solar Flux Index (SFI)
+ Think of SFI as a "how active is the sun" number. Higher = better for HF radio, but also higher risk of solar flares.
+
+ Quick rule: SFI above 90 and Kp below 4 = good day for HF radio.
+
+ Kp Index
+ Kp measures how disturbed Earth's magnetic field is, on a 0-9 scale. Higher = more disturbance = worse for HF radio but better for aurora viewing.
+ 5, <>Minor storm (G1). HF noticeably degraded. Aurora visible at high latitudes (~60°N).],
+ [6, <>Moderate storm (G2). HF getting rough. Aurora moving south (~55°N).],
+ [7, <>Strong storm (G3). HF unreliable for 1-2 days. Aurora at mid-latitudes.],
+ [8-9, <>Severe/Extreme storm. HF may black out completely. Aurora visible at very low latitudes. Power grid stress possible.],
+ ]}
+ />
+
+ R / S / G Scales
+ NOAA's shorthand for three types of space weather events:
+ R (Radio Blackouts) — from solar flares:
+
+ - R1-R2: Brief HF disruption. You might not notice.
+ - R3: HF goes out for about an hour on the sunlit side of Earth.
+ - R4-R5: HF dead for hours. Serious.
+
+ S (Solar Radiation Storms) — from energetic particles:
+
+ - Mostly affects polar regions and satellites
+ - S3+: Polar HF goes out entirely
+
+ G (Geomagnetic Storms) — from solar wind disturbances:
+
+ - Same as the Kp scale: G1 = Kp 5, up to G5 = Kp 9
+
+
+ Bz — The Storm Predictor
+
+ Bz measures the direction of the solar wind's magnetic field. When it points south (negative values), the solar wind can dump energy into Earth's magnetic field, causing storms.
+
+
+ Bz can change fast — minute to minute. What matters is whether it stays negative for hours, not brief dips.
+
+ Learn More
+
+ - SWPC Space Weather Dashboard — live data
+ - NOAA Space Weather Scales — what R/S/G mean
+ - HamQSL Solar Page — ham-friendly display
+ - Planetary K-Index — live Kp
+
+
+
+ {/* Tropospheric Ducting */}
+
+ What You're Looking At
+
+ Sometimes the atmosphere creates an invisible "pipe" that traps radio signals and carries them much farther than normal. This is called tropospheric ducting. It mostly affects VHF and UHF frequencies.
+
+
+ MeshAI watches for these conditions by analyzing weather data (temperature and humidity at different altitudes) over your mesh area.
+
+
+ How Do I Know If Ducting Is Happening?
+ MeshAI reports a "condition" based on the atmospheric profile:
+
+
+ What You'll Actually Notice
+ When ducting happens on your mesh:
+
+ - Distant repeaters you've never heard suddenly come in
+ - Nodes appear from far outside your normal range
+ - You hear FM radio stations from other cities
+ - ADS-B flight tracking range gets much longer
+ - There might be interference from distant stations on your frequency
+
+
+ The dM/dz Number
+ The dashboard shows a "dM/dz" value in "M-units/km." You don't need to understand the math — just know:
+
+ - Around 118 = normal atmosphere
+ - Below 79 = enhanced propagation starting
+ - Below 0 (negative) = ducting is happening
+ - Below -50 = strong ducting — classic VHF/UHF DX event
+
+
+ When Does Ducting Happen?
+
+ - Under high-pressure weather systems (clear, stable air)
+ - When warm air sits on top of cool air (temperature inversion)
+ - Most common in late summer and early fall
+ - Strongest along coastlines and over water
+ - In mountain valleys: cold air pooling in fall/winter can create surface ducts
+
+
+ Setting It Up
+
+ Just configure the latitude and longitude of the center of your mesh area in Config → Environmental → Ducting. MeshAI checks the atmospheric conditions there every 3 hours using free weather model data. No API key needed.
+
+
+ Learn More
+
+ - Tropo Forecast Maps (Hepburn) — 6-day tropo prediction
+ - DX Maps — real-time VHF/UHF propagation reports
+ - Wikipedia: Tropospheric Propagation — background
+
+
+
+ {/* Avalanche Danger */}
+
+ What You're Looking At
+
+ MeshAI pulls avalanche forecasts from your regional avalanche center during winter months. The danger scale has 5 levels and it's the same across all of North America.
+
+
+ The Danger Scale
+ , 'Generally safe. Normal caution in steep terrain.'],
+ ['2', 'Moderate', , 'Be careful on specific terrain features. Evaluate conditions.'],
+ ['3', 'Considerable', , <>DANGEROUS. This is where most people die in avalanches — they see "3 out of 5" and think it's fine. It's not. Use extreme caution.],
+ ['4', 'High', , <>Very dangerous. Stay off anything steep.],
+ ['5', 'Extreme', , <>Don't go out. Avalanches are happening on their own.],
+ ]}
+ />
+
+ The Most Important Thing to Know
+
+ Level 3 (Considerable) kills more people than any other level. People look at "3 out of 5" and think "middle of the road, probably okay." In reality, the risk roughly doubles at each step up the scale. Level 3 is where dangerous conditions overlap with people thinking they can handle it.
+
+
+ Seasonal
+
+ MeshAI only checks avalanche conditions during winter months (configurable, default December through April). Outside season, it shows "off season" and saves API calls.
+
+
+ Finding Your Avalanche Center
+
+ Go to avalanche.org/avalanche-centers/ for a map. Common center codes:
+
+
+ - SNFAC — Sawtooth (central Idaho)
+ - UAC — Utah
+ - NWAC — Cascades/Olympics (WA/OR)
+ - CAIC — Colorado
+ - SAC — Sierra Nevada (CA)
+ - GNFAC — Gallatin (SW Montana)
+
+
+ Learn More
+
+ - Avalanche.org — US forecasts
+ - Avalanche Danger Scale — full scale explanation
+ - Know Before You Go — avalanche awareness
+
+
+
+ {/* Traffic Flow */}
+
+ What You're Looking At
+
+ MeshAI monitors traffic speed on road segments you configure, using data from TomTom (real vehicles with navigation apps reporting their speed).
+
+
+ Speed Ratio — The Key Number
+ MeshAI compares current speed to "free-flow speed" (what traffic normally does when the road is empty). The ratio tells you how congested it is:
+ Above 85%, 'Normal. Traffic flowing fine.'],
+ [<> 65-85%, 'Slow. Heavier than usual but moving.'],
+ [<> 40-65%, 'Congested. Significant delays.'],
+ [<> Below 40%, 'Gridlock. Barely moving.'],
+ ]}
+ />
+
+ Note: "free-flow speed" is NOT the speed limit. It's what traffic actually does on that road when nobody's in the way. Drivers often exceed speed limits on open highways.
+
+
+ Confidence — Can You Trust the Data?
+ TomTom's confidence score tells you how much of the reading comes from real vehicles right now vs historical averages:
+ Unreliable — mostly guessing from historical patterns. Don't alert on this.],
+ ]}
+ />
+ Set minimum confidence to 0.7 to avoid false congestion alerts at night or on rural roads where few probe vehicles drive.
+
+ Setting Up Corridors
+ Each "corridor" is a point on a road you want to monitor. To add one:
+
+ - Go to Google Maps, find the road
+ - Right-click the road → "What's here?" → copy the coordinates
+ - Add the corridor in Config with a name and those coordinates
+ - TomTom finds the nearest road segment automatically
+
+
+ Getting an API Key
+
+ - Sign up at developer.tomtom.com (free)
+ - Create an app → get your API key
+ - Free tier: 2,500 requests/day (plenty for 5-10 corridors)
+
+
+ Learn More
+
+ - TomTom Developer Portal — API docs and key signup
+ - TomTom Traffic Index — city congestion rankings
+
+
+
+ {/* 511 Road Conditions */}
+
+ What You're Looking At
+
+ 511 systems report road closures, construction, weather events, mountain pass conditions, and incidents. Every state runs their own 511 system — there is no national API.
+
+
+ Setting It Up
+
+ You need to find YOUR state's 511 developer API. MeshAI does not include a default URL because every state is different. Some states have free public APIs, some require registration, and some don't have developer APIs at all.
+
+ Configure in Config → Environmental → 511:
+
+ - Base URL — your state's API endpoint
+ - API Key — if required by your state
+ - Endpoints — which data feeds to poll (varies by state)
+
+
+ Learn More
+ Check your state's 511 or DOT website for developer information.
+
+
+ {/* Mesh Health */}
+
+ Health Score
+ MeshAI computes a 0-100 health score for your mesh network by looking at five areas:
+
+
+ Health Tiers
+ Healthy, "Everything's working well."],
+ ['75-89', <> Slight degradation, 'Some issues but the mesh is functional.'],
+ ['50-74', <> Unhealthy, 'Multiple problems. Reliability is affected.'],
+ ['25-49', <> Warning, 'Significant issues. The mesh is struggling.'],
+ ['0-24', <> Critical, 'Major failures. Barely functional.'],
+ ]}
+ />
+
+ Channel Utilization — Is the Radio Channel Full?
+
+ Meshtastic radios share one LoRa channel. If too many nodes are transmitting too often, they step on each other and messages get lost.
+
+ Under 25%, 'Healthy. The firmware itself starts throttling above 25% to protect the channel — so under 25% is the target.'],
+ [<> 25-40%, 'Getting busy. Common on larger meshes. Worth watching.'],
+ [<> 40-50%, 'Congested. The firmware throttles GPS updates above 40%. Messages are colliding and retrying.'],
+ [<> Over 50%, 'Serious problem. More time is spent retrying than communicating. Mesh reliability drops fast.'],
+ [<> Over 65%, 'Documented failure point on busy LONG_FAST meshes. The mesh becomes unusable.'],
+ ]}
+ />
+
+ Packet Flooding
+
+ ⚠️ "Packet flooding" means a node sending too many RADIO PACKETS. This has nothing to do with water flooding.
+
+
+ A normal Meshtastic node sends a packet every few minutes (announcing itself, reporting telemetry, updating position). If a node starts blasting packets every few seconds, something is wrong — firmware bug, stuck transmitter, or misconfiguration.
+
+
+
+ Battery Levels
+
+ Most Meshtastic radios (T-Beam, RAK4631, Heltec V3) use a single lithium battery cell. The voltage tells you how much charge is left:
+
+ 3.60V, ~30%, <>⚠️ Warning — charge it soon],
+ [3.50V, ~15%, <>🔴 Low — charge it now],
+ [3.40V, ~7%, <>⚫ About to die],
+ ['3.30V', '~3%', 'Device shutting down'],
+ ]}
+ />
+
+ USB-powered nodes report 100% battery even if there's no battery installed. Battery alerts only matter for nodes actually running on battery power.
+
+
+ Node Offline Detection
+
+ MeshAI marks a node as "offline" when it hasn't been heard for a configurable time period. Different node types need different thresholds:
+
+ 2 hours, 'These should always be transmitting. 2 hours of silence means something is wrong.'],
+ ['Fixed client (wall power)', '2-4 hours', 'Same logic, slightly more lenient.'],
+ ['Mobile / vehicle', '4-8 hours', 'They go behind mountains, into garages, out of range. Normal.'],
+ ['Solar-powered', '12-24 hours', 'May shut down at night when solar stops charging.'],
+ ]}
+ />
+
+ Rule of thumb: set the threshold to about 4× the node's beacon interval. Too tight and nodes will constantly flap "offline/online" from normal gaps. Too loose and real outages go unnoticed.
+
+
+
+ {/* Notifications */}
+
+ How It Works
+
+ - Something happens — a fire is detected, weather warning issued, node goes offline, etc.
+ - MeshAI checks your rules — does this event match any of your notification rules? Is it severe enough? Are we in quiet hours?
+ - If a rule matches — MeshAI sends the notification through whatever delivery method that rule is configured for.
+
+
+ Building Rules
+ Each rule answers three questions:
+
+ - WHEN does it trigger? (which categories, what severity)
+ - WHERE does it send? (mesh broadcast, email, webhook, etc.)
+ - HOW OFTEN at most? (cooldown period)
+
+
+ Use "Add from Template" to start with a pre-built rule and customize it, or build from scratch with "Add Rule."
+
+
+ Severity Levels — What Should I Set?
+ Warning ✓, 'Take action (fire within 15km, severe weather, critical battery)', 'Low — recommended for most rules'],
+ ['Emergency', 'Life safety (extreme weather, fire at infrastructure, total blackout)', 'Very rare'],
+ ]}
+ />
+
+ "Warning" is the sweet spot for most rules. You get alerted when something actually needs your attention without being overwhelmed by every minor event.
+
+
+ Quiet Hours
+
+ When enabled, non-emergency notifications are held during sleeping hours (default 10pm-6am). Emergency alerts and rules marked "Override Quiet Hours" always get through.
+
+ You can turn quiet hours off entirely if you don't want them.
+
+ Webhook — The Swiss Army Knife
+
+ A webhook sends your alert as an HTTP POST to any URL. This one delivery method works with:
+
+
+ - Discord — use a Discord webhook URL
+ - Slack — use a Slack incoming webhook URL
+ - ntfy.sh — POST to https://ntfy.sh/your-topic
+ - Pushover — POST to the Pushover API
+ - Home Assistant — POST to an automation webhook URL
+ - Anything else that accepts HTTP POST
+
+
+ MeshAI doesn't need to know what's on the other end. Give it the URL and it works.
+
+
+
+ {/* Commands */}
+
+
+ All commands use the ! prefix (configurable). Send these as a direct message to MeshAI on your mesh.
+
+
+ Basic Commands
+ !help, 'Shows all available commands'],
+ [!ping, 'Tests if the bot is alive'],
+ [!status, 'Quick mesh summary (nodes online, health score)'],
+ [!health, 'Detailed health report with pillar scores'],
+ [!weather, 'Current weather for your area'],
+ ]}
+ />
+
+ Environmental Commands
+ !alerts, 'Active NWS weather alerts for your area'],
+ [<>!solar (or !hf), 'Current solar indices and RF conditions'],
+ [!fire, 'Active wildfires near your mesh'],
+ [!avy, 'Avalanche advisory (seasonal — shows "off season" in summer)'],
+ [<>!streams (or !gauges), 'Stream gauge readings'],
+ [<>!roads (or !traffic), 'Road conditions and traffic flow'],
+ [!hotspots, 'Satellite fire detections'],
+ ]}
+ />
+
+ Subscription Commands
+ !subscribe, 'Lists all alert categories you can subscribe to'],
+ [!subscribe fire_proximity, 'Subscribe to a specific category'],
+ [!subscribe all, 'Subscribe to everything'],
+ [!unsubscribe fire_proximity, 'Unsubscribe from a category'],
+ [!subscriptions, "Shows what you're currently subscribed to"],
+ ]}
+ />
+
+ Conversational
+
+ MeshAI isn't just commands — you can ask it questions in plain English. "How's the mesh doing?" "Is there any ducting?" "What's the fire situation?" "How's traffic on I-84?" It uses the live environmental data and mesh health data to answer.
+
+
+
+ {/* API Reference */}
+
+
+ MeshAI's REST API is available at http://your-host:8080. All endpoints return JSON.
+
+
+ System
+
+ - GET /api/status — version, uptime, node count
+ - GET /api/channels — radio channel list
+ - POST /api/restart — restart the bot
+
+
+ Mesh Data
+
+ - GET /api/health — health score and pillars
+ - GET /api/nodes — all nodes with positions and telemetry
+ - GET /api/edges — neighbor links with signal quality
+ - GET /api/regions — region summaries
+ - GET /api/sources — data source health
+
+
+ Configuration
+
+ - GET /api/config — full config
+ - GET /api/config/{'{section}'} — one section
+ - PUT /api/config/{'{section}'} — update a section
+
+
+ Environmental
+
+ - GET /api/env/status — per-feed health
+ - GET /api/env/active — all active events
+ - GET /api/env/swpc — solar/geomagnetic data
+ - GET /api/env/ducting — atmospheric profile
+ - GET /api/env/fires — wildfire perimeters
+ - GET /api/env/hotspots — satellite fire detections
+
+
+ Alerts
+
+ - GET /api/alerts/active — current alerts
+ - GET /api/alerts/history — past alerts
+ - GET /api/notifications/categories — available alert categories
+
+
+ Real-time
+
+ - ws://your-host:8080/ws/live — WebSocket for live updates
+
+
+
+