Help & Operations Guide

Complete documentation for operating and maintaining your EAS Station

Safety Reminder: This guide supports an experimental build of EAS Station. The platform is verified against reference projects such as multimon-ng, but it is not FCC-approved and must only be used in controlled lab environments. Never depend on it for live emergency alerting or public safety workflows.

Quick Navigation

Jump directly into the workflows you open most often.

7 shortcuts

Getting Started

Install, provision, and verify your stack.

Daily Operations

Monitor, validate, broadcast, and archive.

Troubleshooting

Playbooks for the failures we see most.

Reference Commands

Docker, Postgres, and analytics utilities.

Admin Panel

User, RBAC, and infrastructure controls.

System Health

Live service status and background workers.

Permission Tree

Compare every role and inherited scope.

Operations Flow

1

Monitor & Capture

CAP polling + SDR ingest keep alerts flowing in.
2

Analyze & Verify

Rule filters, analytics, and operator review.
3

Broadcast & Notify

Builder, audio playout, GPIO, and displays.
4

Audit & Improve

Archive, compliance, and analytics feedback.

Safety Expectations

Isolated Networks: Operate the stack in isolated development or staging networks disconnected from broadcast transmitter controls.
No Live Credentials: Do not ingest live IPAWS credentials, dispatch feeds, or mission-critical telemetry into this environment.
Validated Workflows: Validate any workflows on certified FCC equipment before using them in real-world alerting scenarios.
Legal Review: Review the repository Terms of Use and Privacy Policy with your operators prior to onboarding.

Getting Started

Prerequisites: Ensure you have Docker Engine 24+ with Docker Compose V2 and a dedicated PostgreSQL 15 + PostGIS database before starting.

Review Documentation
The About page covers system goals, core services, and the complete software stack.
Provision Infrastructure
Deploy Docker Engine 24+ with Docker Compose V2 and ensure a dedicated PostgreSQL 15 + PostGIS database container is available.
Configure Environment
Copy .env.example to .env, set secure secrets, and update database connection details.
Launch the Stack
Run docker compose up -d --build after .env points at your PostgreSQL/PostGIS deployment.

Routine Operations

Navigate to http://<host>:5000 in a modern browser.

Tip: Bookmark the dashboard for quick access during operations.

Open the Dashboard to view active CAP products on the interactive map.
Use the Statistics tab to analyze severity, event types, and historical counts.
Check System Health for CPU, memory, disk, receiver, and audio pipeline heartbeat metrics.

Interactive Map: Geographic visualization

Statistics: Historical analysis

Navigate to Alert Verification (/admin/alert-verification) to inspect delivery timelines and per-target outcomes.
Upload captured WAV or MP3 files to decode SAME bursts directly in the browser.
Store decoded results for future comparison from the sidebar list.

Note: The verification dashboard helps validate that generated alerts match expected EAS formats.

Importing Boundary Data

The system supports two methods for importing geographic boundary data:

GeoJSON Files: Upload GeoJSON files directly via the "Upload Files" tab
Shapefiles: Upload ESRI Shapefiles (ZIP archives with .shp, .shx, .dbf files) or import existing shapefiles from the server

Using Shapefiles

Navigate to Admin → Upload Files and scroll to the "Upload Shapefiles" section:

View Server Files: Click "Refresh List" to see shapefiles already on the server (e.g., in /streams and ponds)
Import Existing: Click "Import" next to any complete shapefile to convert and load it into the database
Upload New: Upload a ZIP file containing all shapefile components and select the boundary type

Tip: The system automatically detects water features (rivers, lakes) from TIGER/Line shapefiles. For Putnam County (FIPS 39137), water boundary files are pre-loaded in the streams and ponds directory.

Supported Boundary Types

🌊 Rivers & Streams - Linear water features
💧 Lakes & Ponds - Area water bodies
⚡ Electric Providers - Utility service areas
🏘️ Villages & Townships - Municipal boundaries
🏫 School Districts
🔥 Fire Districts
🚑 EMS Districts
🚆 Railroads - Rail corridors
📞 Telephone Providers
🗺️ County Outlines

Additional Configuration

Alert Configuration: Set up alert routing and notification preferences in the admin panel
Filter Settings: Configure geographic and event-based alert filtering
Intersection Calculation: After uploading boundaries, calculate intersections via Operations → Calculate Intersections

Toggle Auto Start or Enabled to control which receivers the radio manager spins up during poller runs.
Use the action menu to request synchronized IQ/PCM captures.
Captured files are surfaced alongside status updates in the compliance dashboard.

Create dynamic content templates for LED signs and VFD displays with API data integration.

Screen Templates: Define custom layouts with variable substitution from API endpoints like /api/system_status, /api/alerts, and /api/monitoring/radio
LED Displays: Configure text content (4 lines × 20 chars) with color, animation mode, and speed settings
VFD Graphics: Build graphical screens with progress bars, VU meters, text, shapes, and images on 140×32 pixel displays
Screen Rotation: Set up automatic cycling between multiple screens with configurable durations
Dynamic Data: Display system health, CPU/memory usage, alert counts, network info, signal strength, and more
Priority Management: Emergency screens override rotation; alerts pause normal displays

Access: Navigate to System → Custom Screens from the main menu or visit /screens

Documentation: See Custom Display Screens Guide for template syntax, variable reference, and examples

Broadcast Builder Console:

Accessible from the top navigation once logged in. Use the browser-based workflow to:

Pick a state or territory
Choose county/parish or statewide SAME codes
Select originator code (EAS, CIV, WXR, PEP)
Choose from authorized 47 CFR §11.31(d-e) event types
Preview the SAME header in real-time
Generate complete packages with SAME bursts, attention tones, and narration

