Add CLAUDE.md with deployment instructions
This commit is contained in:
parent
15756fa9dd
commit
9f10a8fb69
200
CLAUDE.md
Normal file
200
CLAUDE.md
Normal file
@ -0,0 +1,200 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code when working with gr-apollo.
|
||||
|
||||
## Project Overview
|
||||
|
||||
GNU Radio 3.10+ out-of-tree (OOT) module for decoding **Apollo Unified S-Band (USB)** telecommunications signals. Based on the 1965 NAA Telecommunication Systems Study Guide (Course A-624) and Virtual AGC project.
|
||||
|
||||
**Target signals:**
|
||||
- Downlink: 2287.5 MHz (spacecraft → ground)
|
||||
- Uplink: 2106.40625 MHz (ground → spacecraft)
|
||||
- Coherent ratio: 240/221 (Tx = Rx × 240/221)
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
gr-apollo/
|
||||
├── src/apollo/ # GNU Radio Python blocks (src-layout)
|
||||
│ ├── pm_demod.py # PM demodulator (0.133 rad peak)
|
||||
│ ├── bpsk_subcarrier_demod.py # 1.024 MHz BPSK subcarrier
|
||||
│ ├── pcm_frame_sync.py # 32-bit sync, 128-word frames
|
||||
│ ├── pcm_demux.py # Frame demultiplexer
|
||||
│ └── voice_subcarrier_demod.py # 1.25 MHz FM voice
|
||||
├── grc/ # GRC block YAML definitions
|
||||
├── docs/ # Reference documentation
|
||||
├── examples/ # Example flowgraphs
|
||||
├── pyproject.toml # Python package configuration
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
# Install in development mode
|
||||
uv pip install -e .
|
||||
|
||||
# Install GRC block definitions
|
||||
cp grc/*.yml ~/.local/share/gnuradio/grc/blocks/
|
||||
|
||||
# Test with gr-mcp (if available)
|
||||
# Use protocol analysis tools to generate decoder chain
|
||||
```
|
||||
|
||||
## Signal Architecture
|
||||
|
||||
### Downlink Signal Chain (2287.5 MHz)
|
||||
|
||||
```
|
||||
RF Input → Carrier PLL → PM Demod → Subcarrier Separation
|
||||
│
|
||||
┌───────────────────────┼───────────────────────┐
|
||||
↓ ↓ ↓
|
||||
1.024 MHz BPSK 1.25 MHz FM Ranging
|
||||
(PCM telemetry) (Voice) (PRN code)
|
||||
↓ ↓
|
||||
Symbol Sync FM Discriminator
|
||||
↓ ↓
|
||||
51.2 kbps NRZ 300-3000 Hz audio
|
||||
↓
|
||||
Frame Sync (32-bit)
|
||||
↓
|
||||
128-word demux
|
||||
```
|
||||
|
||||
### Key Parameters
|
||||
|
||||
| Parameter | Value | Notes |
|
||||
|-----------|-------|-------|
|
||||
| Downlink frequency | 2287.5 MHz | Coherent with uplink |
|
||||
| PM peak deviation | 0.133 rad (7.6°) | Phase modulation |
|
||||
| PCM subcarrier | 1.024 MHz | BPSK modulated |
|
||||
| PCM bit rate | 51.2 kbps (high) / 1.6 kbps (low) | NRZ, MSB first |
|
||||
| Voice subcarrier | 1.25 MHz | FM, ±29 kHz deviation |
|
||||
| Frame length | 128 words × 8 bits | 50 fps high rate |
|
||||
| Frame sync | 32-bit pattern | Complements on odd frames |
|
||||
| Master clock | 512 kHz | All timing derived from this |
|
||||
|
||||
### PCM Frame Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Frame Sync (32 bits = 4 words) │
|
||||
│ [5-bit A][15-bit core][6-bit B][6-bit frame ID] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Data Words 5-128 (124 words) │
|
||||
│ - High-level analog (0-5V, 8-bit) │
|
||||
│ - Low-level analog (0-40mV, 8-bit with ×125 gain) │
|
||||
│ - Digital parallel/serial inputs │
|
||||
│ - AGC downlink data (channels 34, 35, 57) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
|
||||
50 frames = 1 subframe (1 second at high rate)
|
||||
```
|
||||
|
||||
### Subcarrier Oscillators (FM Mode)
|
||||
|
||||
| SCO | Center Freq | Deviation | Use |
|
||||
|-----|-------------|-----------|-----|
|
||||
| 1 | 14,500 Hz | ±7.5% | Analog sensor |
|
||||
| 2 | 22,000 Hz | ±7.5% | Analog sensor |
|
||||
| 3 | 30,000 Hz | ±7.5% | Analog sensor |
|
||||
| 4 | 40,000 Hz | ±7.5% | Analog sensor |
|
||||
| 5 | 52,500 Hz | ±7.5% | Analog sensor |
|
||||
| 6 | 70,000 Hz | ±7.5% | Analog sensor |
|
||||
| 7 | 95,000 Hz | ±7.5% | Analog sensor |
|
||||
| 8 | 125,000 Hz | ±7.5% | Analog sensor |
|
||||
| 9 | 165,000 Hz | ±7.5% | Analog sensor |
|
||||
|
||||
## GNU Radio Blocks to Implement
|
||||
|
||||
### Phase 1: Core Demodulation
|
||||
| Block | Type | I/O | Description |
|
||||
|-------|------|-----|-------------|
|
||||
| `pm_demod` | `gr.sync_block` | complex→float | PM demodulator with carrier recovery |
|
||||
| `subcarrier_extract` | `gr.sync_block` | float→complex | Bandpass + downconvert subcarrier |
|
||||
| `bpsk_demod` | `gr.sync_block` | complex→byte | BPSK demodulation with symbol sync |
|
||||
|
||||
### Phase 2: PCM Processing
|
||||
| Block | Type | I/O | Description |
|
||||
|-------|------|-----|-------------|
|
||||
| `pcm_frame_sync` | `gr.basic_block` | byte→PDU | 32-bit sync detection, frame extraction |
|
||||
| `pcm_demux` | `gr.basic_block` | PDU→PDU | Demultiplex 128-word frames by word position |
|
||||
| `downlink_decoder` | `gr.basic_block` | PDU→dict | Interpret AGC telemetry lists |
|
||||
|
||||
### Phase 3: Voice & Analog
|
||||
| Block | Type | I/O | Description |
|
||||
|-------|------|-----|-------------|
|
||||
| `fm_voice_demod` | `gr.sync_block` | complex→float | 1.25 MHz FM subcarrier → audio |
|
||||
| `sco_demod` | `gr.sync_block` | float→float | FM SCO demodulator (configurable) |
|
||||
|
||||
## Virtual AGC Integration
|
||||
|
||||
The Virtual AGC emulator communicates via TCP socket (port 19697+):
|
||||
|
||||
```
|
||||
4-byte packet format:
|
||||
Byte 0: [Channel bits 8-4][0x00]
|
||||
Byte 1: [0x40 | Channel bits 3-1][Value bits 14-12]
|
||||
Byte 2: [0x80 | Value bits 11-6]
|
||||
Byte 3: [0xC0 | Value bits 5-0]
|
||||
```
|
||||
|
||||
Key telecom channels:
|
||||
- **Ch 45 (INLINK)**: Uplink data input
|
||||
- **Ch 57 (OUTLINK)**: Downlink data output
|
||||
- **Ch 34/35 (DNTM1/2)**: Telemetry word stream
|
||||
|
||||
## References
|
||||
|
||||
- [Implementation Spec](../virtualagc/telecom_study_guide/IMPLEMENTATION_SPEC.md)
|
||||
- [Virtual AGC Project](https://www.ibiblio.org/apollo/)
|
||||
- [NASA Apollo USB Description](https://ntrs.nasa.gov/)
|
||||
- [NAA Course A-624 Study Guide](https://archive.org/details/apollo-telecommunications)
|
||||
|
||||
## Code Style
|
||||
|
||||
- Python: Follow GNU Radio block patterns (numpy for DSP)
|
||||
- Use gr-mcp protocol analysis tools for decoder chain generation
|
||||
- Test blocks in Docker before integration
|
||||
|
||||
## Docs Site Deployment
|
||||
|
||||
Starlight documentation site in `docs/` subdirectory.
|
||||
|
||||
- **Production**: https://gr-apollo.warehack.ing
|
||||
- **Local dev**: Set `DOMAIN=gr-apollo.l.warehack.ing` in `docs/.env`
|
||||
- **Git**: `git@git.supported.systems:warehack.ing/gr-apollo.git`
|
||||
- **Server**: `ssh -A warehack-ing@warehack.ing`, repo at `~/gr-apollo`
|
||||
|
||||
### Environment
|
||||
|
||||
Copy `.env.example` to `.env` and set:
|
||||
|
||||
```env
|
||||
COMPOSE_PROJECT=gr-apollo-docs
|
||||
DOMAIN=gr-apollo.warehack.ing
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# From docs/ directory:
|
||||
make up # Production — Caddy serves static dist/
|
||||
make dev # Development — Astro dev server with HMR
|
||||
make down # Stop all containers
|
||||
make logs # Tail container logs
|
||||
```
|
||||
|
||||
### Deploy to Production
|
||||
|
||||
```bash
|
||||
# One-liner from local machine
|
||||
ssh -A warehack-ing@warehack.ing "cd ~/gr-apollo && git pull && cd docs && make up"
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Uses Docker Compose profiles (`prod` / `dev`)
|
||||
- Playwright + Chromium installed in build stage for mermaid diagram rendering
|
||||
- caddy-docker-proxy on external `caddy` network handles TLS automatically
|
||||
Loading…
x
Reference in New Issue
Block a user