From 425a6357ccb16a8021d280eeb71d625a3ff71d0d Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Fri, 20 Feb 2026 10:46:43 -0700
Subject: [PATCH] init: Apollo Unified S-Band decoder for GNU Radio 3.10+

Project scaffold for decoding Apollo USB signals:
- 2287.5 MHz downlink with PM/FM modulation
- 1.024 MHz BPSK subcarrier (PCM telemetry)
- 1.25 MHz FM subcarrier (voice)
- 128-word PCM frames at 50 fps

Based on NAA Course A-624 Study Guide (1965) and Virtual AGC.
---
 README.md              | 82 ++++++++++++++++++++++++++++++++++++++++++
 pyproject.toml         | 33 +++++++++++++++++
 src/apollo/__init__.py | 18 ++++++++++
 3 files changed, 133 insertions(+)
 create mode 100644 README.md
 create mode 100644 pyproject.toml
 create mode 100644 src/apollo/__init__.py

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37341c9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# gr-apollo
+
+GNU Radio 3.10+ out-of-tree module for decoding **Apollo Unified S-Band (USB)** telecommunications signals.
+
+## Overview
+
+The Apollo Unified S-Band system was the primary communication link between the spacecraft and Earth during the Apollo missions (1967-1972). This module implements GNU Radio blocks to decode these signals, enabling:
+
+- Reception of Apollo-era recordings
+- Integration with the [Virtual AGC](https://www.ibiblio.org/apollo/) emulator
+- Educational exploration of 1960s space communications
+
+## Signal Specifications
+
+| Parameter | Value |
+|-----------|-------|
+| Downlink Frequency | 2287.5 MHz |
+| Uplink Frequency | 2106.40625 MHz |
+| Coherent Ratio | 240/221 |
+| PM Peak Deviation | 0.133 rad (7.6°) |
+| PCM Subcarrier | 1.024 MHz BPSK |
+| PCM Bit Rate | 51.2 kbps (high) / 1.6 kbps (low) |
+| Voice Subcarrier | 1.25 MHz FM |
+| Frame Length | 128 words × 8 bits @ 50 fps |
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv pip install -e .
+
+# Install GRC blocks
+cp grc/*.yml ~/.local/share/gnuradio/grc/blocks/
+```
+
+## Signal Chain
+
+```
+RF 2287.5 MHz
+     │
+     ▼
+┌─────────────┐
+│ Carrier PLL │ ◄── 240/221 coherent recovery
+└─────────────┘
+     │
+     ▼
+┌─────────────┐
+│  PM Demod   │ ◄── 0.133 rad peak deviation
+└─────────────┘
+     │
+     ├────────────────────┬──────────────────┐
+     ▼                    ▼                  ▼
+┌──────────┐        ┌──────────┐       ┌──────────┐
+│ 1.024MHz │        │ 1.25 MHz │       │ Ranging  │
+│   BPSK   │        │    FM    │       │   PRN    │
+└──────────┘        └──────────┘       └──────────┘
+     │                    │
+     ▼                    ▼
+┌──────────┐        ┌──────────┐
+│ PCM Sync │        │  Voice   │
+│ 51.2kbps │        │ 300-3kHz │
+└──────────┘        └──────────┘
+     │
+     ▼
+┌──────────┐
+│ 128-word │
+│  Demux   │
+└──────────┘
+     │
+     ▼
+  Telemetry
+```
+
+## References
+
+- [Virtual AGC Project](https://www.ibiblio.org/apollo/)
+- [NASA Technical Reports](https://ntrs.nasa.gov/)
+- NAA Course A-624: Telecommunication Systems Study Guide (1965)
+
+## License
+
+MIT
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..dc397f6
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,33 @@
+[project]
+name = "gr-apollo"
+version = "0.1.0"
+description = "Apollo Unified S-Band (USB) decoder for GNU Radio 3.10+"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "Ryan Malloy", email = "ryan@supported.systems"},
+]
+keywords = ["gnuradio", "sdr", "apollo", "usb", "unified-s-band", "nasa", "space"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Ham Radio",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+
+dependencies = [
+    "numpy",
+]
+
+[project.urls]
+"Homepage" = "https://git.supported.systems/rf/gr-apollo"
+"Virtual AGC" = "https://www.ibiblio.org/apollo/"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
diff --git a/src/apollo/__init__.py b/src/apollo/__init__.py
new file mode 100644
index 0000000..26413e0
--- /dev/null
+++ b/src/apollo/__init__.py
@@ -0,0 +1,18 @@
+"""
+gr-apollo: Apollo Unified S-Band decoder for GNU Radio 3.10+
+
+Decodes Apollo-era Unified S-Band (USB) telecommunications:
+- 2287.5 MHz downlink with PM/FM modulation
+- 1.024 MHz BPSK subcarrier (PCM telemetry @ 51.2 kbps)
+- 1.25 MHz FM subcarrier (voice)
+- 128-word PCM frames at 50 fps
+"""
+
+__version__ = "0.1.0"
+
+# Block imports will be added as they are implemented
+# from .pm_demod import pm_demod
+# from .bpsk_subcarrier_demod import bpsk_subcarrier_demod
+# from .pcm_frame_sync import pcm_frame_sync
+# from .pcm_demux import pcm_demux
+# from .fm_voice_demod import fm_voice_demod