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
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
|
|
|