File acq_core.h¶

FileList > acq > acq_core.h

Go to the source code of this file

Streaming DSSS burst-acquisition engine. More...

• #include "buffer/buffer.h"
• #include "clib_common.h"
• #include "dp_state.h"
• #include "corr2d/corr2d_core.h"
• #include "detection/detection_core.h"
• #include "fft/fft_core.h"
• #include "jm_perf.h"
• #include "detector2d/detector2d_core.h"
• #include "fft2d/fft2d_core.h"

Classes¶

Public Functions¶

Macros¶

Detailed Description¶

Acquires a direct-sequence spread-spectrum burst — a run of repeated, BPSK-modulated PN-code segments — arriving with an unknown integer code phase and an unknown carrier-frequency (Doppler) offset, buried in AWGN. It jointly estimates the (Doppler bin, code phase) of the burst and declares a detection whenever the CFAR test statistic crosses an automatically configured threshold.

Pipeline (owned end to end, one object): push(raw cf32) -> ring buffer -> reframe to (doppler_bins, code_bins) -> slow-time Doppler FFT (FFT along the segment axis) -> 2-D code correlation against a single-row PN reference (corr2d) -> argmax + CFAR noise estimate -> threshold gate -> acq_result_t.

The fast-time axis (code_bins = sf*spc columns) is the circular code matched filter; the slow-time axis (doppler_bins rows, one row per code repetition) is the Doppler search. A carrier offset f (cycles/sample) lands the peak at row = round(f*code_bins*doppler_bins) mod doppler_bins, column = code phase.

Physics-only construction: the user gives the PN code, the front-end geometry (reps, spc, chip_rate), the sensitivity (cn0_dbhz), and the detection targets (pfa, pd, optional doppler_uncertainty). The engine converts C/N0 to a per-sample amplitude SNR (snr = sqrt(10^(cn0_dbhz/10) / (chip_rate*spc))) and picks the smallest coherent depth doppler_bins in [1, reps] whose doppler_bins*code_bins coherent samples meet pd (det_threshold / det_pd) — minimum latency for a strong signal. A tighter doppler_uncertainty shrinks the searched cell count, lowering the Bonferroni threshold (more sensitive).

// 31-chip PN, 4x oversample, up to 16 coherent reps; 1 MHz chips, 45 dB-Hz
uint8_t code[31] = { 0 };   // ... fill with PN chips (0/1) ...
acq_state_t *a = acq_create(code, 31, 16, 4, 1.0e6, 45.0,
                            0.0, 1e-3, 0.9, 0, 1);
acq_result_t hits[64];
size_t nh = acq_push(a, samples, n_samples, hits, 64);
for (size_t i = 0; i < nh; i++)
  printf("Doppler %zu, code phase %zu, SNR %.2f\n",
         hits[i].doppler_bin, hits[i].code_phase, hits[i].snr_est);
acq_destroy(a);

Public Functions Documentation¶

function acq_create¶

Create a streaming DSSS acquisition engine.

acq_state_t * acq_create (
    const uint8_t * code,
    size_t code_len,
    size_t reps,
    size_t spc,
    double chip_rate,
    double cn0_dbhz,
    double doppler_uncertainty,
    double pfa,
    double pd,
    int noise_mode,
    size_t max_noncoh
) 

Builds the single-row oversampled BPSK reference from code, infers sf = code_len, converts cn0_dbhz to a per-sample amplitude SNR (snr = sqrt(10^(cn0_dbhz/10) / (chip_rate*spc))), and auto-configures the search grid: the smallest coherent depth doppler_bins in [1, reps] whose doppler_bins*code_bins coherent samples meet pd at the Bonferroni threshold, plus non-coherent looks (up to max_noncoh) if the coherent depth alone falls short. A tighter doppler_uncertainty narrows the scanned Doppler band, lowering the per-cell threshold (more sensitive).

Parameters:

• code PN chips (0/1), length code_len.
• code_len Number of chips supplied (= sf, the spreading factor).
• reps Max coherent code repetitions, the coherence ceiling (>=1).
• spc Samples per chip (>= 1).
• chip_rate Chip rate in Hz (> 0).
• cn0_dbhz Carrier-to-noise density in dB-Hz (> 0).
• doppler_uncertainty One-sided Doppler search half-range in Hz; 0 uses the full native span +/- chip_rate/(2*sf). Must be <= span.
• pfa Target system (max-of-N) false-alarm probability (0,1).
• pd Target detection probability (0,1).
• noise_mode CFAR mode index: 0=mean, 1=median, 2=min, 3=max.
• max_noncoh Cap on the auto-split non-coherent look count (>= 1; default 1 keeps the engine purely coherent).

Returns:

Heap-allocated state, or NULL on bad arguments / allocation failure.

function acq_destroy¶

Destroy and free an engine.

void acq_destroy (
    acq_state_t * state
) 

Parameters:

• state May be NULL.

function acq_get_state¶

Serialize state's cross-call state intoblob (caller-owned,acq_state_bytes() long). Call between pushes (no partial dump pending).

void acq_get_state (
    const acq_state_t * state,
    void * blob
) 

function acq_push¶

Stream raw samples; emit one event per CFAR dump above threshold.

size_t acq_push (
    acq_state_t * state,
    const float complex * in,
    size_t n_in,
    acq_result_t * result,
    size_t max_results
) 

Buffers in, then for every complete frame applies the slow-time Doppler FFT, correlates against the PN reference, dumps the coherent surface (or, when n_noncoh > 1, accumulates |·|² over n_noncoh looks first), gates the peak on the auto-configured threshold, and appends an acq_result_t.

Parameters:

• state Allocated engine (non-NULL).
• in Raw input, interleaved CF32, n_in complex samples.
• n_in Number of complex input samples.
• result Output array for detection events.
• max_results Capacity of result.

Returns:

Number of events written (0 … max_results).

function acq_reset¶

Drain the input ring and reset the coherent accumulator.

void acq_reset (
    acq_state_t * state
) 

Parameters:

• state Must be non-NULL.

function acq_run¶

Pure run: inject state_in , streamin , emit hits, exportstate_out —(state_in, input) -> (state_out, output) over an engine treated as immutable config + scratch.state_in /state_out may alias. Either may be NULL (NULL in = fresh; NULL out = discard).

size_t acq_run (
    acq_state_t * state,
    const void * state_in,
    void * state_out,
    const float complex * in,
    size_t n_in,
    acq_result_t * result,
    size_t max_results
) 

Returns:

Number of events written (0 … max_results).

function acq_set_state¶

Restore cross-call state from blob intostate (replacing it).

int acq_set_state (
    acq_state_t * state,
    const void * blob
) 

Returns:

0 on success, -1 if the blob's magic/version/n/n_noncoh disagree with state (rebuild the engine from the matching descriptor first).

function acq_state_bytes¶

Byte size of state's blob (header + unconsumed + nc).

size_t acq_state_bytes (
    const acq_state_t * state
) 

Macro Definition Documentation¶

define ACQ_STATE_MAGIC¶

#define ACQ_STATE_MAGIC `DP_FOURCC ('A', 'C', 'Q', 'R')`

define ACQ_STATE_VERSION¶

#define ACQ_STATE_VERSION `1u`

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