Struct SameReceiverBuilder

pub struct SameReceiverBuilder { /* private fields */ }

Builds a SAME/EAS receiver

The builder comes with a sensible set of default options. All you really need to provide is the input sampling rate. The SameReceiver was designed to work well at a sampling rate of 22050 Hz, however, and you may wish to tweak some of these values.

The API specified by the builder is part of this crate’s API. The actual default values are not, however, and are subject to revision in any minor release. If you care very strongly about a setting, be sure to configure it here.

Implementations

impl SameReceiverBuilder

pub fn new(input_rate: u32) -> Self

New receiver chain with “sensible” defaults

The only mandatory parameter is the input sampling rate, in Hz. To avoid computationally-intensive resampling in your sound server, you should use one of the native output rates of your sound card or an easy division thereof. 22050 Hz is a popular choice. The SameReceiver can be designed for a variety of different sampling rates.

pub fn build(&self) -> SameReceiver

Build a receiver chain

Once built, the receiver chain is immediately ready to process samples.

pub fn with_dc_blocker_length(&mut self, len: f32) -> &mut Self

DC-blocking filter length (fraction of baud rate)

Some analog audio interconnects and demodulation methods will produce an audio signal that has a DC bias. A DC bias may cause the AGC loop or the timing recovery to behave erratically, and it must be eliminated.

Set len to a non-zero value to use a DC-blocking filter with a length of len SAME symbols. The SAME baud rate is 520.83 symbols/second. This value can be greater than 1.0 if you want the DC-blocking filter to evolve very slowly. A len of 0.0 disables the DC-blocking filter.

The DC-blocking filter imposes a delay of len baud.

pub fn with_agc_bandwidth(&mut self, bw: f32) -> &mut Self

Automatic gain control bandwidth (fraction of baud rate)

Controls how fast the AGC is permitted to update. Bandwidth is expressed as a fraction of the SAME baud rate, which is 520.83 Hz. This value may be greater than 1.0 if you want the AGC to evolve significantly faster than one symbol.

pub fn with_agc_gain_limits(&mut self, min: f32, max: f32) -> &mut Self

Automatic gain control gain limits

Set the minimum and maximum AGC gains. For a fixed-point input type like i16, you should probably set the minimum gain to 1 / i16::MAX and the maximum to around 30× that.

Correctly limiting the gain range will result in faster convergence.

pub fn with_timing_bandwidth( &mut self, unlocked_bw: f32, locked_bw: f32, ) -> &mut Self

Timing loop bandwidth (fraction of baud rate)

The timing loop bandwidth controls how quickly the symbol timing estimate is allowed to change. There are two values:

1. The first value is used when the system has not yet acquired the SAME preamble / byte sync.

2. The second value is used when byte sync is acquired. The second value is clamped to the

The loop bandwidth is specified as a fraction of the SAME baud rate, which is 520.83 Hz.

pub fn with_timing_max_deviation(&mut self, max_dev: f32) -> &mut Self

Maximum timing deviation (fraction of baud rate)

max_dev is the maximum permitted deviation from the ideal SAME baud rate, which is 520.83 Hz. max_dev should be given in fractions of one baud, where 0.0 represents no deviation and 0.5 represents an entire half-symbol of deviation. Keep this value small!

pub fn with_squelch_power(&mut self, open: f32, close: f32) -> &mut Self

Squelch power thresholds (linear power)

Require a minimum symbol power of open in order to begin decoding a frame. Stop decoding a frame if the power drops below close. These values are linear powers in units of amplitude^2.

Prior to demodulation, AGC normalizes the received signal to an amplitude of 1.0. These power values should range from [0.0, 1.0]. A value of 0.0 disables the power squelch, and a value of 1.0 requires a no-noise perfect demodulation.

We recommend setting open ≥ close.

pub fn with_squelch_bandwidth(&mut self, bw: f32) -> &mut Self

Squelch power tracker bandwidth (fraction of baud rate)

The power squelch is smoothed with a single-pole IIR filter with bandwidth bw. The bandwidth is a fraction of the baud rate.

pub fn with_preamble_max_errors(&mut self, max_err: u32) -> &mut Self

Maximum preamble sync bit errors

The SameReceiver detects the start of a frame by correlating with four bytes (32 bits) of the SAME preamble. The preamble is a total of 16 bytes long. When acquiring the preamble, we permit some errors to occur. (We hope that the adaptive equalizer will lower the error rate farther down the chain.)

