cbs228 / sameold

SAME/EAS decoding for Rust 🦀

binary | library | api docs

sameold: SAME/EAS Demodulation

Over-the-air weather alerts for your desktop or RPi.

This project provides a digital demodulator and decoder for Specific Area Message Encoding (SAME). SAME is commonly used to distribute weather alerts in the United States and Canada. It was originally developed for use with broadcast stations that carry analog audio signals, such as:

• NOAA Weather Radio
• Commercial FM radio broadcast stations
• Commercial television broadcast and cable networks

These stations participate in an emergency alerting network known as the Emergency Alert System, which disseminates alerts to the general public.

SAME messages are transmitted in place of the station's normal programming as an audio-only message. SAME messages include a digital header which separates them from the station's normal programming. The digital header is also sent in-band—encoded with an analog modulation to preserve it. SAME headers are modulated using two-level frequency-shift keying (FSK) and sent at a baud rate of 520.83 Hz.

This project provides a Rust library and executable for decoding SAME messages.

Disclaimer

This project is dual-licensed MIT and Apache 2.0. Read these licenses carefully as they may affect your rights.

This project has not been certified as a weather radio receiver or for any other purpose. The author strongly discourages its use in any safety-critical applications. Always have at least two methods available for receiving weather alerts.

Getting Started

Binaries

Binary builds are available on the releases page for a variety of platforms. Linux binaries are currently built against glibc 2.28 and should be portable to most distros.

Building

You will need a working rust toolchain.

To build and install binaries from this repository, run

cargo install --path crates/samedec
samedec --help

Then see the binary's README for further instructions.

Containerized Build

Containerized builds are available for any architecture supported by the official rust image. This example uses podman, but similar commands exist in other container managers:

DOCKER_BUILDKIT=1 podman build . --tag samedec:latest
podman run --rm -it --userns=keep-id samedec:latest

Arguments to run are samedec arguments. See the binary's README for additional documentation.

Container binaries are not published at present.

Add SAME decoding to your own project

Add the following to your Cargo.toml:

[dependencies]
sameold = "0.4"

Then read our API documentation.

Contributing

If you have a recording of a signal that you think should demodulate, but doesn't, please open an new issue. Either attach or link to your recording.

Please read our contributing guidelines before opening any issues or PRs.

sameold's Issues

Create an example of how to use with a RTL SDR

I am confused on how to implement this with an RTL SDR

Add fallback decoder

Currently, all three AFSK data bursts must be detected in order for sameold to report a Message to the client. Noise or sync issues might prevent sameold from decoding all three bursts. We should be able to operate on just two—so long as they are identical.

Add a fallback decoder for this scenario. Also ensure that the timeout is long enough that we can miss the middle burst.

All headers output option

Is it possible to add an option to output every SAME code header as they were received instead of a single one? That would be very helpful for testing. I am currently using the 'multimon-ng', which does it by default but I am not completely satisfied with it. I would like to try the 'samedec' instead but I need to see every header in the burst as long as the preamble got decoded correctly.

samedec: Windows and/or Mac support?

Right now, samedec is only tested on x86_64-pc-linux-gnu. It is unclear if it works correctly on Windows, Mac, or other platforms. Most of the instructions are written for linux.

I am unable to provide direct assistance with these other platforms. If samedec does not work, and you can contribute platform-specific fixes or advice, please feel free to do so.

Help wanted: distro packaging

If you enjoy using samedec and would like it to be packaged for your distro, consider volunteering to be a packager. Special attention is requested for distros which run on low-powered ARM hardware, like the raspberry-pi flavor of Ubuntu. The Debian project has a specific procedure for packaging Rust programs.

samedec is free software and does not require any special permission in order to be packaged. If you would like to be recognized for your efforts, or if there are changes that would make it easier to package this software, please comment on this issue.

Per-Header / EOM Output in a verbosity level

Hey there!

I am currently writing a Python app that uses a system call to pipe external audio into an app such as this one, however I have a dilemma.
Currently, I am using Multimon-NG to do this task right now, but due to some samplerate issues, I am required to move to a new codebase for the monitoring, and SameDec is perfect, except one issue.
With Multimon-NG, The SAME in Verbose mode allows to see "Part" Messages, or each individual data burst as they come in, as well as the End Of Messages. My codebase can work with the single Message that SameDec/SameOld puts out, however the End Of Message tones are the issue.
Due to SameOld only outputting EOMs when 3 have been received, this can cause some issues where not all 3 have been sent, received, or in some specific cases such as the Trilithic EASyPLUS and Cox Communication EAS relays, the EOMs can be faster or slower. (Example: Cox Communications, Trilithic EASyPLUS)
Is it possible to make SameOld/SameDec do this in a Verbosity Level, Such as display the bursts as received and decoded?

Closely-spaced EOM/SOM might not decode

samedec may fail to decode a start-of-message (SOM) if:

1. it is spaced very closely to a preceding end-of-message (EOM); and
2. the first EOM header is missed.

i.e.:

NNNN
NNNN
ZCZC-WXR-TOR-…
ZCZC-WXR-TOR-…
ZCZC-WXR-TOR-…

If the messages are spaced more closely than MAX_INTERBURST_GAP_SYMBOLS, Framer::bursts will contain a mixture of EOM and SOM headers. The SOM will be missed.

Handling this situation potentially requires:

• limiting bursts to only SOM
• adding some logic to disambiguate
• implementing the fallback decoder from #4.

sameold: location API

At present, sameold only supports retrieving the six-digit SAME location codes (PSSCCC). No further interpretation is performed. We should consider:

• Adding a type to represent the SAME location code
• Containment tests: is the area specified by code X contained in the area specified by code Y?
  • United States FIPS code
  • Canada Location Code
• Providing a location database which maps codes to place names. In the United States, there are many codes for marine areas and other places which are not part of core FIPS, and there are several different lists.
• Providing a location database which maps codes to geo-referenced POLYGON geometries. This database would likely be very large and need constant updating.

Download locations for GIS files, as of this writing. These files are subject to periodic update and should not be used blindly.

• U.S. Counties (partial & full): https://www.weather.gov/source/gis/Shapefiles/County/cs10nv20.zip: represents SAME codes directly
• Coastal Marine Zones: https://www.weather.gov/source/gis/Shapefiles/WSOM/mz30mr21.zip: the ID field is named zzZnnn. An example is ID AMZ158 → SAME 075158 The last three digits nnn map directly to a SAME code suffix. The first two alphanumerics map to a "state" field per this page.
  • AM: 75
  • AN: 73
  • GM: 77
  • LC: 94
  • LE: 96
  • LH: 93
  • LM: 92
  • LO: 97
  • LS: 91
  • PH: 59
  • PK: 58
  • PM: 65
  • PS: 61
  • PZ: 57
  • SL: 98
• Offshore Marine Zones: https://www.weather.gov/source/gis/Shapefiles/WSOM/oz16ap19.zip: identical ID mapping to the above
• Canada:
  • Land: https://dd.weather.gc.ca/meteocode/geodata/version_6.6.0/MSC_Geography_Pkg_V6_6_0_Land_KMZ.zip, see land_PubMesoZone_detail.kmz
  • Water: https://dd.weather.gc.ca/meteocode/geodata/version_6.6.0/MSC_Geography_Pkg_V6_6_0_Water_KMZ.zip, see water_MarStdZone_detail.kmz.
  • Placenames only: https://dd.weather.gc.ca/meteocode/geodata/version_6.6.0/Documentations/Location_Metadata_V6_6_0_UTF8.txt