init commit

2026-02-05 00:37:55 -07:00
commit 2c87c57651
19 changed files with 1727 additions and 0 deletions
@@ -0,0 +1,218 @@
+# 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