Set how many bit errors to allow. 0 requires the sync estimate to be error-free.

When setting this value, we suggest consulting with the ambiguity function for four bytes of the SAME preamble: 0xabababab. Shifting from zero to eight bits, we find bit errors of:

[0, 24, 8, 24, 8, 24, 8, 24, 0]

This indicates that invalid offsets are only off by eight bits. The maximum value of this parameter is therefore capped at 7. We suggest a value of 2 or 3.

pub fn with_adaptive_equalizer(&mut self, eql: &EqualizerBuilder) -> &mut Self

Set adaptive equalizer parameters

To configure the adaptive equalizer, generate an EqualizerBuilder and provide it to this method.

pub fn without_adaptive_equalizer(&mut self) -> &mut Self

Disable the adaptive equalizer

pub fn with_frame_prefix_max_errors(&mut self, max_err: u32) -> &mut Self

Maximum frame start bit errors

max_err is the maximum number of bit errors permitted when detecting the “beginning of burst” data sequence, “ZCZC” or “NNNN.” These byte sequences are allowed to begin a SAME/EAS data transmission, and the framer uses them to determine when to begin reading data.

Once the framer detects either of these values, further changes to the byte synchronization are disallowed until carrier is dropped.

We recommend setting this value between zero and two.

pub fn with_frame_max_invalid(&mut self, max_invalid: u32) -> &mut Self

Maximum frame invalid bytes

The framer will detect the end of a SAME burst after a total of max_invalid “invalid” SAME characters have been received. SAME/EAS uses ASCII bytes, but not all valid ASCII bytes are valid as SAME characters.

This error count helps detect the end of a SAME burst. If more than max_invalid bytes are received, the burst is ended.

SAME/EAS transmissions are repeated three times, and it is often necessary to perform parity correction to recover a valid message. The end-of-burst is difficult to detect in noisy conditions. This field balances the need to detect end-of-frame with permitting frame errors that will (hopefully) be corrected later.

Some NWR transmitters have been observed transmitting five or six zero bytes at the end of each burst. This behavior is not in the SAME standard, but it does help us detect end-of-frame when present.

You should probably set this field to 5 or 6.

pub fn input_rate(&self) -> u32

Input sampling rate (Hz)

pub fn dc_blocker_length(&self) -> f32

DC-blocking filter length (fraction of baud rate)

The DC-blocking filter imposes a delay of len baud. A value of 0.0 disables the DC blocker.

pub fn agc_bandwidth(&self) -> f32

AGC bandwidth (fraction of input rate)

pub fn agc_gain_limits(&self) -> &[f32; 2]

AGC lower and upper gain limit

pub fn timing_bandwidth(&self) -> (f32, f32)

Timing loop bandwidth (fraction of baud rate)

Returns both unlocked and locked timing loop bandwidth, as a fraction of the baud rate.

pub fn timing_max_deviation(&self) -> f32

Timing maximum deviation (fraction of baud rate)

pub fn squelch_power(&self) -> (f32, f32)

Squelch power level

Returns tuple of squelch (open, close) power level. A power level of 0.0 disables the power squelch. A power level of 1.0 requires a completely clean demodulation.

pub fn squelch_bandwidth(&self) -> f32

Squelch bandwidth (fraction of baud rate)

pub fn preamble_max_errors(&self) -> u32

Maximum preamble sync bit errors

pub fn adaptive_equalizer(&self) -> Option<&EqualizerBuilder>

Adaptive equalizer configuration

pub fn frame_prefix_max_errors(&self) -> u32

Maximum frame start bit errors

pub fn frame_max_invalid(&self) -> u32

Maximum frame invalid bytes

Trait Implementations

impl Clone for SameReceiverBuilder

fn clone(&self) -> SameReceiverBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SameReceiverBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SameReceiverBuilder

fn default() -> Self

Returns the “default value” for a type.

impl From<&SameReceiverBuilder> for SameReceiver

fn from(cfg: &SameReceiverBuilder) -> Self

Create the SAME Receiver from its Builder

impl PartialEq for SameReceiverBuilder

fn eq(&self, other: &SameReceiverBuilder) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for SameReceiverBuilder

fn partial_cmp(&self, other: &SameReceiverBuilder) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for SameReceiverBuilder

impl StructuralPartialEq for SameReceiverBuilder