Command Line: For automation, use: docker compose exec app python tools/generate_sample_audio.py

Required Weekly Test (RWT) broadcasts can be automatically scheduled to run on specific days and time windows.

Accessing Weekly Test Automation

Navigate to Broadcast → Weekly Test Automation from the navigation menu
Or visit /rwt-schedule directly

Configuration Options

Enable/Disable: Toggle automatic RWT broadcasts on or off
Days of Week: Select which days to send RWT (Monday through Sunday)
Time Window: Set start and end times (e.g., 8:00 AM to 4:00 PM)
Coverage: The scheduler always follows the shared Default RWT Counties list that sits next to the form—update it once and Quick RWT, manual defaults, and automation all stay aligned.

Originator & Station: RWT automation reuses the EAS_ORIGINATOR and EAS_STATION_ID environment variables that also feed the Broadcast Builder console.

RWT Broadcast Behavior

Automatic RWT broadcasts are designed to be lean and FCC-compliant:

No TTS Narration: RWT contains only SAME headers and EOM tones
No Attention Tones: Silent except for required signaling
Once Per Day: Only one RWT sent per configured day
Time Window: Broadcasts only during configured hours
Logged: All broadcasts stored in database for compliance tracking

Testing Your Configuration

Use the "Send Test RWT Now" button to immediately trigger a test broadcast and verify your configuration.

Scheduling Note: The system checks every minute whether to send an RWT. Once configured, it runs automatically in the background.

Default Counties: Systems ship with Allen, Defiance, Hancock, Henry, Paulding, Van Wert, and Wood Counties in Ohio (FIPS codes 039003, 039039, 039063, 039069, 039125, 039161, 039173). Update the Default RWT Counties manager to write your own list into Location Settings—Quick RWT, the Broadcast Builder defaults, and the scheduler will all use it automatically.

Troubleshooting

Check Logs: Run docker compose logs -f to see container startup messages.
Database Connection: Verify POSTGRES_* settings in .env match your database deployment.
Secret Key: Ensure SECRET_KEY is set to a non-empty value.
Port Conflicts: Confirm port 5000 isn't already in use.

Common Issue: Database connectivity problems account for 80% of startup failures.

PostGIS Extension: Ensure your database has the PostGIS extension enabled: CREATE EXTENSION IF NOT EXISTS postgis;
Spatial Indexes: Check that boundary tables have spatial indexes for performance.
Geometry Types: Verify imported GeoJSON files use valid geometry types.

Audio Drivers: Verify sound card drivers are working on the host system.
File Permissions: Check that the application has write access to audio output directories.
Azure Speech: If using Azure TTS, verify API keys and regional endpoints.

Serial Connection: Verify the serial port device exists and is accessible.
Protocol Settings: Check that baud rate and protocol settings match your sign model.
Network Access: Ensure the application can reach the sign's IP address if using network control.

Reference Commands

Docker Operations


                                    # View logs

                                    docker compose logs -f


                                    # Restart services

                                    docker compose restart


                                    # Update stack

                                    docker compose pull && docker compose up -d

Database Operations


                                    # Reset database

                                    docker compose exec app python tools/reset_database.py


                                    # Check health

                                    docker compose exec app python tools/check_db_health.py

Audio & Testing


                                    # Generate test audio

                                    docker compose exec app python tools/generate_sample_audio.py


                                    # Test receivers

                                    docker compose exec app python tools/test_receivers.py

System Status


                                    # System health

                                    curl http://localhost:5000/api/system_health


                                    # Version info

                                    curl http://localhost:5000/version

Getting Help

1
Check Documentation: Review this guide and the About page for system information.
2
Review Logs: Run docker compose logs -f to identify error messages.
3
Check System Health: Visit System Health for status overview.
4
Search Issues: Look for similar problems on GitHub Issues.
5
Create New Issue: Provide logs, configuration (redact secrets), and steps to reproduce.

External Resources:

Trusted Field Resources

Curated references from NOAA, FEMA IPAWS, and ARRL to keep operations sharp.

NOAA FEMA IPAWS ARRL

NOAA Weather Service

Primary CAP documentation, glossary, and sample payloads.

FEMA IPAWS Lab

Interoperability, architecture, and test schedule references.

ARRL Field Playbooks

ARES task books, ICS-213 templates, and readiness checklists.

Quick Actions

Admin Panel

System Health

Live Alerts

Statistics

Help & Operations Guide

Quick Navigation

Getting Started

Daily Operations

Troubleshooting

Reference Commands

Admin Panel

System Health

Permission Tree

Operations Flow

Monitor & Capture

Analyze & Verify

Broadcast & Notify

Audit & Improve

Safety Expectations

Getting Started

Routine Operations

Accessing the Dashboard

Monitoring Live Alerts

Reviewing Compliance & Weekly Tests

Managing Boundaries and Alerts

Importing Boundary Data

Using Shapefiles

Supported Boundary Types

Additional Configuration

Managing Receivers

Custom Display Screens

Generating Sample Audio

Scheduling Automatic RWT Broadcasts

Accessing Weekly Test Automation

Configuration Options

RWT Broadcast Behavior

Testing Your Configuration

Troubleshooting

Application Will Not Start

Spatial Queries Failing

Audio Generation Errors

LED Sign Not Responding

Reference Commands

Docker Operations

Database Operations

Audio & Testing

System Status

Getting Help

Trusted Field Resources

NOAA Weather Service

FEMA IPAWS Lab

ARRL Field Playbooks

Quick Actions