Installation

Prerequisites

gr-apollo requires Python 3.10+ and uses uv for dependency management. GNU Radio is only needed if you want to use the GR block wrappers.

Dependency	Required for	Install
Python 3.10+	Everything	System package manager
uv	Dependency management	curl -LsSf https://astral.sh/uv/install.sh | sh
NumPy	Signal processing	Installed automatically
GNU Radio 3.10+	GR blocks only	System package manager

Install gr-apollo

1. Clone the repository

   git clone https://git.supported.systems/rf/gr-apollo.git
   cd gr-apollo

2. Create a virtual environment and install

   Without GNU Radio

   This installs the pure-Python engines (signal generator, frame sync, demux, AGC bridge). No GNU Radio dependency.

   uv venv
   uv pip install -e ".[dev]"

   With GNU Radio

   GNU Radio installs Python bindings as system packages. To access them from a virtualenv, use --system-site-packages:

   uv venv --system-site-packages
   uv pip install -e ".[dev]"

   This lets the virtualenv see gnuradio, pmt, and other system-installed GR modules while still isolating gr-apollo’s own dependencies.

3. Install GRC block definitions (optional, for GNU Radio Companion)

   Copy the YAML block descriptions so GRC can find them:

   mkdir -p ~/.local/share/gnuradio/grc/blocks/
   cp grc/*.yml ~/.local/share/gnuradio/grc/blocks/

   This installs 12 block definitions: PM demod, subcarrier extract, BPSK demod, frame sync, demux, downlink decoder, voice demod, SCO demod, AGC bridge, uplink encoder, and the all-in-one usb_downlink_receiver.

Verify the installation

Pure-Python engines

These should work regardless of whether GNU Radio is installed:

python -c "import apollo; print(f'gr-apollo v{apollo.__version__}')"

Expected output:

gr-apollo v0.1.0

Test the signal generator and frame sync engine:

python -c "
from apollo import generate_usb_baseband, FrameSyncEngine
signal, bits = generate_usb_baseband(frames=1)
print(f'Generated {len(signal)} samples, {len(bits[0])} bits/frame')
engine = FrameSyncEngine()
frames = engine.process_bits(bits[0])
print(f'Frame sync: {len(frames)} frame(s), state={engine.state_name}')
"

Expected output:

Generated 102400 samples, 1024 bits/frame
Frame sync: 1 frame(s), state=VERIFY

GNU Radio blocks

If you installed with --system-site-packages:

python -c "
from apollo import pm_demod, bpsk_demod, pcm_frame_sync
from apollo.usb_downlink_receiver import usb_downlink_receiver
print('All GR blocks imported successfully')
"

Caution

If you see ImportError: No module named 'gnuradio', make sure you created the virtualenv with --system-site-packages and that GNU Radio’s Python bindings are installed system-wide. On Arch Linux: sudo pacman -S gnuradio. On Ubuntu/Debian: sudo apt install gnuradio python3-gnuradio.

GRC blocks

Open GNU Radio Companion and search for “apollo” in the block list. You should see blocks prefixed with Apollo:

gnuradio-companion

If the blocks do not appear, verify the YAML files are in the right location:

ls ~/.local/share/gnuradio/grc/blocks/apollo_*.yml

You should see 12 files. If the directory was wrong for your GR installation, check where GRC looks for blocks:

/usr/share/gnuradio/grc/blocks/

gnuradio-config-info --prefix
# Blocks may also live under:
#   /usr/local/share/gnuradio/grc/blocks/

Troubleshooting

ModuleNotFoundError: No module named 'apollo'

You are running Python outside the virtualenv. Either activate it (source .venv/bin/activate) or use uv run:

uv run python -c "import apollo; print(apollo.__version__)"

ImportError: No module named 'gnuradio'

The virtualenv cannot see GNU Radio’s system packages. Recreate with system site access:

rm -rf .venv
uv venv --system-site-packages
uv pip install -e ".[dev]"

GRC blocks not visible

GRC only scans certain directories for block YAML files. If ~/.local/share/gnuradio/grc/blocks/ is not picked up, try the system-wide path:

sudo cp grc/*.yml /usr/share/gnuradio/grc/blocks/

Then restart GNU Radio Companion.

NumPy version conflicts

If GNU Radio was built against a specific NumPy version, you may see warnings or errors. Pin to the system NumPy:

uv pip install --force-reinstall numpy==$(python -c "import numpy; print(numpy.__version__)")

Next step

Quick Start Generate a synthetic signal and decode your first telemetry frame.