Skip to content

README.md

Latest commit

 

History

History
123 lines (93 loc) · 3.75 KB

README.md

File metadata and controls

123 lines (93 loc) · 3.75 KB

esp32-afsk

ESP32 AFSK modem helper library for Arduino.

Performance Notes

  • The demodulator uses esp-dsp FIR/DSP routines for best performance.
  • Good real-time performance is expected on ESP32-class targets, especially:
    • ESP32
    • ESP32-S3
  • Other targets/build environments may work functionally but can show different throughput.

Install

Use PlatformIO Library Manager or add as a Git dependency.

Usage

See examples/basic/basic.ino.

Common usage patterns:

  • Demodulate int16_t PCM chunks (e.g. ADC/I2S input):
#include "AfskDemodulator.h"

static void onPacket(const uint8_t *frame, size_t len) {
  // handle AX.25 payload
}

AfskDemodulator demod(48000, 2, onPacket);

// call for each incoming chunk
demod.processSamples(samples_i16, sample_count);

// call at end of stream / mode switch
demod.flush();
  • Demodulate float samples:
AfskDemodulator demod(48000, 1, onPacket);
demod.processSamples(samples_f32, sample_count);
demod.flush();
  • Modulate packets to audio via callback:
#include "AfskModulator.h"

static void onTxSamples(const float *samples, size_t count) {
  // send to DAC / I2S
}

AfskModulator mod(48000, onTxSamples);
float chunk[256];
mod.modulate(payload, payload_len, chunk, 256);

  • chunk is a caller-provided scratch/output buffer.

  • The modulator fills this buffer with PCM float samples in blocks.

  • When a block is ready (or a final partial block remains), it invokes onTxSamples(samples, count).

  • The callback must consume/copy samples immediately if it needs them later.

  • Modulate with lead/tail silence (PTT friendly):

mod.modulate(payload, payload_len, chunk, 256, 1000.0f, 1000.0f);
  • Stream-style single-sample demod (less efficient, useful for harnesses):
demod.processSample(sample_f32);

See also:

  • examples/basic/basic.ino
  • examples/kiss_tnc/src/main.cpp
    • Simple KISS TNC terminal example for KV4P-style hardware wiring/pinout (SA818/DRA818 + ESP32 audio/PTT switching).

Testing

Native decoder tests:

  • pio test -e native

ESP32 embedded benchmark test (requires board connected):

  • pio test -e esp32dev -v
    • The test runs an embedded 20s audio clip that is compiled into flash as a int16_t PCM array in test/test_demodulator_esp32/embedded_audio.h.
    • The clip is derived from test/fixtures/01_40-Mins-Traffic-on-144.39.flac, trimmed to 20s, resampled to 48 kHz mono, and converted to raw PCM before being converted into the header.
    • During the test, the decoder processes the entire embedded clip and reports:
      • packets: number of deduplicated frames decoded
      • decode_sec: CPU time spent in the decode loop (seconds)
      • audio_sec: clip duration (seconds)
      • rt_factor: audio_sec / decode_sec (values > 1.0 mean faster than real time)
      • cpu_pct: decode_sec / audio_sec * 100 (values < 100% mean real-time or better)
    • The test currently asserts packets == 13 for all decimation factors, with per-decim CPU limits.

Current metrics (latest run):

  • Native decoder packet counts:
Decim Track 1 (01_40-Mins-Traffic-on-144.39.flac) Track 2 (02_100-Mic-E-Bursts-DE-emphasized.flac)
1 1005 947
2 1005 946
3 1005 945
4 1000 948
Decim CPU usage
1 17.96%
2 9.58%
3 6.70%
4 5.50%
  • Measurement method:
    • The benchmark measures wall-clock time spent inside the decode loop (decode_sec) for a fixed embedded clip.
    • audio_sec is the real-time duration of that clip.
    • cpu_pct = (decode_sec / audio_sec) * 100.

If you only want to build (no upload), add --without-uploading.