Modem Configuration

The primary configuration structures for libquiet are quiet_encoder_options and quiet_decoder_options. Although it is possible to modify values in these structures, it is generally recommended to use the JSON-based configuration system instead, as that system works consistently across all platforms. This page documents how to configure from the JSON profiles as well as the raw configuration structures themselves.

quiet_decoder_profile_file

quiet_decoder_options *

quiet_decoder_profile_file(FILE *f,

                           const char *profilename);

libquiet's configuration options are fairly numerous, and testing can be frustrating when configuration requires recompilation. For this reason, libquiet provides a JSON file containing multiple sets of configuration profiles and functions to read and validate them.

Each profile provides access to every option contained in quiet_encoder_options/quiet_decoder_options. It is hoped that this will give good default options and provide a starting place for users to tune new profiles.

quiet_decoder_profile_file reads the profile given by profilename from the file pointer and returns the corresponding quiet_decoder_options.

Parameters

f - file pointer which contains a valid JSON libquiet profile set

profilename - the string key of the profile to fetch

Returns

a pointer to an initialized quiet_decoder_options or NULL if decoding failed. must be freed by caller (with free()).

quiet_decoder_profile_filename

quiet_decoder_options *

quiet_decoder_profile_filename(const char *fname,

                               const char *profilename);

quiet_decoder_profile_filename reads the profile given by profilename from the file located at filename and returns the corresponding quiet_decoder_options.

Parameters

fname - path to a file which will be opened and read, must contain a valid JSON liquiet profile set

profilename - the string key of the profile to fetch

Returns

a pointer to an initialized quiet_decoder_options or NULL if decoding failed. must be freed by caller (with free()).

quiet_decoder_profile_str

quiet_decoder_options *

quiet_decoder_profile_str(const char *input,

                          const char *profilename);

quiet_decoder_profile_str reads the profile given by profilename from the input and returns the corresponding quiet_decoder_options.

Parameters

input - a string containing a valid JSON libquiet profile set

profilename - the string key of the profile to fetch

Returns

a pointer to an initialized quiet_decoder_options or NULL if decoding failed. must be freed by caller (with free()).

quiet_encoder_profile_file

quiet_encoder_options *

quiet_encoder_profile_file(FILE *f,

                           const char *profilename);

quiet_encoder_profile_file reads the profile given by profilename from the file pointer and returns the corresponding quiet_encoder_options.

Parameters

f - file pointer which contains a valid JSON libquiet profile set

profilename - the string key of the profile to fetch

Returns

a pointer to an initialized quiet_encoder_options or NULL if decoding failed. must be freed by caller (with free()).

quiet_encoder_profile_filename

quiet_encoder_options *

quiet_encoder_profile_filename(const char *fname,

                               const char *profilename);

quiet_encoder_profile_filename reads the profile given by profilename from the file located at filename and returns the corresponding quiet_encoder_options.

Parameters

fname - path to a file which will be opened and read, must contain a valid JSON liquiet profile set

profilename - the string key of the profile to fetch

Returns

a pointer to an initialized quiet_encoder_options or NULL if decoding failed. must be freed by caller (with free()).

quiet_encoder_profile_str

quiet_encoder_options *

quiet_encoder_profile_str(const char *input,

                          const char *profilename);

quiet_encoder_profile_str reads the profile given by profilename from the input and returns the corresponding quiet_encoder_options.

Parameters

input - a string containing a valid JSON libquiet profile set

profilename - the string key of the profile to fetch

Returns

a pointer to an initialized quiet_encoder_options or NULL if decoding failed. must be freed by caller (with free()).

quiet_encoder_options

typedef struct {

    quiet_ofdm_options ofdmopt;

    quiet_modulator_options modopt;

    quiet_resampler_options resampler;

    quiet_encoding_t encoding;

    quiet_checksum_scheme_t checksum_scheme;

    quiet_error_correction_scheme_t inner_fec_scheme;

    quiet_error_correction_scheme_t outer_fec_scheme;

    quiet_modulation_scheme_t mod_scheme;

    bool header_override_defaults;

    quiet_checksum_scheme_t header_checksum_scheme;

    quiet_error_correction_scheme_t header_inner_fec_scheme;

    quiet_error_correction_scheme_t header_outer_fec_scheme;

    quiet_modulation_scheme_t header_mod_scheme;

    size_t frame_len;

} quiet_encoder_options;

This specifies a complete set of options for the encoder in libquiet.

ofdmopt

