You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

208 lines
10 KiB

/* SPDX-License-Identifier: MIT
* Copyright (c) 2026 Dan Chokola, KD2HSG
*
* chirpmodem: public C API.
*
* A chirp-spread-spectrum modem for amateur radio and ISM links, on-air
* format v1 (FORMAT.md). This header is everything an application needs:
*
* chirpmodem_tx frames (and a CW ID) as complex samples at any sample
* rate, optionally shifted to an IF; ready for an SDR.
* chirpmodem_rx a streaming receiver: push SDR samples in any common
* format and rate, get a callback for every decoded frame.
*
* Conventions
* - Complex samples are interleaved float32 pairs (I, Q, I, Q, ...), so
* buffers are float[2 * n]. This matches std::complex<float>,
* gr_complex, numpy.complex64 and SDRAngel's float samples. Counts are
* always in complex samples.
* - Functions return >= 0 on success and a negative CHIRPMODEM_E* code on
* error; chirpmodem_strerror() describes it.
* - Handles are independent: different handles may be used from different
* threads at once. One handle must not be used by two threads at once.
* - The library is pure computation: no files, no threads, no globals.
*
* The API is 0.x: it may still change between minor versions.
*/
#ifndef CHIRPMODEM_H
#define CHIRPMODEM_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#if defined(_WIN32) && defined(CHIRPMODEM_SHARED)
# ifdef CHIRPMODEM_BUILDING
# define CHIRPMODEM_API __declspec(dllexport)
# else
# define CHIRPMODEM_API __declspec(dllimport)
# endif
#elif defined(__GNUC__) && __GNUC__ >= 4
# define CHIRPMODEM_API __attribute__((visibility("default")))
#else
# define CHIRPMODEM_API
#endif
#define CHIRPMODEM_VERSION_MAJOR 0
#define CHIRPMODEM_VERSION_MINOR 1
#define CHIRPMODEM_VERSION_PATCH 0
#define CHIRPMODEM_FORMAT_VERSION 1 /* on-air format, FORMAT.md */
/* Library version, "0.1.0" (may differ from the header's if linked dynamically). */
CHIRPMODEM_API const char *chirpmodem_version(void);
/* ------------------------------------------------------------------ errors */
enum {
CHIRPMODEM_OK = 0,
CHIRPMODEM_EINVAL = -1, /* a parameter is out of range */
CHIRPMODEM_ENOMEM = -2,
CHIRPMODEM_EPOLICY = -3, /* the operating profile forbids this frame */
CHIRPMODEM_ETOOLONG = -4, /* body too long for one frame */
CHIRPMODEM_ECALLSIGN = -5, /* callsign not encodable (A-Z 0-9 - / ., <= 9) */
CHIRPMODEM_ESPACE = -6 /* output buffer too small */
};
CHIRPMODEM_API const char *chirpmodem_strerror(int err);
/* ------------------------------------------------------------------ common */
enum { /* operating profile (header field) */
CHIRPMODEM_LICENSED = 0, /* amateur: source callsign required, no encryption */
CHIRPMODEM_UNLICENSED = 1 /* ISM: neither rule */
};
enum { /* payload mode in configs */
CHIRPMODEM_MODE_AUTO = -1, /* non-coherent at SF >= 10 or BW <= 62.5 kHz */
CHIRPMODEM_MODE_NONCOHERENT = 0,
CHIRPMODEM_MODE_COHERENT = 1
};
typedef enum { /* input sample formats (SigMF names) */
CHIRPMODEM_CU8 = 0, /* uint8 pairs, centre 127.5 (rtl_sdr) */
CHIRPMODEM_CI8 = 1, /* int8 pairs, full scale 128 (HackRF) */
CHIRPMODEM_CI16 = 2, /* int16 little-endian pairs, full scale 32768 (Pluto) */
CHIRPMODEM_CF32 = 3 /* float32 pairs, full scale 1.0 */
} chirpmodem_format;
#define CHIRPMODEM_MAX_MAC 2047 /* MAC frame bytes: flags + callsigns + body */
/* Largest body that fits one frame with the given callsigns (NULL = none). */
CHIRPMODEM_API int chirpmodem_max_body(const char *src, const char *dst);
/* The payload mode CHIRPMODEM_MODE_AUTO picks for these parameters (0 or 1). */
CHIRPMODEM_API int chirpmodem_default_coherent(int sf, double bw);
/* Seconds on air of one frame (without fades or gaps). */
CHIRPMODEM_API double chirpmodem_frame_seconds(int sf, double bw, int mac_len, int coherent);
/* ------------------------------------------------------------------ transmit */
typedef struct {
int sf; /* spreading factor 7..12 [9] */
double bw; /* chip rate = occupied bandwidth, Hz [62500] */
double fs; /* output sample rate, Hz; 0 = 2 * bw (modem rate) [0] */
double if_offset; /* signal centre relative to 0 Hz of the output [0] */
int coherent; /* CHIRPMODEM_MODE_* [AUTO] */
int profile; /* CHIRPMODEM_LICENSED / UNLICENSED [LICENSED] */
double amp; /* peak amplitude, 0..1 of full scale [0.7] */
} chirpmodem_tx_config;
typedef struct chirpmodem_tx chirpmodem_tx;
CHIRPMODEM_API void chirpmodem_tx_config_init(chirpmodem_tx_config *cfg); /* the [defaults] */
/* NULL on error, with *err (if given) set. */
CHIRPMODEM_API chirpmodem_tx *chirpmodem_tx_new(const chirpmodem_tx_config *cfg, int *err);
CHIRPMODEM_API void chirpmodem_tx_free(chirpmodem_tx *tx);
/* One frame: MAC frame (callsigns + body) -> samples at fs with
* raised-cosine edges. src/dst may be NULL; the licensed profile requires
* src and forbids encrypted. Writes up to cap samples to iq (float[2*cap])
* and returns the number written; with iq == NULL returns the number needed.
* Each call starts the IF oscillator at phase 0. */
CHIRPMODEM_API long chirpmodem_tx_frame(chirpmodem_tx *tx, const char *src, const char *dst,
const uint8_t *body, int body_len, int encrypted,
float *iq, long cap);
/* Station identification "DE <call>" in Morse at the signal centre
* (47 CFR 97.119(b)(1): CW at no more than 20 WPM). Same buffer
* convention as chirpmodem_tx_frame. wpm 0 = 20. */
CHIRPMODEM_API long chirpmodem_tx_cw_id(chirpmodem_tx *tx, const char *call, double wpm,
float *iq, long cap);
/* The payload mode this transmitter uses (resolves MODE_AUTO), and its rate. */
CHIRPMODEM_API int chirpmodem_tx_coherent(const chirpmodem_tx *tx);
CHIRPMODEM_API double chirpmodem_tx_fs(const chirpmodem_tx *tx);
/* ------------------------------------------------------------------ receive */
enum { /* chirpmodem_frame.status */
CHIRPMODEM_FRAME_OK = 0,
CHIRPMODEM_FRAME_HEADER_FAIL = 1, /* preamble found, header did not decode */
CHIRPMODEM_FRAME_PAYLOAD_FAIL = 2 /* header decoded, payload did not */
};
typedef struct {
int status; /* CHIRPMODEM_FRAME_* */
double t; /* frame start, s from the first sample pushed */
double snr_db; /* in the signal bandwidth */
double offset_hz; /* carrier offset (both radios' crystals) */
double offset_ppm; /* offset_hz relative to the configured freq */
/* the rest is valid when status is OK (header fields also for PAYLOAD_FAIL) */
int profile; /* CHIRPMODEM_LICENSED / UNLICENSED */
int coherent, encrypted;
int policy_ok; /* 0: a licensed frame without source or with encryption */
int ramp_retry; /* carrier drift was removed ... */
double ramp_hz_per_s; /* ... at this rate */
int drift_retry; /* the sample clock was re-estimated ... */
double clock_ppm; /* ... to this error */
int dd_passes; /* decision-directed re-estimation passes */
char src[10], dst[10]; /* "" if absent */
const uint8_t *body; /* valid only during the callback */
int body_len;
const uint8_t *mac; /* the whole MAC frame, valid only during the callback */
int mac_len;
} chirpmodem_frame;
typedef void (*chirpmodem_frame_cb)(void *user, const chirpmodem_frame *frame);
typedef void (*chirpmodem_log_cb)(void *user, const char *message);
typedef struct {
int sf; /* 7..12 [9] */
double bw; /* Hz [62500] */
double fs; /* input sample rate, Hz [1e6] */
double if_offset; /* signal centre minus the input's 0 Hz, Hz [250e3] */
double freq; /* signal centre, Hz: reports ppm, ties CFO to the
sample clock [223.58e6] */
int max_bytes; /* longest MAC frame to wait for [255] */
int effort; /* 0..2: retries per frame (2 = all) [2] */
int auto_effort; /* lower effort while decoding lags real time [0] */
int report_failures; /* also call back for HEADER_FAIL / PAYLOAD_FAIL [0] */
chirpmodem_frame_cb on_frame; /* required */
chirpmodem_log_cb on_log; /* optional: effort changes and similar */
void *user; /* passed to both callbacks */
} chirpmodem_rx_config;
typedef struct {
long frames_ok, frames_failed;
double seconds_in; /* stream time pushed so far */
double cpu_convert, cpu_detect, cpu_decode; /* seconds of processing */
int effort; /* current */
double load; /* recent processing / stream time */
} chirpmodem_rx_stats;
typedef struct chirpmodem_rx chirpmodem_rx;
CHIRPMODEM_API void chirpmodem_rx_config_init(chirpmodem_rx_config *cfg); /* the [defaults] */
CHIRPMODEM_API chirpmodem_rx *chirpmodem_rx_new(const chirpmodem_rx_config *cfg, int *err);
CHIRPMODEM_API void chirpmodem_rx_free(chirpmodem_rx *rx);
/* Push n complex samples of the given format. Callbacks run inside this
* call, for every frame that has completed. Any block size works. */
CHIRPMODEM_API int chirpmodem_rx_push(chirpmodem_rx *rx, const void *samples, long n,
chirpmodem_format fmt);
/* End of stream: decode whatever is pending. A frame cut off by the end of
* the stream is dropped without a callback. */
CHIRPMODEM_API int chirpmodem_rx_finish(chirpmodem_rx *rx);
CHIRPMODEM_API void chirpmodem_rx_get_stats(const chirpmodem_rx *rx, chirpmodem_rx_stats *st);
/* Receiver latency: the FIR group delay already subtracted from frame.t, s. */
CHIRPMODEM_API double chirpmodem_rx_delay(const chirpmodem_rx *rx);
#ifdef __cplusplus
}
#endif
#endif