cat-radio/CONTEXT.md

# CAT-Radio - Cave Adapted Telephone

Open source through-the-earth digital text messaging system. FOSS clone of Cave-Link.

## Overview

| Parameter | Value |
|-----------|-------|
| Frequency | 20-140 kHz (VLF), selectable |
| Mode | Digital text, FSK modulated |
| Baud rate | 10-100 baud (frequency dependent) |
| TX power | 10-30W |
| Target range | 1000m+ through rock |
| Error handling | CRC-16 + ARQ (retry until success) |
| Relay | Store & forward |

## Why This Works

Lower frequency = deeper rock penetration.

Skin depth formula: δ ≈ 503 × √(ρ/f) meters

For 100 Ωm resistivity rock:
- 87 kHz → ~170m skin depth (Nicola voice system)
- 40 kHz → ~350m skin depth
- 20 kHz → ~500m skin depth

Digital + checksums = bad signal just means slower transmission, not errors.

## Hardware

### MCU

**STM32L476RG** (NUCLEO-L476RG dev board)

| Spec | Value |
|------|-------|
| Core | Cortex-M4 + FPU |
| Clock | 80 MHz |
| RAM | 128 KB |
| ADC | 12-bit, 5 Msps |
| DAC | 12-bit, 2 channels |
| Power | Ultra low (µA in sleep) |

### Display + Input

| Part | Notes |
|------|-------|
| ILI9341 2.4" LCD | 320x240, SPI interface |
| 4x4 membrane keypad | T9-style text input |
| HC-05 Bluetooth | Optional phone interface |

### Test Equipment

| Part | Purpose |
|------|---------|
| SDRplay RSP1A | View TX signal, debug, spectrum analysis |

### Antenna Options

**Earth Electrodes (best range):**
- Two copper/steel stakes, 30-50cm long
- 50-100m wire between them
- Low ground resistance critical
- Surface: lay out wire in field
- Underground: clip to metal, wet cracks, pools

**Loop Antenna (portable RX):**
- 0.5m diameter, collapsible frame
- 80-100 turns, 0.5mm² enameled wire
- ~50 mH inductance
- Tuned with ~300 pF variable cap
- Electrostatically shielded

## Firmware Architecture

```
┌─────────────────────────────────────┐
│           Application               │
│  - Message compose/display          │
│  - T9 text input                    │
│  - Menu system                      │
│  - Store & forward logic            │
├─────────────────────────────────────┤
│           Protocol                  │
│  - Packet framing                   │
│  - CRC-16-CCITT                     │
│  - ARQ (ACK/retry)                  │
│  - Addressing                       │
├─────────────────────────────────────┤
│           Modem                     │
│  - FSK modulator (DAC + DMA)        │
│  - FSK demodulator (Goertzel)       │
│  - Bit sync / clock recovery        │
│  - Carrier detect                   │
├─────────────────────────────────────┤
│           HAL / Drivers             │
│  - ADC + DMA                        │
│  - DAC + DMA                        │
│  - UART (debug, BT)                 │
│  - SPI (display)                    │
│  - GPIO (keypad)                    │
└─────────────────────────────────────┘
```

## Packet Format

```
┌────────┬────────┬──────┬────────┬─────────────────┬───────┐
│Preamble│Sync    │ Len  │ Header │     Payload     │ CRC   │
│ 16 bits│ 16 bits│8 bits│ 32 bits│   0-64 bytes    │16 bits│
└────────┴────────┴──────┴────────┴─────────────────┴───────┘
   0xAAAA   0x2D4B   N       ...        message       CRC-16
```

**Header:**
- Dst (1 byte): destination address, 0xFF = broadcast
- Src (1 byte): source address
- Seq (1 byte): sequence number for ARQ
- Flags (1 byte): ACK, REQ_ACK, RELAY, URGENT

## FSK Modem Specs

| Parameter | Value |
|-----------|-------|
| Center frequency | 40 kHz (default) |
| Mark (1) | center + 50 Hz |
| Space (0) | center - 50 Hz |
| Baud rate | 50 baud |
| Modulation | Continuous-phase 2-FSK |
| Demodulation | Goertzel algorithm |

## Dev Plan

### Phase 1: Modem Proof of Concept
1. Set up STM32CubeIDE
2. Generate 40 kHz sine on DAC
3. View on SDR
4. Add FSK modulation
5. Implement Goertzel demodulator
6. Loopback test (DAC → wire → ADC)

### Phase 2: Packet Protocol
1. Implement packet framing
2. Add CRC-16
3. Test encode/decode
4. Add ARQ state machine

### Phase 3: User Interface
1. Wire up ILI9341 display
2. Wire up 4x4 keypad
3. Implement T9 input
4. Message display/history

### Phase 4: RF Hardware
1. Build RX preamp
2. Build TX amplifier (10W)
3. Build antenna matching network
4. Test with loop antenna
5. Test with earth electrodes

### Phase 5: Field Testing
1. Short range through-air test
2. Through-rock test (shallow)
3. Deep cave test
4. Range optimization

## Parts List

**DigiKey:**
| Item | Price |
|------|-------|
| NUCLEO-L476RG | $14.85 |

**Amazon/AliExpress:**
| Item | Price |
|------|-------|
| ILI9341 2.4" SPI LCD | ~$10 |
| 4x4 membrane keypad | ~$3 |
| HC-05 Bluetooth module | ~$5 |

**SDRplay:**
| Item | Price |
|------|-------|
| RSP1A | ~$110 |

**Total: ~$145**

**Phase 1 Test BOM (DigiKey):**
| Item |
|------|
| 40 kHz ultrasonic transducers x2 (muRata MA40S4S/R) |
| TL072 dual op-amp |
| Breadboard |
| Jumper wire kit (M-M) |
| Through-hole ceramic capacitor variety pack |
| Through-hole resistor variety pack |

**Later (RF hardware):**
| Item | Notes |
|------|-------|
| TL072 / LF353 op-amps | RX preamp |
| IRLZ44N MOSFETs | TX PA |
| Matching transformer | Antenna interface |
| Wire, stakes | Antennas |

## References

- [Cave-Link](https://www.cavelink.com/cl3x_neu/index.php/en/)
- [Nicola System](https://www.caverescue.org.uk/nicolaradio/)
- [3496 Hz DQ Receiver](https://radiolocation.tripod.com/DQ_Construction/DQRX.htm)
- [Arduino Cave Radio (GitHub)](https://github.com/adam-sampson/Arduino-cave-radio)
- [Through-the-Earth Communications (Wikipedia)](https://en.wikipedia.org/wiki/Through-the-earth_communications)
- [Skin Depth Theory](https://em.geosci.xyz/content/maxwell1_fundamentals/harmonic_planewaves_homogeneous/skindepth.html)

## License

TBD - likely GPLv3 or MIT