# Bayou Radar Skywarn

**Bayou Radar Skywarn is powered by Bayou Radar with the goal of making SKYWARN operations and keeping people informed a little easier.** It gives compatible Asterisk/app_rpt radio systems an automated way to monitor official weather alerts, announce changing threats, maintain active-alert tail messages, and support local severe-weather communications.

Bayou Radar is a nationwide live radar and weather-intelligence service built to make important weather information fast, clear, and easy to use. It brings live radar, government-issued weather alerts, storm tracking, tropical weather, forecasts, lightning information, and storm-awareness tools together in one powerful platform. Bayou Radar's mission is simple: **Weather Intelligence for Everyone.**

Bayou Radar Skywarn extends that mission to amateur-radio operators, repeater owners, weather volunteers, and community communication networks that help keep people informed before, during, and after hazardous weather.

![Bayou Radar](src/bayouradar_skywarn/web/logo.png)

## Bayou Radar first, NWS fallback

Version 0.2.0 makes Bayou Radar the operational source of truth:

1. Each configured area is queried through `https://backend.bayouradar.com`.
2. A valid Bayou Radar response is used even when it contains zero alerts.
3. If Bayou Radar times out, returns an HTTP error, supplies malformed data, or cannot query a configured area, only that area is retried through the direct NWS API.
4. If both sources fail, the service retains unexpired cached alerts for the affected area instead of announcing a false all-clear.
5. The dashboard and JSON status show the active source for every monitored area.

The Bayou Radar public API is location-based. Its point route uses latitude/longitude and its active-alert overlay route uses a bounding box. Each monitored area therefore combines:

- A county or forecast-zone UGC code for alert matching and NWS fallback.
- A Bayou Radar bounding box for county-wide coverage, or latitude/longitude for one exact repeater location.

Bounding boxes are preferred when the node is expected to announce alerts anywhere in a whole county or parish.

## What is working in 0.2.0

- Bayou Radar backend API as the primary alert source
- Automatic direct NWS fallback by individual monitored area
- Source validation that distinguishes a legitimate zero-alert response from a broken response
- Dashboard source health, per-area routing, fallback visibility, and Bayou Radar success time
- County or forecast-zone UGC matching
- CAP identifier and update-reference tracking
- New, updated, cleared, and all-clear announcements
- Multiple simultaneous alerts of the same event type
- Offline espeak/espeak-ng TTS and optional Piper TTS
- Asterisk/app_rpt `rpt localplay` output to multiple nodes
- Generated app_rpt tail messages
- Dynamic courtesy-tone and node-ID file switching
- Alert-triggered DTMF and explicitly configured shell actions
- Detailed alert descriptions by number, title, or identifier
- Pushover notifications
- Supermon `/tmp/AUTOSKY/warnings.txt` compatibility
- SQLite state, low-write operation, and alert history
- Full and partial source-outage protection using unexpired cached alerts
- systemd service with cron compatibility fallback
- Local Bayou Radar status dashboard
- Test-alert injection
- Optional prerecorded audio prefixes/suffixes and transmitter-keying delay

## Supported systems

The primary target is Python 3 on AllStarLink 3 and Debian 12 or newer. The implementation avoids unnecessary version-specific Python syntax and should also run on many older Python 3 environments when PyYAML is available. The installer supports Debian-family and pacman-family systems. Very old images may require manual dependency installation.

## Install

```bash
sudo ./install.sh
sudo nano /etc/bayouradar-skywarn/config.yaml
sudo /opt/bayouradar-skywarn/bin/br-skywarn config-check
sudo systemctl restart bayouradar-skywarn
sudo systemctl status bayouradar-skywarn
```

Set a real contact email or website in `nws.user_agent`, add the Bayou Radar location and NWS UGC code under `areas`, and enter the node numbers under `asterisk.nodes`.

### Monitored-area example

```yaml
areas:
  - code: LAC019
    name: Calcasieu Parish
    bbox:
      west: -93.765851
      south: 30.038041
      east: -92.887222
      north: 30.490523
```

Point mode is also supported:

```yaml
areas:
  - code: LAC019
    name: Calcasieu Parish repeater site
    latitude: 30.2293504
    longitude: -93.3579244
```

Point mode monitors alerts affecting that point. It should not be treated as full parish coverage.

For tail messages, add or update the node's `rpt.conf` entry:

```ini
tailmessagetime = 600000
tailsquashedtime = 30000
tailmessagelist = /run/bayouradar-skywarn/wx-tail
```

Then restart Asterisk.

## Commands

```bash
/opt/bayouradar-skywarn/bin/br-skywarn status
/opt/bayouradar-skywarn/bin/br-skywarn run-once
/opt/bayouradar-skywarn/bin/br-skywarn enabled toggle
/opt/bayouradar-skywarn/bin/br-skywarn describe 1
/opt/bayouradar-skywarn/bin/br-skywarn describe "Tornado Warning"
/opt/bayouradar-skywarn/bin/br-skywarn announce "This is a Bayou Radar Skywarn test."
/opt/bayouradar-skywarn/bin/br-skywarn tones weather
/opt/bayouradar-skywarn/bin/br-skywarn id normal
```

Commands can be mapped in `rpt.conf` for over-the-air control:

```ini
831 = cmd,/opt/bayouradar-skywarn/bin/br-skywarn enabled toggle
841 = cmd,/opt/bayouradar-skywarn/bin/br-skywarn describe 1
842 = cmd,/opt/bayouradar-skywarn/bin/br-skywarn describe 2
```

On systems where Asterisk runs as an unprivileged user, ensure that user can execute the command and write the configured runtime/audio targets. The installer runs the service as the `asterisk` user when that account exists.

## Dashboard

The local dashboard presents service health, active alerts, monitored areas, radio nodes, the current data route, per-area Bayou Radar/NWS status, fallback areas, and the last successful Bayou Radar poll. It listens on `127.0.0.1:8765` by default. Put it behind authenticated nginx access before exposing it beyond the node itself.

The same information is available as JSON at `/api/status`.

## Testing without transmitting

Copy the example config, set `asterisk.enabled: false`, set `testing.inject: true`, then run:

```bash
/opt/bayouradar-skywarn/bin/br-skywarn run-once
/opt/bayouradar-skywarn/bin/br-skywarn status
```

Generated audio and status files appear in `/run/bayouradar-skywarn`.

## Audio customization

The service creates 8 kHz mono µ-law audio directly with `ffmpeg`; it does not depend on `pydub` or Python's removed `audioop` module. `audio.delay_ms` can add key-up silence before playback. Existing WAV, ULAW/MULAW, SLN, and SLN16 files can be placed before or after generated speech with the announcement and tail-message prefix/suffix settings.

## Safety and data notes

- A valid empty Bayou Radar alert collection means no active alerts; it is not treated as an outage.
- The NWS API is a resilience source, not the normal primary route.
- The configuration validator enforces a minimum 30-second polling interval.
- CAP alert data must not be used to activate an EAS encoder or decoder. Bayou Radar Skywarn is for informational radio-node announcements and administrator-defined node behavior, not EAS origination.
- County UGC codes are recommended because they support county-based products and matching during direct NWS fallback.
- Shell actions run only when explicitly configured by the system administrator.
- SKYWARN® is a registered trademark of NOAA's National Weather Service. Bayou Radar Skywarn is an independent Bayou Radar product and is not affiliated with or endorsed by NOAA or the National Weather Service.

## License

GPL-3.0. See `LICENSE` and `NOTICE.md`.