A professional Emergency Alert System (EAS) platform for monitoring, broadcasting, and verifying NOAA and IPAWS alerts
EAS Station is a software-defined drop-in replacement for commercial EAS encoder/decoder hardware, built on commodity hardware like Raspberry Pi. It provides comprehensive alert processing with FCC-compliant SAME encoding, multi-source aggregation, PostGIS spatial intelligence, SDR verification, and integrated LED signage.
!!! warning "IMPORTANT: Laboratory Use Only" EAS Station is experimental software for research and development. It is not FCC-certified and must only be used in controlled test environments. Never use for production emergency alerting.
| Feature | Description |
|---|---|
| π Multi-Source Ingestion | NOAA Weather, IPAWS federal alerts, and custom CAP feeds |
| π» FCC-Compliant SAME | Specific Area Message Encoding per FCC Part 11 |
| πΊοΈ Geographic Intelligence | PostGIS spatial filtering with county/state/polygon support |
| π‘ SDR Verification | Automated broadcast verification with RTL-SDR/Airspy |
| π Built-in HTTPS | Automatic SSL/TLS with Let's Encrypt, nginx reverse proxy |
| π¨ Modern Web UI | Responsive Bootstrap 5 interface with real-time updates |
| β‘ Hardware Integration | GPIO relay control, LED signs, multiple audio outputs |
Separated Systemd Service Design - Modern, reliable, production-grade architecture:
graph TB
subgraph External["External Sources"]
NOAA[NOAA Weather<br/>CAP Feeds]
IPAWS[FEMA IPAWS<br/>CAP Feeds]
RF[RF Signals<br/>162 MHz]
end
subgraph Services["Systemd Services"]
POLL[eas-station-poller<br/>Alert Polling]
WEB[eas-station-web<br/>Flask + Gunicorn]
SDR[eas-station-sdr<br/>SDR Hardware]
AUDIO[eas-station-audio<br/>EAS Monitoring]
HW[eas-station-hardware<br/>GPIO/Displays]
end
subgraph Infrastructure["Infrastructure"]
DB[(PostgreSQL 17<br/>+ PostGIS 3.4)]
REDIS[(Redis 7<br/>Cache + IPC)]
NGINX[nginx<br/>HTTPS Proxy]
end
subgraph Output["Outputs"]
TX[FM Transmitter]
UI[Web Browser]
LED[LED Signs]
end
NOAA --> POLL
IPAWS --> POLL
RF --> SDR
POLL --> DB
WEB --> DB
WEB --> REDIS
SDR --> REDIS
AUDIO --> REDIS
NGINX --> WEB
WEB --> UI
HW --> TX
HW --> LED
style External fill:#3b82f6,color:#fff
style DB fill:#8b5cf6,color:#fff
style WEB fill:#10b981,color:#fff
style AUDIO fill:#f59e0b,color:#000
style UI fill:#6366f1,color:#fff
Benefits:
- β Reliable - Services isolated (web crashes don't affect audio/SDR)
- β Simple - No container orchestration, standard systemd
- β Fast - Direct hardware access, dedicated resources per service
- β Debuggable - Separate logs via journalctl, independent restart
eas-station/
βββ app.py # Main Flask application
βββ *_service.py # Service entry points (EAS, SDR, hardware, audio)
βββ wsgi.py # WSGI server entry point
βββ app_core/ # Core business logic
β βββ audio/ # Audio processing and EAS monitoring
β βββ radio/ # SDR radio management
β βββ auth/ # Authentication and RBAC
β βββ models.py # Database models
βββ app_utils/ # Utility modules
β βββ eas.py # SAME encoding/generation
β βββ eas_decode.py # SAME decoding
β βββ eas_tts.py # Text-to-speech synthesis
βββ webapp/ # Web application routes and templates
β βββ admin/ # Admin routes and API
β βββ templates/ # Jinja2 HTML templates
βββ poller/ # CAP feed polling service
βββ static/ # Frontend assets (CSS, JS, images)
βββ scripts/ # Utility and maintenance scripts
β βββ debug/ # Debug and testing scripts
β βββ fixes/ # One-time fix scripts
β βββ diagnostics/ # Diagnostic tools
β βββ maintenance/ # Database and system maintenance
βββ tests/ # Comprehensive test suite (80+ files)
βββ docs/ # Documentation
β βββ guides/ # Setup and user guides
β βββ architecture/ # Architecture documentation
β βββ FUTURE_ENHANCEMENTS.md # Planned enhancements
βββ legacy/ # Archived code for reference
**Key Files:**
- `app.py` - Main web application and Flask initialization
- `eas_service.py` - EAS monitoring service (subscribes to Redis audio)
- `sdr_hardware_service.py` - SDR hardware USB access (publishes IQ samples)
- `hardware_service.py` - GPIO, displays, and Zigbee hardware
- `eas_monitoring_service.py` - Audio processing and EAS monitoring
git clone https://github.com/KR8MER/eas-station.git && \
cd eas-station && \
sudo bash install.shThe installer uses an interactive TUI (raspi-config style) to collect all configuration:
- π€ Administrator account (username, password, email)
- π₯οΈ System settings (hostname, domain, EAS originator, station callsign)
- π Location & timezone (state, county, optional FIPS codes)
- π‘ Alert sources (NOAA, IPAWS with poll intervals)
- π΅ Audio/streaming (Icecast with auto-generated passwords)
- π Hardware (GPIO, LED signs, VFD displays)
Then automatically:
- β Installs all dependencies (PostgreSQL, Redis, Python, nginx, etc.)
- β Generates secure SECRET_KEY and passwords
- β Creates configuration file with your settings
- β Initializes the database schema
- β Starts all services
- β Configures HTTPS with self-signed certificate
All configuration is done during installation - no post-install wizard needed!
π‘ Debian Trixie (Testing): Fully supported! The installer auto-detects your OS version and installs compatible packages. Python 3.13 is fully supported with the latest dependency updates.
To completely remove EAS Station from your system:
cd eas-station
sudo bash uninstall.shThe uninstall script will:
- β Stop and remove all EAS Station services
- β Remove application files and logs
- β Optionally remove PostgreSQL database
- β Optionally remove dependencies (PostgreSQL, Redis, Nginx, etc.)
Open your web browser and navigate to:
- https://localhost (on the server)
- https://your-server-ip (from network)
Accept the self-signed certificate warning (safe for initial setup).
Log in with the administrator account you created during installation - your station is ready!
All essential settings are configured during installation, but you can:
-
Advanced Features - Use the web-based setup wizard at
/setupfor:- FIPS code lookup from county names
- Auto-derive zone codes from FIPS codes
- Interactive builders with validation
-
Reconfigure Anytime - Use
sudo eas-configfor raspi-config style TUI -
Manual Editing - Edit
/opt/eas-station/.envfor advanced settings
π‘ Production SSL:
sudo certbot --nginx -d your-domain.com
- OS: Debian 12 (Bookworm), Debian 13 (Trixie), Ubuntu 22.04+, or Raspberry Pi OS
- CPU: 2+ cores (4+ recommended)
- RAM: 2GB minimum (4GB+ recommended)
- Storage: 20GB minimum (50GB+ recommended for alerts database)
- Network: Internet connection for alert polling
- β Native Performance - Runs directly on host OS
- β Direct Hardware Access - SDR, GPIO, and audio devices work natively
- β Standard Linux Management - Familiar systemd service control
- β Interactive Setup - raspi-config style TUI for easy configuration
- β All-in-One Install - Complete configuration during installation
- β
Reconfigurable - Change settings anytime with
sudo eas-config
Build a pre-configured bootable ISO for dedicated hardware:
cd eas-station
sudo bash scripts/build-iso.sh
# Burn to USB: sudo dd if=eas-station-*.iso of=/dev/sdX bs=4M status=progressπ Full Guide: See docs/installation/README.md for detailed installation, upgrades, configuration, and troubleshooting.
Debian 13 (Trixie) is the current testing distribution and is fully supported:
- Python 3.13: All dependencies updated to support Python 3.13 (gevent 25.9.1+, pytest 9.0+, etc.)
- PostgreSQL: Works with PostgreSQL 15, 16, or 17 with PostGIS 3.3 or 3.4
- Package availability: All required packages are available in Trixie repositories
- Testing status: While Trixie is "testing", it's stable enough for development and lab use
If you encounter any package availability issues on Trixie, the installer will attempt to install from Debian Backports or skip optional packages gracefully.
graph TD
START{What do you<br/>want to do?}
START -->|Install & Setup| SETUP[π Quick Start Guide<br/>Installation]
START -->|Configure Hardware| HW[π‘ SDR Setup<br/>π§ Audio Sources<br/>π GPIO/Displays]
START -->|Daily Operations| OPS[π User Guide<br/>π οΈ Admin Interface<br/>π Monitoring]
START -->|Development| DEV[π» Developer Guide<br/>ποΈ Architecture<br/>π¨ Frontend Docs]
START -->|Troubleshooting| TROUBLE[π§ SDR Issues<br/>π Network/504<br/>ποΈ Database]
SETUP --> DOCS[π Full Documentation<br/>92 Documents]
HW --> DOCS
OPS --> DOCS
DEV --> DOCS
TROUBLE --> DOCS
style START fill:#3b82f6,color:#fff
style DOCS fill:#10b981,color:#fff
style TROUBLE fill:#f59e0b,color:#000
| For... | Start Here |
|---|---|
| First Time Setup | Setup Instructions β Quick Start |
| Radio Configuration | SDR Setup Guide |
| Daily Operations | User Guide |
| Deployment | Installation Guide |
| Development | Developer Guide |
| Remote Development (VSCode) | VSCode Setup Guide - 5-minute setup! |
| Debugging on Pi | PyCharm Remote Debugging Guide |
π Complete Documentation Index - Searchable topics and detailed guides
EAS Station exposes a comprehensive REST API for automation and integrations:
- Endpoint reference β Complete request/response catalog and authentication model
- Architecture overview β How the API interacts with pollers, database, and broadcast services
- JavaScript API Guide β Using the JavaScript client to control GPIO and audio devices
Tip: All API routes are namespaced under
/api/. Use theX-API-Keyheader generated from the Configuration β API Keys page.
graph TB
subgraph External["External Sources"]
SRC[Alert Sources<br/>NOAA, IPAWS]
RF[RF Signals<br/>SDR Receivers]
end
subgraph Services["Systemd Services"]
POLL[Alert Poller<br/>Unified CAP Polling]
WEB[Web Application<br/>Flask + FastAPI]
SDR_SVC[SDR Service<br/>Radio Hardware]
AUDIO_SVC[Audio Service<br/>EAS Monitoring]
HW_SVC[Hardware Service<br/>GPIO/Displays]
end
subgraph Infrastructure["Infrastructure"]
DB[(PostgreSQL 17<br/>+ PostGIS 3.4)]
REDIS[(Redis 7<br/>Cache + Pub/Sub)]
NGINX[nginx<br/>HTTPS + Proxy]
end
subgraph Output["Outputs"]
TX[FM Transmitter<br/>GPIO Control]
UI[Web Browser<br/>HTTPS]
LED[LED Signs<br/>RS-232]
STREAM[Audio Streams<br/>Icecast]
end
SRC -->|CAP XML| POLL
RF --> SDR_SVC
POLL -->|Store Alerts| DB
WEB -->|Query Data| DB
WEB -->|Commands| REDIS
SDR_SVC -->|Metrics| REDIS
AUDIO_SVC -->|Decode| REDIS
NGINX -->|Reverse Proxy| WEB
WEB --> UI
HW_SVC -->|Relay Control| TX
HW_SVC -->|Messages| LED
SDR_SVC -->|Demod Audio| STREAM
style External fill:#3b82f6,color:#fff
style DB fill:#8b5cf6,color:#fff
style WEB fill:#10b981,color:#fff
style AUDIO_SVC fill:#f59e0b,color:#000
style UI fill:#6366f1,color:#fff
| Component | Technology | Purpose |
|---|---|---|
| Web Application | Flask 3.1 + FastAPI 0.124 + Bootstrap 5 | User interface and REST API |
| Alert Poller | Python asyncio | Unified NOAA/IPAWS CAP monitoring |
| Database | PostgreSQL 17 + PostGIS 3.4 | Spatial data storage and queries |
| SDR Service | SoapySDR + RTL-SDR/Airspy | Radio reception and demodulation |
| Audio Service | Python + ALSA | EAS decoding and monitoring |
| Hardware Service | RPi.GPIO + lgpio | GPIO relay, OLED, VFD, LED control |
| Web Server | Gunicorn 23.0 + nginx | WSGI server + HTTPS termination |
| Cache & IPC | Redis 7 | Real-time metrics and pub/sub messaging |
|
Broadcasters
Amateur Radio
|
Alert Distribution
Developers
|
| Component | Specification |
|---|---|
| Compute | Raspberry Pi 5 (8GB) or equivalent x86 |
| Control | Multi-relay GPIO HAT |
| Audio | USB sound card or Pi HAT |
| SDR | RTL-SDR v3 or Airspy |
| Storage | External SSD (50GB+) |
Operating System:
- Debian 12 (Bookworm) or Debian 13 (Trixie)
- Ubuntu 22.04 LTS or newer
- Raspberry Pi OS (based on Debian Bookworm/Trixie)
- Python 3.11, 3.12, or 3.13
- PostgreSQL 14+ with PostGIS 3+
- Redis 7+
Core System Packages (all Debian/Ubuntu versions including Trixie):
# Build tools and Python development
python3 python3-pip python3-venv python3-dev
build-essential gcc g++ make
# Database and spatial extensions
postgresql postgresql-contrib postgis
postgresql-17-postgis-3 # or postgresql-16-postgis-3 on older systems
# Networking and web services
redis-server nginx certbot python3-certbot-nginx
# Audio processing
ffmpeg espeak libespeak-ng1
# Development libraries
libpq-dev libev-dev libevent-dev libffi-dev libssl-dev
# USB and hardware support
libusb-1.0-0 libusb-1.0-0-dev usbutils ca-certificates
# Version control and utilities
git curl wgetOptional Packages (for SDR and hardware features):
# SDR receiver support (RTL-SDR, Airspy)
python3-soapysdr soapysdr-tools
soapysdr-module-rtlsdr soapysdr-module-airspy
libairspy0 librtlsdr0
# Raspberry Pi GPIO support (Pi only)
python3-lgpio # Preferred on Pi 5Python Package Requirements (installed via pip in virtual environment):
- Flask 3.1.2 - Web framework
- FastAPI 0.124.2 - Async API framework
- SQLAlchemy 2.0.45 - Database ORM
- gevent 25.9.1+ - WSGI async support (Python 3.13 compatible)
- redis 7.1.0 - Redis client
- psutil 7.1.3 - System monitoring
- numpy 2.3.5 - Numerical processing for SDR
- Pillow 12.0.0 - Image processing for displays
- pytest 9.0.2 - Testing framework
π Complete dependency list: See requirements.txt for all 50+ Python packages
π Automated Installation: The installation script (
install.sh) installs all required and optional dependencies automatically.π Manual Installation: See Setup Instructions for step-by-step installation guide.
Edit .env with your settings:
# Core settings
SECRET_KEY=generate-with-python-secrets-module
POSTGRES_HOST=localhost
POSTGRES_PASSWORD=your-secure-password
# Your location
DEFAULT_COUNTY_NAME=Your County
DEFAULT_STATE_CODE=XX
DEFAULT_ZONE_CODES=XXZ001,XXC001
# Enable broadcast (optional)
EAS_BROADCAST_ENABLED=false
EAS_ORIGINATOR=WXR
EAS_STATION_ID=YOURCALLConfiguration file location: /opt/eas-station/.env
After editing, restart services:
sudo systemctl restart eas-station.targetSee Configuration Guide for complete reference.
Professional flowcharts and block diagrams illustrating system architecture and workflows:
π View all architectural diagrams β
|
Main Dashboard |
Administration Panel |
We welcome contributions! Please see:
# Clone repository
git clone https://github.com/KR8MER/eas-station.git
cd eas-station
# Set up environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Configure database
cp .env.example .env
# Edit .env with local database settings
# Run development server
python app.py- π Documentation: Complete Docs
- π§ Diagnostic Tools: Troubleshooting Scripts
- π¬ Discussions: GitHub Discussions
- π Issues: GitHub Issues
- π‘ Community: Join our amateur radio forums
Quick Diagnostics:
- SDR not working? Run
bash scripts/collect_sdr_diagnostics.shor see SDR Quick Fix Guide- Connection issues? Run
bash scripts/diagnostics/troubleshoot_connection.sh- See all tools: scripts/diagnostics/README.md
Alert Self-Test: Open Tools β Alert Verification and use the built-in Alert Self-Test panel to replay bundled RWT captures and confirm your configured FIPS codes still trigger activations.
!!! danger "FCC Compliance Warning" EAS Station generates valid EAS SAME headers and attention tones. Unauthorized broadcast violates FCC regulations and can result in substantial fines:
- 2015 iHeartMedia: [$1M settlement](https://docs.fcc.gov/public/attachments/DA-15-199A1.pdf)
- 2014 Multiple Networks: [$1.9M settlement](https://docs.fcc.gov/public/attachments/DA-14-1097A1.pdf)
Always work in shielded test environments. Never connect to production broadcast chains.
See Terms of Use and FCC Compliance for details.
Current development focuses on:
- β Core Features: Multi-source ingestion, SAME encoding, geographic filtering
- β System Diagnostics: Web-based validation and health checking tool
- β Stream Profiles: Multi-bitrate Icecast streaming configuration
- π Hardware Parity: Advanced relay control, multi-receiver coordination
- β³ Certification: FCC Part 11 compliance documentation
- β³ Advanced Features: Cloud sync, mobile app, multi-site coordination
See Feature Roadmap for complete details.
- Stream Profile Manager (
/settings/stream-profiles) - Configure multiple Icecast streams with different bitrates and formats - Quick Start Guide - 15-minute deployment guide with common scenarios and troubleshooting
See Changelog for detailed documentation of recent changes.
EAS Station is available under dual licensing:
For open-source projects and non-commercial use, EAS Station is licensed under the GNU Affero General Public License v3 (AGPL-3.0).
Key requirements:
- β Free to use, modify, and distribute
- β Must keep source code open
- β Must share modifications if you deploy as a web service
- β Must retain copyright and attribution notices
- β Cannot remove author attribution or rebrand
See LICENSE file for full AGPL terms.
For proprietary/closed-source use without AGPL obligations, a Commercial License is available.
Benefits:
- β No source code disclosure requirements
- β Integration into proprietary systems
- β Priority support and updates
- β Custom development assistance
Contact for commercial licensing: See LICENSE-COMMERCIAL for details.
Copyright (c) 2025 Timothy Kramer (KR8MER)
EAS Station - https://github.com/KR8MER/eas-station
IMPORTANT: All derivative works must retain attribution to the original author. Rebranding or removing attribution is prohibited under both licenses. See NOTICE file for complete terms.
- For hobbyists & open-source: Free to use under AGPL
- For commercial use: Option to license without copyleft obligations
- For everyone: Protects the author's rights and prevents unauthorized rebranding
- NOAA/NWS - Weather alert data and CAP specifications
- FEMA/IPAWS - National alert system integration
- PostGIS Team - Spatial database technology
- Putnam County GIS Office - Geographic boundary data (Greg Luersman, GIS Coordinator)
- U.S. Census Bureau - FIPS codes and TIGER/Line boundary data
- Flask Community - Web framework
- RTL-SDR Project - Software-defined radio tools
- Amateur Radio Community - Testing and feedback
| Resource | Link |
|---|---|
| Documentation | docs/ |
| NOAA CAP API | https://www.weather.gov/documentation/services-web-api |
| IPAWS | https://www.fema.gov/emergency-managers/practitioners/integrated-public-alert-warning-system |
| FCC Part 11 | https://www.ecfr.gov/current/title-47/chapter-I/subchapter-A/part-11 |
| PostGIS | https://postgis.net/documentation/ |
Click to expand complete technology stack
- Flask 3.1.2 - Primary web framework for UI and REST API
- FastAPI 0.124.2 - Modern async API framework (parallel deployment)
- Gunicorn 23.0 - Production WSGI server
- Uvicorn 0.38.0 - ASGI server with WebSocket support
- nginx - HTTPS termination and reverse proxy
- PostgreSQL 17 - Primary relational database
- PostGIS 3.4 - Geographic/spatial data extension
- SQLAlchemy 2.0.45 - Python ORM and database toolkit
- GeoAlchemy2 0.18.1 - PostGIS integration for SQLAlchemy
- Alembic 1.17.2 - Database migration management
- Redis 7.1 - Cache, pub/sub messaging, and IPC
- Bootstrap 5.3.0 - Responsive UI framework
- Leaflet 1.9.4 - Interactive mapping library
- Chart.js - Data visualization and metrics
- Socket.IO - Real-time bidirectional communication
- Jinja2 3.1.6 - Template rendering engine
- SoapySDR - Software-defined radio abstraction layer
- RTL-SDR / Airspy - Radio receiver hardware support
- ALSA - Advanced Linux Sound Architecture
- Icecast - Audio streaming server
- numpy - Audio signal processing
- scipy - Digital signal processing
- RPi.GPIO / lgpio - Raspberry Pi GPIO control
- pyserial - Serial port communication (LED signs, VFD)
- smbus2 - I2C bus interface (OLED displays)
- lxml - Fast XML parsing for CAP feeds
- requests 2.32.5 - Synchronous HTTP client
- httpx 0.28.1 - Async HTTP client with connection pooling
- certifi 2025.11.12 - Updated CA bundle for SSL/TLS
- pytz 2025.2 - Timezone handling
- psutil 7.1.3 - System resource monitoring
- python-dotenv 1.2.1 - Environment variable management
- Systemd - Service orchestration and management
- journalctl - Centralized logging
- pytest - Testing framework
- black - Code formatting
- flake8 - Linting
- mypy - Static type checking
- Python 3.11 / 3.12 / 3.13 - Tested on all three versions
- Debian 12 (Bookworm) - Primary target OS
- Debian 13 (Trixie) - Fully supported
- Ubuntu 22.04+ - Compatible
- Raspberry Pi OS - Optimized support
73 de KR8MER π‘