OFDM options, used only by OFDM mode.

modopt

Interpolation filter and carrier frequency options.

resampler

Resampler configuration (if specified frequency is not 44.1kHz)

encoding

Encoder mode, one of {ofdm_encoding, modem_encoding, gmsk_encoding}.

checksum_scheme

inner_fec_scheme

outer_fec_scheme

mod_scheme

header_override_defaults

Header schemes These control the frame header properties Only used if header_override_defaults = true.

header_checksum_scheme

header_inner_fec_scheme

header_outer_fec_scheme

header_mod_scheme

frame_len

Maximum frame length.

This value controls the maximum length of the user-controlled section of the frame. There is overhead in starting new frames, and each frame performs its own CRC check which either accepts or rejects the frame. A frame begins with a synchronization section which the decoder uses to detect and lock on to the frame. Over time, the synchronization will drift, which makes shorter frames easier to decode than longer frames.

quiet_decoder_options

typedef struct {

    quiet_ofdm_options ofdmopt;

    quiet_demodulator_options demodopt;

    quiet_resampler_options resampler;

    quiet_encoding_t encoding;

    bool header_override_defaults;

    quiet_checksum_scheme_t header_checksum_scheme;

    quiet_error_correction_scheme_t header_inner_fec_scheme;

    quiet_error_correction_scheme_t header_outer_fec_scheme;

    quiet_modulation_scheme_t header_mod_scheme;

    bool is_debug;

} quiet_decoder_options;

This specifies a complete set of options for the decoder in libquiet.

In order for a decoder to decode the signals from an encoder, certain options must match between both. In particular, the encoding mode and modopt/demodopt must match. Additionally, if ofdm_encoding is used, then the ofdmopt must also match. If the header options are overriden in the encoder, then they must also be overriden in the decoder.

ofdmopt

OFDM options, used only by OFDM mode.

demodopt

Decimation filter and carrier frequency options.

resampler

Resampler configuration (if specified frequency is not 44.1kHz)

encoding

Encoder mode, one of {ofdm_encoding, modem_encoding, gmsk_encoding}.

header_override_defaults

Header schemes These control the frame header properties Only used if header_override_defaults = true.

header_checksum_scheme

header_inner_fec_scheme

header_outer_fec_scheme

header_mod_scheme

is_debug

Enable debug mode on receiver.

