Over-the-air weather alerts for your desktop or RPi.
This crate provides a digital demodulator and decoder for Specific Area Message Encoding (SAME). It can detect the presence of SAME messages in an audio signal and report them to the caller.
This crate is dual-licensed MIT and Apache 2.0. Read these licenses carefully as they may affect your rights.
This crate 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.
A complete example may be found in our
samedec crate, which provides a
command-line program for decoding SAME via pipes.
You will first need to recover baseband audio from a radio or television station which broadcasts SAME signals. Obtain the audio signal that you would normally listen to. You can use either
In either case, obtaining the audio is beyond the scope of this crate. To sample your soundcard, try cpal. If you have a stereo signal, mix to mono first. If you are demodulating wideband FM, and your demodulator offers you a choice, choose mono-only demodulation.
```rust use sameold::{FrameOut, Message, SameReceiverBuilder};
// Create a SameReceiver with your audio sampling rate // Sound cards typically run at 44100 Hz or 48000 Hz. Use // an input rate of at least 8000 Hz. let mut rx = SameReceiverBuilder::new(48000) .withagcbandwidth(0.05) // AGC bandwidth at symbol rate, < 1.0 .withagcgainlimits(1.0/(i16::MAX as f32), 1.0/200.0) // for i16 .withsquelchpower(0.10, 0.05) // squelch open/close power, 0.0 < power < 1.0 .withpreamblemaxerrors(2) // bit error limit when detecting sync sequence .build();
// let audiosrc be an iterator which outputs audio samples, // such as a BufReader bound to stdin or a file, in f32 // format at the sampling rate (here 48000 Hz) let audiosrc = someaudiosourceiterator(); for msg in rx.itermessages(audiosrc) { match msg { Message::StartOfMessage(hdr) => { println!("begin SAME voice message: {}", hdr); } Message::EndOfMessage => { println!("end SAME voice message"); } } } ```
The digital receiver is created via a builder.
The
SameReceiver
binds by iterator to any source of f32 PCM mono (1-channel) audio samples. If
you're using i16 samples (as most sound cards do), you'll need to cast them to
f32. There is no need to scale them as long as you configure the AGC properly,
as above.
The iterator consumes as many samples as possible until the next
[Message] is decoded.
You can use the
[iter_frames()]((https://docs.rs/sameold/latest/sameold/struct.SameReceiver.html#method.iter_frames)
method instead to obtain more information about what the demodulator is
doing, including errors framing messages.
The [Message] type marks the start or end of a SAME message. The
actual "message" part of a SAME message is the audio itself, which
should contain a voice message that
This crate decodes the digital headers and trailers which summarize the message. An example header, as received "off the wire" in ASCII format, is:
txt
ZCZC-WXR-RWT-012345-567890-888990+0015-0321115-KLOX/NWS-
If this was the header string received, then you could decode
hdr from the previous example as follows:
```rust use sameold::{EventCode, Originator, SignificanceLevel};
// what organization originated the message? assert_eq!(Originator::NationalWeatherService, hdr.originator());
// event code // in actual implementations, handle this error gracefully! let evt = hdr.event().expect("unknown event code"); assert_eq!(EventCode::RequiredWeeklyTest, evt);
// events have a "significance level" which describes how // urgent or actual they are asserteq!(SignificanceLevel::Test, evt.tosignificance_level()); assert!(SignificanceLevel::Test < SignificanceLevel::Warning);
// location codes are accessed by iterator let firstlocation = hdr.locationstriter().next(); asserteq!(Some("012345"), first_location); ```
SAME messages are always transmitted three times for redundancy.
When decoding the message header, sameold will use all three
transmissions together to improve decoding. Only one
[Message::StartOfMessage] is output for all three header transmissions.
The trailers which denote the end of the message are not subject to
this error-correction process. One [Message::EndOfMessage] is
output for every trailer received. There may be up to three
EndOfMessage output for every complete SAME message.
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:
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.
chrono: Use chrono to calculate message
issuance times
and other fields as true UTC timestamps. If enabled, chrono
becomes part of this crate's public API.If you have a recording of a signal that you think should demodulate, but doesn't, please open an new issue on github. Either attach or link to your recording.
Please read our contributing guidelines before opening any issues or PRs.
License: MIT OR Apache-2.0