# marinmikael/satnogs-ogg-decoders architecture

> Architecture diagram of the GitHub repository marinmikael/satnogs-ogg-decoders, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marinmikael/satnogs-ogg-decoders
- Repository: https://github.com/marinmikael/satnogs-ogg-decoders

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Service
    SatNOGS(("SatNOGS Service")):::external

    %% Input Storage
    subgraph "Examples / Input Storage"
        KafaOGG["Kafasat OGG Files"]:::data
        RandOGG["Randev OGG Files"]:::data
    end

    %% Orchestration
    subgraph "Orchestration Scripts" 
        Batch["Batch Decoder\n(foreach satnogs_*.ogg)"]:::code
        Watcher["Watcher Script"]:::code
    end

    %% Decoders
    subgraph "Decoders Directory"
        subgraph "GNU Radio Flowgraphs"
            BPSKFlow["ogg_bpsk_decoder.grc"]:::code
            GMSKFlow["ogg_gmsk_decoder.grc"]:::code
        end
        subgraph "Python Wrappers"
            BPSKPy["ogg_bpsk_decoder.py"]:::code
            GMSKPy["ogg_gmsk_decoder.py"]:::code
        end
        PostProc["print_ax25.py"]:::code
    end

    %% Output Storage
    subgraph "Examples / Decoded Output"
        KafaDec["Kafasat Decoded Results"]:::data
        RandDec["Randev Decoded Results"]:::data
    end

    %% README & License
    Docs["README.md / LICENSE"]:::code

    %% Connections
    SatNOGS -->|"downloads .ogg audio"| KafaOGG
    SatNOGS -->|"downloads .ogg audio"| RandOGG

    KafaOGG -->|".ogg audio"| Batch
    RandOGG -->|" .ogg audio"| Batch
    Batch -->|"launches"| BPSKPy
    Batch -->|"launches"| GMSKPy
    Watcher -->|"monitors folder"| Batch

    BPSKPy -->|"loads flowgraph"| BPSKFlow
    GMSKPy -->|"loads flowgraph"| GMSKFlow

    BPSKFlow -->|"raw bitstream"| PostProc
    GMSKFlow -->|"raw bitstream"| PostProc

    PostProc -->|"AX.25 frames"| KafaDec
    PostProc -->|"AX.25 frames"| RandDec

    Docs --> Batch

    %% Click Events
    click Batch "https://github.com/marinmikael/satnogs-ogg-decoders/blob/main/decoders/decode_all_ogg.sh"
    click Watcher "https://github.com/marinmikael/satnogs-ogg-decoders/blob/main/decoders/watch.sh"
    click BPSKFlow "https://github.com/marinmikael/satnogs-ogg-decoders/blob/main/decoders/ogg_bpsk_decoder.grc"
    click GMSKFlow "https://github.com/marinmikael/satnogs-ogg-decoders/blob/main/decoders/ogg_gmsk_decoder.grc"
    click BPSKPy "https://github.com/marinmikael/satnogs-ogg-decoders/blob/main/decoders/ogg_bpsk_decoder.py"
    click GMSKPy "https://github.com/marinmikael/satnogs-ogg-decoders/blob/main/decoders/ogg_gmsk_decoder.py"
    click PostProc "https://github.com/marinmikael/satnogs-ogg-decoders/blob/main/decoders/print_ax25.py"
    click KafaOGG "https://github.com/marinmikael/satnogs-ogg-decoders/tree/main/examples/kafasat/satnogs_ogg"
    click RandOGG "https://github.com/marinmikael/satnogs-ogg-decoders/tree/main/examples/randev/satnogs_ogg"
    click KafaDec "https://github.com/marinmikael/satnogs-ogg-decoders/tree/main/examples/kafasat/decoded"
    click RandDec "https://github.com/marinmikael/satnogs-ogg-decoders/tree/main/examples/randev/decoded"
    click Docs "https://github.com/marinmikael/satnogs-ogg-decoders/blob/main/README.md"

    %% Styles
    classDef code fill:#D6EAF8,stroke:#3498DB,color:#154360;
    classDef data fill:#D5F5E3,stroke:#2ECC71,color:#145A32;
    classDef external fill:#FADBD8,stroke:#E74C3C,color:#641E16,stroke-dasharray: 5 5;
```
