Help & Operations Guide
Complete documentation for operating and maintaining your EAS Station™
Quick Navigation
Jump directly into the workflows you open most often.
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
-
Review DocumentationThe About page covers system goals, core services, and the complete software stack. The Attribution & Credits page lists every open-source dependency, data source, and licensing detail.
-
Run Installation ScriptRun
cd bare-metal && sudo bash scripts/install.shto install all dependencies and set up systemd services. -
Configure EnvironmentEdit
/opt/eas-station/.env, set secure secrets, and update database connection details. -
Start ServicesRun
sudo systemctl start eas-station.targetto launch all EAS Station™ services.
Routine Operations
Navigate to http://<host>:5000 in a modern browser.
Log in with administrator credentials created during initial setup.
EAS Station™ lets each operator pick how positional and motion values are
displayed across the UI. Selections are saved in your browser's
localStorage (per-device, per-browser) and apply
immediately wherever the affected values appear.
Configurable units
- Coordinates:
D.dddd(decimal degrees, e.g.41.450123°) orDMS(degrees / minutes / seconds, e.g.41°27'00.4"N). - Altitude: meters (
m) or feet (ft). - Speed: knots (
kn), miles per hour (mph), kilometers per hour (km/h) or meters per second (m/s). - Distance: meters (
m), feet (ft), miles (mi) or nautical miles (nmi).
Where to change them
- Your username menu (top-right) → Display Units opens the global picker from any page. Unit choices are personal to your browser, which is why they live in your account menu rather than under Settings.
- Each affected page also has an inline Units button:
- GPS & Time Dashboard — header, right-hand side.
- System Health — page header, top-right.
D.dddd, m, kn, m).
- 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.
Every map follows the theme you pick from the palette icon in the navigation bar. The basemap is deliberately toned down and the alert area is drawn with a glow and a white outline, so the warning is the only thing competing for your attention — the same treatment used on the shareable alert images. Switching themes restyles an open map instantly; no reload needed.
When enabled, lower-priority alerts (watches, advisories, routine updates) are held for a configurable timer before broadcasting instead of airing immediately, giving an operator a window to review them first.
- Immediate urgency or Extreme severity alerts always bypass the gate and broadcast right away, exactly as they do today — gating never delays a Tornado Warning or similarly urgent product.
- Held alerts appear on Broadcast → Pending Alerts with a live countdown.
- Approve broadcasts a pending alert immediately, skipping the rest of the wait.
- Cancel permanently blocks a pending alert — it will never air, even after its timer expires.
- If nobody acts, the alert auto-releases and broadcasts normally once the hold-off timer reaches zero.
- A non-empty queue also shows on the hardware: the USB tower/stack light (and the navbar's stack-light widget) shows a distinct color — blue by default, configurable under Admin → Hardware Settings — and a "Pending Review" scene rotates onto any connected OLED, LED sign, or VFD display, so an operator away from the browser still sees that something needs review.
Configure whether gating is enabled and the hold-off duration under Settings → Alert Gating. Disabled by default — turning it off restores today's immediate-broadcast behavior for every alert.
- 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.
Every audit log entry — logins, configuration changes, alerts received, EAS broadcasts, manual activations — is hash-chained to the entry before it and signed with the station's Ed25519 key. Any edit, deletion, or insertion (even directly against the database) is cryptographically detectable.
- Navigate to System Logs → Audit tab (
/logs?type=audit). - To see who changed a setting: use the Reports → Logs → Configuration Changes menu shortcut, or pick Configuration Changes in the Audit Action dropdown on the Audit tab. This shows every
config.updatedevent with the user, timestamp, IP address, and which fields changed. The filter is preserved in CSV/PDF exports. - In the Chain Integrity card, choose a scope (entire chain, or the newest N rows on very large logs) and click Verify Chain Integrity.
- A green result proves the log has not been modified; a red result reports the first bad row and why it failed.
- Expand any entry's details to see its
entry_hash,prev_hash, andsignature. - Each verification run is itself recorded in the chain as
audit.chain.verified— your receipt that the check happened.
/opt/eas-station/secrets/audit_signing.key; the path is configurable under Settings → Configuration → Environment Variables.
Reports → Analytics → Repository Statistics (/repo-stats) reports what is actually installed on this appliance — code size, registered routes and component counts — measured from the running checkout each time you load it. It reads like the System Health and GNSS dashboards: live status pills in the page header, a strip of at-a-glance readouts, then detail cards below.
- At-a-glance readouts — lines of code, source files, routes, comments, templates, test modules and the vendored share, in the same tile strip the other dashboards use.
- Language breakdown — every language with its brand logo, file and line counts, and its share of the codebase.
- What gets counted — every tracked file lands in exactly one bucket: first-party, documentation, or vendored third-party libraries (Bootstrap, Chart.js and friends under
static/vendor/). Vendored code is reported separately so it never inflates the headline figures. - Routes by module — read from the running application's URL map, so the count matches what the server actually serves.
- Component inventory — Flask blueprints, database models, Alembic migrations, systemd units and operator scripts.
Figures are cached for ten minutes. Click Recalculate in the page header to force a fresh measurement — no command line required. Signed-in users also get a JSON button exposing the same snapshot at /api/repo-stats.
The Security Center (Reports → Security → Security Center, /security/center) brings four related security views together on one tabbed page:
- Traffic — the full Traffic Analytics dashboard (described below), embedded inline.
- Malicious Logins — SQL/command-injection login attempts, with per-IP attack statistics and a one-click Ban button for any attacking source.
- Global Ban List — the single source of truth for banned IPs, enforced by multiple layers (the application gate, the host firewall, and fail2ban). Manage the allowlist and blocklist: ban an IP or CIDR range (permanently or for a set number of hours), toggle entries on/off, and clean up expired ones. Each entry shows a Source badge (Manual, Login Brute Force, SSH Brute Force, Malicious Request, …) and a Location column (country flag, city, region) when a MaxMind GeoLite2 database is configured under Traffic Analytics — IPv4 and IPv6. The tab also shows an Enforcement Status card, Security Metrics (failed logins 24h, IPs banned 24h, active bans, SSH attacks blocked, mirrored-to-firewall), and a firewall sync indicator with one-click Resync. A ban blocks the IP from the entire application, not just the login page. Loopback (
127.0.0.1) is always exempt for bans so you can never lock the appliance out of itself. Allowlist caution: adding any allowlist entry switches sign-in to allowlist-only mode — only listed IPs may log in, and loopback is not exempt there. To prevent self-lockout, the system refuses an allowlist entry that doesn't cover your current IP (you can confirm to override); add your own IP first if you intend to restrict access. - fail2ban — optional host-firewall enforcement of the single ban list. fail2ban ships pre-installed; there is only one ban list (the Banned IPs tab), and when you enable firewall enforcement here every application ban (manual or automatic) is also dropped at the host firewall before traffic reaches the web app. Toggle enforcement from the UI — no SSH needed; nothing is managed twice. You can also enable an optional
sshdjail to protect the host's SSH daemon; because an IP hammering port 22 is a bad actor everywhere, those offenders are automatically added to the global ban list (blocked at the web layer and all firewall ports), listed here, and cleared globally when you unban them here.
The remainder of this section describes the Traffic tab in detail.
A webalizer/awstats-style dashboard for the station's web traffic. Use the time-range selector in the header to switch between the last 24 hours and the last year, or pick Custom range… to choose explicit start/end dates.
- Custom date ranges & drill-down: pick a custom start/end window, then click any country, path, status code, browser, OS, HTTP method, or visitor IP to filter the entire dashboard to matching traffic. Active filters appear as removable chips at the top; click ✕ on a chip (or "Clear all") to remove them. The big tables (Top Pages, Top Visitors, Recent Requests, Error URLs) also have a live text filter box.
- Anomaly detection: a banner highlights operationally interesting deviations — elevated error rate, 5xx surges, likely vulnerability scanners (many 4xx from one IP), login brute-force bursts, and traffic spikes. Thresholds are tunable under Settings → Anomaly Detection, and the same data is available at
/api/traffic/anomalies. - Privacy / GDPR tools (Settings → Privacy): turn on Anonymize visitor IPs to mask addresses at capture time (so a raw IP is never stored), or erase/mask the records for a specific visitor on request — Anonymize keeps the rows but masks the IP/hostname, Purge deletes them entirely. No shell access needed.
- At-a-glance strip & charts: page views, unique visitors, total hits, successful logins, active sessions, average response time, bandwidth served, and bounce rate. Key tiles show a "vs previous period" delta and a sparkline. Charts include traffic-over-time, status codes, browsers, operating systems, device types (desktop/mobile/tablet), HTTP methods, authenticated vs anonymous, search engines, hour-of-day, day-of-week, and login activity.
- Visitor map: a world map with a marker over each country sized by traffic (needs a GeoLite2 Country/City database for non-local visitors).
- Visitor detail tables: top pages, slowest endpoints, top visitor hosts (with reverse-DNS hostname when enabled), operating systems and browsers (with brand logos), screen resolutions, countries/networks (with flags), cities with state/region (e.g. "Springfield, IL"), languages (with flags), referrers and search engines (with brand logos), file types and robots/spiders (with logos).
- Errors & scanners: top error URLs (4xx/5xx) and the source IPs generating them — each error source also shows the single path it errors on most and that status code, so a scanner probing
/wp-login.php(404) is obvious versus a dashboard hammering a 403/500 endpoint. Plus a Recent Requests table showing the full User-Agent string and parsed browser version. - Login security: successful vs. failed logins over time, top login source IPs, and the most recent login attempts — so you can spot brute-force activity.
IPv6 visitors: country, city, ASN/ISP and reverse-DNS all work for IPv6. Because IPv6 privacy addresses rotate per device, unique-visitor counts group IPv6 by its /64 network so one device isn't counted as many visitors (IPv4 is counted per address). An IPv4 vs IPv6 breakdown panel shows hits, visitors and distinct addresses per family alongside a reverse-DNS coverage figure (resolved / addresses) — handy because most IPv6 hosts publish no PTR record, so a low v6 coverage number is normal, not a fault. Reverse-DNS is also resilient: an authoritative "no PTR record" is remembered, but a slow or timed-out IPv6 lookup is retried on a later background pass (with a longer v6 timeout) instead of being given up on permanently.
Why source IPs now read correctly: the app sits behind nginx, so it now trusts the proxy's X-Forwarded-For header. Logins and sessions show the real client address instead of localhost.
Configure collection from the dashboard's Settings button: enable/disable logging, set the retention window, choose whether to record API requests or authenticated traffic only, exclude bots, turn on reverse-DNS hostname lookups, and enable country/flag resolution by either pointing at a MaxMind GeoLite2 .mmdb path or uploading the database right from the browser (validated and stored automatically — no shell access needed).
Keeping it fast & purging data: traffic is stored in the station database (the web_request_logs table), so a busy site can build up a large table that makes the dashboard slow to load. Two controls in Settings keep it in check: "Auto-purge records older than (days)" deletes old rows automatically (the background recorder prunes hourly — lower it, e.g. 30, for a smaller, faster table), and the Danger Zone → "Purge all traffic data" button wipes every recorded request in one click for an immediate reset. Both keep your settings and GeoIP databases; purging cannot be undone. The dashboard also caches its assembled view for a few seconds so repeated/auto-refreshes and multiple open tabs don't re-run every query.
Reverse DNS & flags (awstats-style): enabling "Resolve hostnames (reverse DNS)" shows each visitor's hostname instead of a bare IP. With a GeoLite2 database configured, public visitors also show their country flag. Hostname lookups happen in the background (off the request path) and are cached; leave them off if you'd rather not send visitor IPs to your DNS resolver. Hostnames also backfill automatically: rows recorded before you enabled this (or while DNS was briefly unreachable) get filled in by a background pass over the following minutes. An IP that simply has no PTR record will always show as a bare address — that's expected, not a bug.
Export: use the Export menu to download every report as a multi-section CSV (opens in Excel) or as a multi-page PDF report (charts and tables included).
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
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
Filtering the Received Alerts List
The Received Alerts page
(Monitor → Alerts → Received Alerts) supports
multi-select filtering with include/exclude modes:
- Audio Source & Event Type are checkbox dropdowns —
tick several values at once, and flip the Include / Exclude
toggle to hide a noisy source or filter weekly tests
(
RWT/RMT) out of the list entirely. Each option shows how many alerts it accounts for. - Active filter chips above the table show every applied value; click a chip's ✕ to remove just that value.
- Statistics cards (Total / Forwarded / Ignored / Errors) are clickable shortcuts that filter by forwarding decision.
- Filters combine and are carried through pagination, so a filtered view can be bookmarked or shared as a URL.
Originating Equipment
Every received alert's detail page (click into any row from the Received Alerts list) shows an Originating Equipment badge in the Reception panel — a best-effort guess at which ENDEC model produced the SAME transmission (SAGE Digital 3644, NWS BMH, Trilithic EASyPLUS, etc.), fingerprinted from transmission characteristics like terminator bytes and inter-burst gap timing rather than any field carried in the alert itself. The same detection also runs on manually uploaded recordings in the Audio Decoder tool.
Purging Received Alerts & Audio
Busy monitoring sources can record thousands of received alerts, and the raw
WAV audio captured with each one is the largest storage cost. The
Alert Purge page
(Settings → Admin Dashboard → Alert Purge,
also reachable from the Purge button on the Received Alerts page)
is the single place to clean this up.
- Filter what to remove by age (older than N days), source, forwarding decision (e.g. everything not forwarded), and/or SAME event code.
- Choose the scope: Audio only strips the stored WAV but keeps the record for the FCC compliance log; Entire alert deletes the record, and can also delete the generated broadcast message and its on-disk audio so no instance of the audio remains.
- Preview first to see how many records and how much audio a purge would affect before running it.
- Automatic Purge can run the same rules in the background (shortly after startup, then roughly every 6 hours).
US County Boundaries (IPAWS SAME Coverage)
The County Boundaries page
(Settings → Data & Storage → County Boundaries)
manages the Census TIGER/Line county shapefile used to draw highlighted county
outlines on IPAWS alert coverage maps. IPAWS/NWS alerts carry 6-digit SAME
geocodes (e.g. 039137) instead of polygon geometry; EAS Station™
converts those codes to county outlines by looking up this table.
Page Workflow
Sections are ordered top-to-bottom for a natural workflow:
-
Status Cards — Shows whether the
us_county_boundariestable exists, how many counties are loaded, how many states, and whether the bundled Census shapefile is present. - Load County Boundaries — Import data from the bundled Census shapefile (≈3,235 counties, optionally filtered to one state) or upload a custom ZIP shapefile.
-
Loaded States — Table listing every state that has county data
in the database. Each row has two action buttons:
- View on Map — loads that state's county outlines on the interactive map directly below this table.
- Delete — removes all county records for that state.
- County Boundary Map — Interactive Leaflet map. Use the state dropdown in the card header to choose a state, or click the button in the Loaded States table to jump directly to a state. Click any county outline to see its name, GEOID, and SAME code. Use Clear to reset the map.
- Search Counties — Real-time search by county name, 5-digit GEOID, or state abbreviation. Clicking a result loads that state on the map.
- Table Lookup / Diagnostics — Enter one or more 6-digit SAME codes or 5-digit GEOIDs (comma-separated) to verify they are present in the database. Useful for confirming coverage before an activation.
- 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.
Deep-dive tools for troubleshooting a receiver's RF front-end and audio pipeline, in one place per receiver.
- Live Waterfall: a continuously scrolling time-vs-frequency-vs-power view, updated roughly twice a second.
- Spectrum Scope: a classic frequency-vs-power line trace with a peak-hold overlay, sharing the waterfall's data feed so running both costs nothing extra.
- Zoom & pan (both views): use the magnifier buttons in either panel header, the mouse wheel to zoom about the cursor, or drag to pan; double-click resets to the full span. Zoom is shared between the waterfall and the scope, and the axis labels and status line always describe the window actually on screen — e.g.
64.0 kHz of 256.0 kHz · 125 Hz/bin. This crops the published FFT rather than retuning the receiver, so it costs nothing extra and stops at the FFT's real resolution instead of inventing detail. - Dead-air monitoring: watches monitored audio for loss of programme content and raises the tower light, optionally sounding a rack alarm buzzer. Configure the thresholds under Monitor → Audio & Radio → Audio Ingestion; the tower-light colour and rack-buzzer pin under Monitor → Station Hardware → Hardware Settings; and see live state (with the Acknowledge button) on the Audio Health dashboard. It checks the audio rather than the service, so it catches the case every other health check misses: the SDR locked and healthy while the station you are monitoring is off the air. Because an off-air FM receiver outputs full-scale hiss rather than silence, detection uses spectral flatness as well as level — leave “detect an unmodulated carrier” on for radio sources. Acknowledging the alarm silences the buzzer but leaves the light lit until audio actually returns.
- Historical Trends: charts of signal strength, lock percentage, sample-rate health, and buffer overflow/underflow over a selectable window (1h/6h/24h/7d), plus an always-on sparkline strip for an at-a-glance read.
- Run Full Diagnostics: a pass/warn/fail checklist covering the SDR service heartbeat, per-receiver health, ring-buffer drops, and spectrum-cache freshness — the same checks available from the command line via
scripts/diagnostics/check_sdr_status.py. - Snapshot Waterfall & Run Diagnostic: capture a short IQ window and get a clipping/front-end-health verdict plus a subcarrier inventory (pilot, stereo, RBDS, SCA).
/admin/radio/diagnostics
Manage and control all display outputs from a unified interface.
- Unified Dashboard: Access LED sign, VFD display, and OLED screen controls from one central page
- Status Monitoring: View connection status and current content for all displays at a glance
- Quick Actions: Jump to full control pages for detailed configuration and testing
- Recent Activity: See a consolidated feed of all display output history
- Individual Controls: Access advanced features like LED animations, VFD graphics, and OLED screen rotation
/displays
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,/api/monitoring/radio, and/api/gps_status - Visual Screen Editor: The drag-and-drop editor (Screens → New/Edit) exposes the full element palette per display type — including LED's "Message Type" toggle for switching a screen between scrolling text and Dots/graphics mode — and its Preview button renders through the same real device pipeline (icons, gauges, compasses, segmented meters and all) instead of an approximation, so what you design matches what the hardware shows
- LED Displays: Configure text content (4 lines × 20 chars) with color, animation mode, and speed settings, or use graphics mode (below) for a single icon+hero-value screen using the sign's real Picture File command
- VFD & OLED Graphics: Both displays share the same graphics engine — icons, a speedometer-style gauge, a compass/heading dial, a multi-value bar chart (e.g. per-satellite signal strength), a segmented VU-meter primitive (VFD), plus the OLED's analog clock face — not just plain text and progress bars. The VFD ships all 11 default screens the OLED does (Status, Alert Status, System Meters, Audio VU Meter, GPS Status, Network Status, GPIO Status, EAS Decoder, Audio Health, IPAWS Poller, Receivers)
- LED Graphics (Dots) Mode: The Alpha 9120C sign can also render icon+text screens on its 160×16 Picture File canvas — a smaller icon/text vocabulary than VFD/OLED (no gauge/compass, since the canvas is half the VFD's height), used by the 3 default graphics screens (Status, Alert, System). Requires a one-time, Admin-only, destructive setup step — see the "Sign Memory" panel on the LED control page's Dots tab — before graphics screens will display correctly; it allocates a dedicated file on the sign and erases all currently stored messages
- Active-Alert Visibility: The VFD's Status screen shows the current active-alert count alongside the time and date, and Alert Status shows the alert's event type and area — the VFD rotation keeps cycling through both while an alert is active instead of pausing
- 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, GPS position/fix status, and more
- Priority Management: Emergency screens override rotation; alerts pause normal displays
/screens
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
python tools/generate_sample_audio.py
When an over-the-air (OTA) alert is decoded, the system captures the voice narration that follows the attention tone and can relay it during auto-forwarding. Some upstream ENDECs and air-chain processors gate their record input, transmitting narration that stutters — words chopped by near-silence gaps with abrupt restarts. The system analyzes every captured narration for this signature and shows the verdict on the received-alert detail page.
The Relay Narration Audio setting (Admin → EAS Encoder Settings) controls what goes to air when relaying:
- Auto (recommended) — relay the captured off-air narration unless it is detected as gate-chopped, in which case a clean narration is synthesized with the configured TTS provider.
- Captured off-air audio — always relay the captured narration exactly as received (legacy behavior).
- Always local TTS — always synthesize the narration locally.
The same alert often arrives from more than one source — a CAP feed and an OTA relay, or two relay streams — within minutes of each other. Auto-forwarding suppresses these cross-source duplicates using two configurable windows (Admin → EAS Encoder Settings → Deduplication & Audio Detection):
- Cross-Source Dedup Window (default 15 min) — used when there is no usable SAME header to compare, only a matching event code and FIPS set.
- Header-Key Dedup Window (default 1440 min / 24 hours) — used when a SAME header is present, matched independently of which station/callsign sent it. This is the longer window because the same NWS issuance can legitimately be re-relayed by different stations hours apart.
Min Confidence to Log (default 0, disabled) filters the Received Audio Alerts log itself, not forwarding. It only applies to detections with no decoded event code — low-confidence noise from a marginal signal. A real decode is always logged regardless of confidence, even one reporting an alert outside this station's coverage area (e.g. from a nationwide relay network) — that is a true decode being correctly filtered downstream, not noise.
Before alert text is sent to the TTS engine it passes through a four-layer normalization pipeline that converts abbreviated and machine-formatted text into natural spoken language.
The Four Layers
-
Time expansion — compact clock times are converted
to fully-spoken equivalents so every TTS backend gives the same
natural result.
1100 PM→ eleven o'clock PM ·9:30 AM→ nine thirty AM -
NWS-specific cleanup — three rules handle
formatting conventions unique to NOAA/NWS alert text:
- Alternate-timezone slash notation — NWS writes
/5 PM CDT/to show a deadline in a second timezone; the slashes are stripped so TTS does not read them literally. - Saint abbreviation —
ST.is expanded to Saint before proper nouns (e.g. Saint Joseph). - Indiana county disambiguation — NWS appends the
state code
INafter a county name that appears in more than one watch state (e.g.ALLEN IN→ ALLEN Indiana,CASS IN→ CASS Indiana). The substitution is applied only when the preceding word is a recognised Indiana county name and the following word is not a directional word or state name, so common phrases like IN EFFECT and section headers like IN MICHIGAN are never altered.
- Alternate-timezone slash notation — NWS writes
-
Built-in acronym table — hard-coded expansions
for EAS/NWS tokens, all US timezone abbreviations, and US state
codes used as county-name markers:
NWS→ National Weather Service ·EDT→ Eastern Daylight Time ·MI→ Michigan ·OH→ Ohio ·AFD→ Air Force Depot · and more - Custom pronunciation dictionary — your own word-substitution rules, applied last and longest-first so multi-word entries are never masked by shorter ones.
Accessing the Tools
-
TTS Settings & Pronunciation Preview —
Navigate to Admin → TTS Settings or visit
/admin/tts. Paste any alert text into the Pronunciation Preview panel to see exactly what the TTS engine will receive before going live. -
Custom Pronunciation Rules —
Navigate to Admin → TTS Settings then click
Pronunciation Dictionary, or visit
/admin/tts/pronunciation. Add entries for place names, call letters, or any term your TTS engine mispronounces. Rules support optional case-sensitive matching and a note field for documentation.
Required Weekly Test (RWT) broadcasts are scheduled automatically: one test per week, on one of the days you allow, at a random time inside your window.
Accessing Weekly Test Automation
- Navigate to Diagnostics → Tests & Verification → Weekly Test Schedule from the navigation menu
- Or visit
/rwt-scheduledirectly
Configuration Options
- Enable/Disable: Toggle automatic RWT broadcasts on or off
- Allowed Days: The days the test is permitted to land on (Monday through Sunday). The scheduler picks one of them each week — ticking Sunday and Tuesday means one test, on a Sunday or a Tuesday, not one on each. Allowing more days makes the test less predictable, which is what 47 CFR §11.61 asks for; it does not send more tests.
- Time Window: Set start and end times (e.g., 8:00 AM to 4:00 PM). The exact minute is drawn at random from inside this window each week.
- 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.
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 Week: Exactly one RWT per week, however many days you allow. If the station is down during the chosen slot, the test is caught up on a later allowed day in the same week.
- 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.
Troubleshooting
- Check Logs: Run
sudo journalctl -u eas-station-web.service -fto see service startup messages. - Database Connection: Verify
POSTGRES_*settings in/opt/eas-station/.envmatch your database deployment. - Secret Key: Ensure
SECRET_KEYis set to a non-empty value. - Port Conflicts: Confirm port 5000 isn't already in use.
- 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
Service Management
# View logs
sudo journalctl -u eas-station-web.service -f
# Restart services
sudo systemctl restart eas-station.target
# Check service status
sudo systemctl status eas-station.target
Database Operations
# Reset database
python tools/reset_database.py
# Check health
python tools/check_db_health.py
Audio & Testing
# Generate test audio
python tools/generate_sample_audio.py
# Test receivers
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
-
1Check Documentation: Review this guide and the About page for system information.
-
2Review Logs: Run
sudo journalctl -u eas-station.target -fto identify error messages. -
3Check System Health: Visit System Health for status overview.
-
4Search Issues: Look for similar problems on GitHub Issues.
-
5Create New Issue: Provide logs, configuration (redact secrets), and steps to reproduce.
Trusted Field Resources
Curated references from NOAA, FEMA IPAWS, and ARRL to keep operations sharp.
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.