Configuration reference

One YAML file, read from /config/wxalerts.yml (override with the WXALERTS_CONFIG environment variable or -c). It is validated in full at startup rather than lazily, because the first use of a broken rule is a tornado warning at three in the morning.

There is no database and no admin UI. The configuration is a list of counties and a severity threshold that changes about twice a year; what you actually want to watch day to day, meaning what went out and what it cost in airtime, is MeshMonitor’s own message log.

The whole file

mqtt:
  url: wss://mqtt.wxalerts.org/mqtt
  username: wxalerts
  password: wxalerts          # public on purpose; the broker denies publish

meshmonitor:
  url: http://meshmonitor:8080
  token: ${MESHMONITOR_TOKEN}
  source_id: default          # optional; for a multi-source MeshMonitor

timezone: America/Chicago

counties:
  - same: "012113"
    label: Santa Rosa         # what appears in the message

offices: [KMOB]               # optional; marine zones have no county

delivery:
  max_bytes: 200
  warmup_seconds: 20
  max_per_hour: 12
  burst: 4
  queue_max_age: 15m
  send_all_clear: true
  office_alerts: unzoned
  dry_run: false

rules:
  - name: life-threatening
    phenomena: [TO, FF, SQ, HU]
    significance: [W]
    channel: WX
    priority: 100
    template: "{emoji}{event} {counties} til {ends} {instruction}"

${VAR} and ${VAR:-default} are expanded from the environment anywhere in the file, so the token never has to live on disk. A ${VAR} with no default and no environment variable set is a config error, not an empty string.

Durations (warmup_seconds, queue_max_age, min_interval) accept a bare number of seconds or a suffixed string: 90, "90s", "15m", "2h".

Top level

mqtt

Defaults point at the public WxAlerts feed and are usually left alone. The credential is published deliberately, because the broker enforces that this account cannot publish, so the read-only feed needs no signup.

meshmonitor

counties and offices

counties is the main subscription. Each entry is a six-digit SAME code and a label:

counties:
  - same: "012113"
    label: Santa Rosa

Quote the code. YAML eats the leading zero on an unquoted 012113. The loader re-pads it rather than rejecting it, because the mistake is near universal, but quoting says what you meant. The label is what appears in the message; if you omit it, the raw code does, which helps nobody. Run init --lat <lat> --lon <lon> to look a code up.

offices subscribes to a WFO’s whole output. The reason to do it is marine and offshore zones: those carry no SAME code at all, so they never appear on the county tree and the forecast office is the only way to receive them. See delivery.office_alerts for what gets kept.

delivery

Rules

Rules are evaluated top to bottom and the first match wins, so they read like a firewall: specific rules above general ones. An alert matching no rule is never sent. The config is an allowlist, which means a new phenomenon code appearing upstream cannot start transmitting on its own.

Every axis you name must match; an axis you omit matches anything. Codes are upper-cased, so to and TO are the same.

Naming the channel

Prefer the name over the slot number. The slot depends on the order channels happened to be added to the device, and a wrong number transmits on the wrong channel instead of failing, which is the worst available outcome. A name is resolved at startup and a name MeshMonitor does not have stops the bridge with a list of the ones it does.

Names are matched ignoring case and a leading hash, because the same channel is written three ways in practice: WX in a config, #wx on a MeshCore device, and wx in someone’s head. WX and WEATHER, however, are two different channels.

min_interval versus escalation

These do different jobs and both are needed. Escalation suppression asks “is this the same thing I already said” and is always on; min_interval asks “am I talking too much about this category” and is off unless you set it. A tornado warning that upgrades from a watch is news and should not be blocked by a category interval, so warning rules normally run with no interval at all, and advisory rules run with a long one.

Templates

The default:

{emoji}{event} {counties} til {ends} {instruction}

A field the alert does not carry renders as empty and the surrounding whitespace collapses, so a template can name fields that only some alerts have.

Times are deliberately terse: 3:45p, not 3:45 PM CDT. The zone is the reader’s own and at 200 bytes the colon and the suffix are a word of instruction.

How a message shrinks

An NWS warning is several kilobytes; a Meshtastic text packet holds 237 bytes. Rather than chopping the rendered string, which leaves a fragment ending mid-word, the message is re-rendered at successively cheaper tiers until it fits:

Only if tier 2 still overflows, from a long literal in the template or a dozen county names, does it fall back to a hard trim on a word boundary, with an ellipsis so the truncation is visible.

The order is the reverse of how the product is written, on purpose. The instruction is the only part that changes what a reader does, so it is dropped last. What survives at the bottom is hazard, place and time, which is what a weather radio tone alone conveys.

Budgets are counted in bytes, not characters, because every emoji is four of them and most degree and quote characters are two or three.

What {counties} resolves to

In order of preference:

1. The labels you gave your own counties. A warning routinely spans counties you do not care about and the payload lists all of them, so the set is intersected with yours first. More than two collapse to Santa Rosa, Baldwin +3.
2. The NWS name of the alert’s UGC zones, fetched once from api.weather.gov and cached for the life of the process. This is what marine and offshore alerts get, since they can never reach step 1.
3. The issuing office, only as a last resort. It answers “who wrote this”, which is the least useful thing that could occupy the place slot.

Zone names are written for a forecast product, so they shed their qualifiers as the budget tightens, so “Pensacola Bay Area including Santa Rosa Sound” becomes “Pensacola Bay Area” before the instruction is touched:

⛵ MARINE WARN Pensacola Bay Area, Pensacola FL to Pascagoula MS til 9:15p Move to safe harbor immediately.

All-clears

The all-clear template is fixed:

{emoji}ALL CLEAR: {event} {counties} ended

It goes out at ten below the rule’s own priority, worth sending but never worth displacing a live hazard from a constrained queue, and only for hazards this bridge actually announced. Telling a mesh that a warning it never heard about is over is pure noise, and on a busy evening it would roughly double the traffic.

Emoji and abbreviations

Both tables are built in and merged with anything you add:

emoji:
  TO: "🌪"
  FW: "🔥"

abbreviations:
  Severe Thunderstorm: SVR TSTM
  Excessive Heat: EXT HEAT

Abbreviations are applied longest-match-first, so Severe Thunderstorm wins over Thunderstorm. They are only used from tier 1 down, because a message that fits keeps the full event name.