File despreader_core.h¶

FileList > despreader > despreader_core.h

Go to the source code of this file

Despreader component API. More...

• #include "clib_common.h"
• #include "dp_state.h"
• #include "jm_perf.h"
• #include "loop_filter/loop_filter_core.h"

Classes¶

Public Functions¶

Macros¶

Detailed Description¶

Lifecycle: create -> [step / steps / reset]* -> destroy

Example:

despreader_state_t *obj = despreader_create(NULL, 0, 1, 2, 0.0, 0.0, 0.01, 0.002);
float complex y = despreader_step(obj, 0.0f + 0.0f * I);
despreader_destroy(obj);

Public Functions Documentation¶

function despreader_bits¶

Despread a CF32 block; emit one hard BPSK bit (0/1) per code period.

size_t despreader_bits (
    despreader_state_t * state,
    const float complex * x,
    size_t x_len,
    uint8_t * out,
    size_t max_out
) 

Same streaming kernel as despreader_steps(), but emits the hard decision crealf(prompt) >= 0 instead of the complex symbol.

Parameters:

• state Must be non-NULL.
• x Input CF32 samples, length x_len.
• x_len Number of input samples.
• out Output buffer for bits (>= max_out).
• max_out Capacity of out in bits.

Returns:

Number of bits written.

function despreader_bits_max_out¶

Upper bound on bits despreader_bits can emit (0; see despreader_steps_max_out).

size_t despreader_bits_max_out (
    despreader_state_t * state
) 

function despreader_create¶

Create a despreader instance.

despreader_state_t * despreader_create (
    const uint8_t * code,
    size_t code_len,
    size_t sf,
    size_t sps,
    double init_norm_freq,
    double init_chip_phase,
    double bn_carrier,
    double bn_code
) 

Parameters:

• code Data spreading code (0/1 chips), length code_len; copied.
• code_len Length of code in chips (>= sf).
• sf sf (default: 1).
• sps sps (default: 2).
• init_norm_freq init_norm_freq (default: 0.0).
• init_chip_phase init_chip_phase (default: 0.0).
• bn_carrier bn_carrier (default: 0.01).
• bn_code bn_code (default: 0.002).

Returns:

Heap-allocated state, or NULL on allocation failure.

Note:

Caller must call despreader_destroy() when done.

function despreader_destroy¶

Destroy a despreader instance and release all memory.

void despreader_destroy (
    despreader_state_t * state
) 

Parameters:

• state May be NULL.

function despreader_get_bn_carrier¶

Carrier (Costas) loop noise bandwidth, normalized to the symbol rate.

double despreader_get_bn_carrier (
    const despreader_state_t * state
) 

function despreader_get_bn_code¶

Code (DLL) loop noise bandwidth, normalized to the symbol rate.

double despreader_get_bn_code (
    const despreader_state_t * state
) 

function despreader_get_code_phase¶

Current tracked code phase within the symbol, chips.

double despreader_get_code_phase (
    const despreader_state_t * state
) 

function despreader_get_lock_metric¶

Lock indicator in [0,1] (EMA of |Re prompt|/|prompt|; ~1 = locked).

double despreader_get_lock_metric (
    const despreader_state_t * state
) 

function despreader_get_norm_freq¶

Current carrier frequency estimate, cycles/sample.

double despreader_get_norm_freq (
    const despreader_state_t * state
) 

function despreader_get_snr_est¶

Post-despread SNR estimate (EMA of (Re prompt)^2 / (Im prompt)^2).

double despreader_get_snr_est (
    const despreader_state_t * state
) 

function despreader_get_state¶

void despreader_get_state (
    const despreader_state_t * state,
    void * blob
) 

function despreader_reset¶

Reset Despreader to its post-create state.

void despreader_reset (
    despreader_state_t * state
) 

Parameters:

• state Must be non-NULL.

function despreader_set_acq¶

Enable preamble-aided pull-in with a distinct acquisition code.

void despreader_set_acq (
    despreader_state_t * state,
    const uint8_t * acq_code,
    size_t acq_code_len,
    size_t acq_reps
) 

Track acq_reps periods of acq_code coherently (the unmodulated, repeated acquisition preamble — a full ±pi phase discriminator, so the loops pull in even a wide residual) before switching to the data code for the payload. Call before feeding the burst; the acq mode clears automatically once the preamble is consumed, and re-arms on despreader_reset().

Parameters:

• state Must be non-NULL.
• acq_code Acquisition code (0/1), length acq_code_len; copied.
• acq_code_len Acquisition code length in chips.
• acq_reps Number of acq-code periods in the preamble.

function despreader_set_bn_carrier¶

Set the carrier loop bandwidth (recomputes the loop gains).

void despreader_set_bn_carrier (
    despreader_state_t * state,
    double val
) 

function despreader_set_bn_code¶

Set the code loop bandwidth (recomputes the loop gains).

void despreader_set_bn_code (
    despreader_state_t * state,
    double val
) 

function despreader_set_norm_freq¶

Override the carrier frequency estimate, cycles/sample (re-seed).

void despreader_set_norm_freq (
    despreader_state_t * state,
    double val
) 

function despreader_set_state¶

int despreader_set_state (
    despreader_state_t * state,
    const void * blob
) 

function despreader_state_bytes¶

size_t despreader_state_bytes (
    const despreader_state_t * state
) 

function despreader_steps¶

Despread a CF32 block; emit one complex prompt symbol per code period.

size_t despreader_steps (
    despreader_state_t * state,
    const float complex * x,
    size_t x_len,
    float complex * out,
    size_t max_out
) 

Streams: a partial symbol is carried in state across calls. Each emitted symbol is the complex prompt integrate-and-dump (carrier-wiped, code-stripped) — its sign is the BPSK decision, its phase/magnitude the soft information. During a despreader_set_acq preamble no symbols are emitted (the loops are pulling in); payload symbols follow.

Parameters:

• state Must be non-NULL.
• x Input CF32 samples, length x_len.
• x_len Number of input samples.
• out Output buffer for prompt symbols (>= max_out).
• max_out Capacity of out in symbols.

Returns:

Number of symbols written.

// seed from acquisition (norm_freq cyc/sample, chip phase in chips):
despreader_state_t *d = despreader_create(code, n, 32, 2, f0, chip, .05, .01);
float complex sym[256];
size_t k = despreader_steps(d, rx, rx_len, sym, 256);
// hard bit of sym[i] = crealf(sym[i]) >= 0
despreader_destroy(d);

function despreader_steps_max_out¶

Upper bound on symbols despreader_steps can emit (0; the caller sizes the output buffer to the input length, which always suffices).

size_t despreader_steps_max_out (
    despreader_state_t * state
) 

Macro Definition Documentation¶

define DESPREADER_STATE_MAGIC¶

#define DESPREADER_STATE_MAGIC `DP_FOURCC ('D','S','P','R')`

define DESPREADER_STATE_VERSION¶

#define DESPREADER_STATE_VERSION `1u`

The documentation for this class was generated from the following file native/inc/despreader/despreader_core.h