File wfm_writer.h¶

FileList > inc > wfm > wfm_writer.h

Go to the source code of this file

Output containers for generated IQ: raw / csv / BLUE-1000 + SigMF meta. More...

• #include <stdio.h>
• #include "clib_common.h"
• #include "wfm/wfm_compose.h"

Public Types¶

Public Functions¶

Detailed Description¶

A streaming writer over a FILE* that serialises cf32 blocks into one of three on-disk containers, in the chosen wire sample type and byte order. The fourth file-type, SigMF, writes its samples as raw (into <base>.sigmf-data) and pairs with a sidecar <base>.sigmf-meta JSON emitted by wfm_sigmf_meta_json().

Axes (orthogonal to the container): * sample_type (wavegen order): 0 cf32, 1 cf64, 2 ci32, 3 ci16, 4 ci8. Integer types quantise full-scale ±1.0 (ci32 2^31-1, ci16 32767, ci8 127). * endian: 0 little, 1 big (csv is text, so endian is ignored there).

wfm_writer_t *w = wfm_writer_open(fp, WFM_FT_BLUE, 3, 0, 1e6, 2.4e9, 4096);
wfm_writer_write(w, iq, 4096);
wfm_writer_close(w);   // patches the BLUE data_size from the actual count

Public Types Documentation¶

enum wfm_filetype_t¶

enum wfm_filetype_t {
    WFM_FT_RAW = 0,
    WFM_FT_CSV = 1,
    WFM_FT_BLUE = 2,
    WFM_FT_SIGMF = 3
};

Output container.

typedef wfm_writer_t¶

typedef struct wfm_writer wfm_writer_t;

Opaque writer.

Public Functions Documentation¶

function wfm_blue_write_hcb¶

Write a complete 512-byte BLUE/Platinum type-1000 Header Control Block.

int wfm_blue_write_hcb (
    FILE * fp,
    int sample_type,
    int endian,
    double fs,
    double fc,
    double data_start,
    size_t total_samples,
    int detached
) 

Used for the blue container — both attached (the writer calls this with data_start = 512, detached = 0, then streams the data after it) and detached (the caller writes the data to a separate .det file and this HCB to a .hdr file with data_start = 0, detached = 1). Every standard field is written; the header byte order follows endian.

Parameters:

• fp destination (binary).
• sample_type wire type (wavegen order) → BLUE format char C{B,I,L,F,D}.
• endian 0 little (EEEI) / 1 big (IEEE).
• fs sample rate (Hz) → xdelta = 1/fs.
• fc reserved (no standard type-1000 field).
• data_start data_start field: 512 attached, 0 detached.
• total_samples complex-sample count → data_size.
• detached non-zero sets the HCB detached flag.

Returns:

0 on success, non-zero on a write error.

function wfm_sigmf_meta_json¶

Build a SigMF .sigmf-meta JSON document for a generated capture.

char * wfm_sigmf_meta_json (
    int sample_type,
    int endian,
    double fs,
    double fc,
    const wfm_segment_t * segs,
    size_t n_segs
) 

global carries core:datatype (from sample_type+endian, e.g. "ci16_le"), core:sample_rate, core:version "1.0.0", and a wfmgen description/author. captures is a single capture at sample 0 / frequency fc. annotations has one entry per composer segment — sample span, frequency edges (fc + freq ± bandwidth/2, bandwidth ≈ fs/sps for symbol/chip types), a core:label of the waveform type, and custom wfmgen:* parameters.

Returns:

malloc'd JSON string (caller frees), or NULL on allocation failure.

function wfm_writer_clip_fraction¶

double wfm_writer_clip_fraction (
    const wfm_writer_t * w
) 

Fraction (0..1) of I/Q components that saturated (|v| > 1). Always 0 unless wfm_writer_track_clipping() was enabled.

function wfm_writer_close¶

Flush, patch the BLUE data_size from the actual count (if seekable), and free the writer (does not close the FILE*).

int wfm_writer_close (
    wfm_writer_t * w
) 

Returns:

0 on success, non-zero on a write/seek error.

function wfm_writer_open¶

Open a writer on an already-open stream.

wfm_writer_t * wfm_writer_open (
    FILE * fp,
    wfm_filetype_t ft,
    int sample_type,
    int endian,
    double fs,
    double fc,
    size_t total_samples
) 

Parameters:

• fp destination (binary mode for raw/blue; text-safe for csv).
• ft container; SIGMF is treated as RAW here.
• sample_type wire type (wavegen order); see file header.
• endian 0 little, 1 big (ignored for csv).
• fs sample rate (Hz) — BLUE xdelta = 1/fs.
• fc center frequency (Hz) — reserved (BLUE/raw ignore it).
• total_samples expected complex-sample count for the BLUE header (0 if unknown; close() patches the actual count when fp is seekable).

Returns:

Writer handle, or NULL on bad args / allocation. BLUE writes its 512-byte header here.

function wfm_writer_open_path¶

wfm_writer_t * wfm_writer_open_path (
    const char * path,
    wfm_filetype_t ft,
    int sample_type,
    int endian,
    double fs,
    double fc,
    size_t total_samples,
    double headroom
) 

Path-opening + FILE-owning ctor for the generated Writer handle (jm kind="handle"): opens path ("wb"), delegates to wfm_writer_open, and marks the FILE owned so wfm_writer_close fclose's it. Returns NULL on open failure.

function wfm_writer_peak¶

double wfm_writer_peak (
    const wfm_writer_t * w
) 

Largest per-axis magnitude max(|I|,|Q|) written so far (pre-clip, full-scale 1.0). > 1.0 ⇒ integer output clipped; peak_dBFS = 20*log10(peak).

function wfm_writer_set_gain¶

void wfm_writer_set_gain (
    wfm_writer_t * w,
    double gain
) 

Set the output gain (linear; default 1.0). For headroom H dB pass 10^(−H/20).

function wfm_writer_track_clipping¶

void wfm_writer_track_clipping (
    wfm_writer_t * w,
    int on
) 

Enable the per-component clip counter (off by default; peak is always on).

function wfm_writer_write¶

Convert and write n complex samples.

size_t wfm_writer_write (
    wfm_writer_t * w,
    const float _Complex * iq,
    size_t n
) 

Returns:

Number of complex samples written (== n on success, else short).

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