How marinmikael/satnogs-ogg-decoders works
Project type and purpose
• This is an open-source, command-line satellite-telemetry audio decoder.
• It provides a set of GNU Radio flowgraphs (.grc), Python scripts, and shell wrappers to take OGG audio files (captured by the SatNOGS network) and decode them into AX.25 or raw data.
File structure
• Top level
• LICENSE, README.md – legal and overview
• decoders/ – the heart of the tool
• examples/ – sample inputs (OGG) and outputs (decoded)
• decoders/
• .grc files – GNU Radio Companion flowcharts for different modulations (BPSK, GMSK)
• .py scripts – wrappers that launch the flowgraphs and post-process their output
• .sh scripts – batch runners (decode_all_ogg.sh, watch.sh)
• print_ax25.py – takes raw demodulated binary and formats AX.25 frames
• examples/
• Two ground-station scenarios (kafasat, randev) each with a subfolder of .ogg files (satnogs_*.ogg) and a decoded/ folder containing results.
Key insights from README.md
• “A set of satnogs flowcharts to decode OGG files from Satnogs’ website”
• Derived from “satnogs-flowgraphs” – it leverages the existing GNURadio ecosystem.
a. Main components
• External Service (SatNOGS website / API)
• Local Storage: raw OGG files
• Orchestration Scripts (decode_all_ogg.sh, watch.sh)
• GNU Radio flowgraphs (ogg_bpsk_decoder.grc, ogg_gmsk_decoder.grc)
• Python Post-Processors (ogg_*.py, print_ax25.py)
• Output Repositories (decoded/ directories)
b. Relationships & data flows
1. External Service → Local Storage: OGG files are downloaded or placed in examples/satnogs_ogg.
2. Orchestration Script → Flowgraph Launcher: decode_all_ogg.sh iterates over each OGG, invokes the appropriate ogg_*.py.
3. Flowgraph → GNURadio Engine: .py script loads the .grc, performs demodulation → produces bitstream or raw frames.
4. Post-Processor → Parsed Output: print_ax25.py formats raw bits into readable AX.25 frames.
5. Post-Processor → Local Storage: outputs land in examples/.../decoded.
c. Architectural patterns & design principles
• Pipeline / Unix-style chaining: small specialized components glued by shell scripts
• Separation of concerns: .grc for signal processing, .py for orchestration & parsing, .sh for batch control
• Extensibility: drop a new .grc+wrapper in decoders/ to support additional modulation schemes
d. Technologies & libraries
• GNU Radio (flowgraphs)
• Python (wrappers, AX.25 packet handling)
• Bash shell (batch orchestration)
• SatNOGS network (source of OGG audio)