In order for this flag to work, libquiet must be compiled in debug mode (#define QUIET_DEBUG 1). Once enabled, this mode causes the decoder to use liquid to create debug files which can be viewed in matlab/octave. These files have the filename format framesync_d, where d is an increasing number. These files can be useful for tracking the decoder's behavior.

quiet_modulator_options

typedef struct {

    unsigned int shape;

    unsigned int samples_per_symbol;

    unsigned int symbol_delay;

    float excess_bw;

    float center_rads;

    float gain;

    quiet_dc_filter_options dc_filter_opt;

} quiet_modulator_options;

This set of options is used only by the encoder

The modulator is a combination element which interpolates the encoded signal (rescaling in frequency domain) and then mixes it onto a carrier of a given frequency. Finally, a gain is applied, and an optional DC blocker removes DC components.

shape

Numerical value for shape of interpolation filter.

These values correspond to those used by liquid DSP. In particular,

1: Nyquist Kaiser

2: Parks-McClellan

3: Raised Cosine

4: Flipped Exponential (Nyquist)

5: Flipped Hyperbolic Secant (Nyquist)

6: Flipped Arc-Hyperbolic Secant (Nyquist)

7: Root-Nyquist Kaiser (Approximate Optimum)

8: Root-Nyquist Kaiser (True Optimum)

9: Root Raised Cosine

10: Harris-Moerder-3

11: GMSK Transmit

12: GMSK Receive

13: Flipped Exponential (root-Nyquist)

14: Flipped Hyperbolic Secant (root-Nyquist)

15: Flipped Arc-Hyperbolic Secant (root-Nyquist)

All other values invalid

samples_per_symbol

interpolation factor

symbol_delay

interpolation filter delay

excess_bw

interpolation roll-off factor

center_rads

carrier frequency, [0, 2*pi)

gain

gain, [0, 0.5]

dc_filter_opt

dc blocker options

quiet_demodulator_options

typedef struct {

    unsigned int shape;

    unsigned int samples_per_symbol;

    unsigned int symbol_delay;

    float excess_bw;

    float center_rads;

} quiet_demodulator_options;

This set of options is used only by the decoder

The demodulator is a combination element which inverts the operations of the modulator. It first mixes down from the carrier and then performs decimation to recover the signal.

shape

Numerical value for shape of decimation filter.

This uses the same set of values as quiet_modulator_options.shape

samples_per_symbol

decimation factor

symbol_delay

decimation filter delay

excess_bw

decimation roll-off factor

center_rads

carrier frequency, [0, 2*pi)

quiet_encoding_t

typedef enum {

    ofdm_encoding,

    modem_encoding,

    gmsk_encoding

} quiet_encoding_t;

Selects operational mode for encoder/decoder. OFDM and Modem mode use the same modulation schemes while gmsk ignores the supplied scheme and uses its own

ofdm_encoding

Encode/decode in OFDM mode.

modem_encoding

Encode/decode in modem mode.

gmsk_encoding

Encode/decode in gaussian minimum shift keying mode.

GMSK mode does not offer the modulation modes given by the other encodings. It has a fairly limited bitrate, but the advantage of GMSK is that its receiver does not need to compute any FFTs, making it suitable for low-power receivers or situations with little computational capacity.

quiet_ofdm_options

typedef struct {

    unsigned int num_subcarriers;

    unsigned int cyclic_prefix_len;

    unsigned int taper_len;

    size_t left_band;

    size_t right_band;

} quiet_ofdm_options;

These options configure the behavior of OFDM, orthogonal frequency division multiplexing, as used by the encoder. OFDM places the modulated symbols on to multiple orthogonal subcarriers. This can help the decoder estabilish good equalization when used on a system with uneven filtering.

num_subcarriers

total number of subcarriers used, inlcuding guard bands and pilots

cyclic_prefix_len

number of cyclic prefix samples between symbols

taper_len

number of taper window between symbols

left_band

number of extra guard subcarriers inserted on left (low freq)

right_band

number of extra guard subcarriers inserted on right (high freq)

quiet_checksum_scheme_t

typedef enum {

    quiet_checksum_none = 1,

    quiet_checksum_8bit,

    quiet_checksum_crc8,

    quiet_checksum_crc16,

    quiet_checksum_crc24,

    quiet_checksum_crc32

} quiet_checksum_scheme_t;

quiet_checksum_none

no error-detection

quiet_checksum_8bit

8-bit checksum

quiet_checksum_crc8

8-bit CRC

quiet_checksum_crc16

16-bit CRC

quiet_checksum_crc24

24-bit CRC

quiet_checksum_crc32

32-bit CRC

quiet_error_correction_scheme_t

typedef enum {

    quiet_error_correction_none = 1,

    quiet_error_correction_repeat_3,

    quiet_error_correction_repeat_5,

    quiet_error_correction_hamming_7_4,

    quiet_error_correction_hamming_7_4_parity,

    quiet_error_correction_hamming_12_8,

    quiet_error_correction_golay_24_12,

    quiet_error_correction_secded_22_16,

    quiet_error_correction_secded_39_32,

    quiet_error_correction_secded_72_64,

    quiet_error_correction_conv_12_7,

    quiet_error_correction_conv_12_9,

    quiet_error_correction_conv_13_9,

    quiet_error_correction_conv_16_15,

    quiet_error_correction_conv_perf_23_7,

    quiet_error_correction_conv_perf_34_7,

    quiet_error_correction_conv_perf_45_7,

    quiet_error_correction_conv_perf_56_7,

    quiet_error_correction_conv_perf_67_7,

    quiet_error_correction_conv_perf_78_7,

    quiet_error_correction_conv_perf_23_9,

    quiet_error_correction_conv_perf_34_9,

    quiet_error_correction_conv_perf_45_9,

    quiet_error_correction_conv_perf_56_9,

    quiet_error_correction_conv_perf_67_9,

    quiet_error_correction_conv_perf_78_9,

    quiet_error_correction_reed_solomon_223_255

} quiet_error_correction_scheme_t;

quiet_error_correction_none

no error-correction

quiet_error_correction_repeat_3

simple repeat code, r1/3

quiet_error_correction_repeat_5

simple repeat code, r1/5

quiet_error_correction_hamming_7_4

Hamming (7,4) block code, r1/2 (really 4/7)

quiet_error_correction_hamming_7_4_parity

Hamming (7,4) with extra parity bit, r1/2.

quiet_error_correction_hamming_12_8

Hamming (12,8) block code, r2/3.

quiet_error_correction_golay_24_12

Golay (24,12) block code, r1/2.

quiet_error_correction_secded_22_16

SEC-DED (22,16) block code, r8/11.

quiet_error_correction_secded_39_32

SEC-DED (39,32) block code.

quiet_error_correction_secded_72_64

SEC-DED (72,64) block code, r8/9.

quiet_error_correction_conv_12_7

convolutional code r1/2, K=7, dfree=10

quiet_error_correction_conv_12_9

convolutional code r1/2, K=9, dfree=12

quiet_error_correction_conv_13_9

convolutional code r1/3, K=9, dfree=18

quiet_error_correction_conv_16_15

convolutional code 1/6, K=15, dfree<=57 (Heller 1968)

quiet_error_correction_conv_perf_23_7

perforated convolutional code r2/3, K=7, dfree=6

quiet_error_correction_conv_perf_34_7

perforated convolutional code r3/4, K=7, dfree=5

quiet_error_correction_conv_perf_45_7

perforated convolutional code r4/5, K=7, dfree=4

quiet_error_correction_conv_perf_56_7

perforated convolutional code r5/6, K=7, dfree=4

quiet_error_correction_conv_perf_67_7

perforated convolutional code r6/7, K=7, dfree=3

quiet_error_correction_conv_perf_78_7

perforated convolutional code r7/8, K=7, dfree=3

quiet_error_correction_conv_perf_23_9

perforated convolutional code r2/3, K=9, dfree=7

quiet_error_correction_conv_perf_34_9

perforated convolutional code r3/4, K=9, dfree=6

quiet_error_correction_conv_perf_45_9

perforated convolutional code r4/5, K=9, dfree=5

quiet_error_correction_conv_perf_56_9

perforated convolutional code r5/6, K=9, dfree=5

quiet_error_correction_conv_perf_67_9

perforated convolutional code r6/7, K=9, dfree=4

quiet_error_correction_conv_perf_78_9

perforated convolutional code r7/8, K=9, dfree=4

quiet_error_correction_reed_solomon_223_255

Reed-Solomon m=8, n=255, k=223.

quiet_modulation_scheme_t

typedef enum {

    quiet_modulation_psk2 = 1,

    quiet_modulation_psk4,

    quiet_modulation_psk8,

    quiet_modulation_psk16,

    quiet_modulation_psk32,

    quiet_modulation_psk64,

    quiet_modulation_psk128,

    quiet_modulation_psk256,

    quiet_modulation_dpsk2,

    quiet_modulation_dpsk4,

    quiet_modulation_dpsk8,

    quiet_modulation_dpsk16,

    quiet_modulation_dpsk32,

    quiet_modulation_dpsk64,

    quiet_modulation_dpsk128,

    quiet_modulation_dpsk256,

    quiet_modulation_ask2,

    quiet_modulation_ask4,

    quiet_modulation_ask8,

    quiet_modulation_ask16,

    quiet_modulation_ask32,

    quiet_modulation_ask64,

    quiet_modulation_ask128,

    quiet_modulation_ask256,

    quiet_modulation_qask4,

    quiet_modulation_qask8,

    quiet_modulation_qask16,

    quiet_modulation_qask32,

    quiet_modulation_qask64,

    quiet_modulation_qask128,

    quiet_modulation_qask256,

    quiet_modulation_qask512,

    quiet_modulation_qask1024,

    quiet_modulation_qask2048,

    quiet_modulation_qask4096,

    quiet_modulation_qask8192,

    quiet_modulation_qask16384,

    quiet_modulation_qask32768,

    quiet_modulation_qask65536,

    quiet_modulation_apsk4,

    quiet_modulation_apsk8,

    quiet_modulation_apsk16,

    quiet_modulation_apsk32,

    quiet_modulation_apsk64,

    quiet_modulation_apsk128,

    quiet_modulation_apsk256,

    quiet_modulation_bpsk,

    quiet_modulation_qpsk,

    quiet_modulation_ook,

    quiet_modulation_sqask32,

    quiet_modulation_sqask128,

    quiet_modulation_v29,

    quiet_modulation_opt_qask16,

    quiet_modulation_opt_qask32,

    quiet_modulation_opt_qask64,

    quiet_modulation_opt_qask128,

    quiet_modulation_opt_qask256,

    quiet_modulation_vtech

} quiet_modulation_scheme_t;

quiet_modulation_psk2

phase-shift keying-2

quiet_modulation_psk4

phase-shift keying-4

quiet_modulation_psk8

phase-shift keying-8

quiet_modulation_psk16

phase-shift keying-16

quiet_modulation_psk32

phase-shift keying-32

quiet_modulation_psk64

phase-shift keying-64

quiet_modulation_psk128

phase-shift keying-128

quiet_modulation_psk256

phase-shift keying-256

quiet_modulation_dpsk2

differential phase-shift keying-2

quiet_modulation_dpsk4

differential phase-shift keying-4

quiet_modulation_dpsk8

differential phase-shift keying-8

quiet_modulation_dpsk16

differential phase-shift keying-16

quiet_modulation_dpsk32

differential phase-shift keying-32

quiet_modulation_dpsk64

differential phase-shift keying-64

quiet_modulation_dpsk128

differential phase-shift keying-128

quiet_modulation_dpsk256

differential phase-shift keying-256

quiet_modulation_ask2

amplitude-shift keying-2

quiet_modulation_ask4

amplitude-shift keying-4

quiet_modulation_ask8

amplitude-shift keying-8

quiet_modulation_ask16

amplitude-shift keying-16

quiet_modulation_ask32

amplitude-shift keying-32

quiet_modulation_ask64

amplitude-shift keying-64

quiet_modulation_ask128

amplitude-shift keying-128

quiet_modulation_ask256

amplitude-shift keying-256

quiet_modulation_qask4

quadrature amplitude-shift keying-4

quiet_modulation_qask8

quadrature amplitude-shift keying-8

quiet_modulation_qask16

quadrature amplitude-shift keying-16

quiet_modulation_qask32

quadrature amplitude-shift keying-32

quiet_modulation_qask64

quadrature amplitude-shift keying-64

quiet_modulation_qask128

quadrature amplitude-shift keying-128

quiet_modulation_qask256

quadrature amplitude-shift keying-256

quiet_modulation_qask512

quadrature amplitude-shift keying-512

quiet_modulation_qask1024

quadrature amplitude-shift keying-1024

quiet_modulation_qask2048

quadrature amplitude-shift keying-2048

quiet_modulation_qask4096

quadrature amplitude-shift keying-4096

quiet_modulation_qask8192

quadrature amplitude-shift keying-8192

quiet_modulation_qask16384

quadrature amplitude-shift keying-16384

quiet_modulation_qask32768

quadrature amplitude-shift keying-32768

quiet_modulation_qask65536

quadrature amplitude-shift keying-65536

quiet_modulation_apsk4

amplitude phase-shift keying-4

quiet_modulation_apsk8

amplitude phase-shift keying-8

quiet_modulation_apsk16

amplitude phase-shift keying-16

quiet_modulation_apsk32

amplitude phase-shift keying-32

quiet_modulation_apsk64

amplitude phase-shift keying-64

quiet_modulation_apsk128

amplitude phase-shift keying-128

quiet_modulation_apsk256

amplitude phase-shift keying-256

quiet_modulation_bpsk

binary phase-shift keying

quiet_modulation_qpsk

quaternary phase-shift keying

quiet_modulation_ook

on-off keying

quiet_modulation_sqask32

square quadrature amplitude-shift keying-32

quiet_modulation_sqask128

square quadrature amplitude-shift keying-128

quiet_modulation_v29

V.29 star constellation.

quiet_modulation_opt_qask16

optimal quadrature amplitude-shift keying-16

quiet_modulation_opt_qask32

optimal quadrature amplitude-shift keying-32

quiet_modulation_opt_qask64

optimal quadrature amplitude-shift keying-64

quiet_modulation_opt_qask128

optimal quadrature amplitude-shift keying-128

quiet_modulation_opt_qask256

optimal quadrature amplitude-shift keying-256

quiet_modulation_vtech

Virginia Tech logo constellation.

quiet_dc_filter_options

typedef struct {

    float alpha;

} quiet_dc_filter_options;

This DC blocker is applied near the end of the signal chain so that any leftover DC component is removed. This is important for audio signals as we do not want to send any DC out to speakers

transfer function H(z)=(1 - (z^-1))/(1 - (1-alpha)*(z^-1))

alpha

quiet_resampler_options

typedef struct {

    size_t delay;

    float bandwidth;

    float attenuation;

    size_t filter_bank_size;

} quiet_resampler_options;

Controls arbitrary resample unit used by libquiet after generating 44.1kHz signal or before decoding signal

This resampler will be applied to set the sample rate to the rate given when creating an encoder or decoder

delay

bandwidth

attenuation

filter_bank_size