docs: add comprehensive README with satellite constellation info

2026-02-12 16:45:31 -07:00 · 2026-02-12 16:45:31 -07:00 · 91bef4ea63
commit 91bef4ea63
parent 5867c54de3
1 changed files with 124 additions and 37 deletions
--- a/README.md
+++ b/README.md
@ -1,64 +1,151 @@
 # gr-sarsat-modern

-GNU Radio 3.10+ compatible Cospas-Sarsat 406 MHz beacon decoder.
+GNU Radio 3.10+ blocks for decoding **Cospas-Sarsat** 406 MHz emergency distress beacons.

 Ported from [zleffke/gr-sarsat](https://github.com/zleffke/gr-sarsat) (2018, GNU Radio 3.7).

+## What is Cospas-Sarsat?
+
+**Cospas-Sarsat** is the international satellite-based search and rescue (SAR) system that has helped save over **60,000 lives** since 1982. It detects and locates emergency beacons carried by:
+
+- **EPIRBs** (Emergency Position Indicating Radio Beacons) - Maritime
+- **ELTs** (Emergency Locator Transmitters) - Aviation
+- **PLBs** (Personal Locator Beacons) - Hikers, adventurers
+
+When activated, these beacons transmit a 406 MHz signal that is picked up by a constellation of satellites and relayed to ground stations (LUTs) for position determination.
+
+## The Satellite Constellation
+
+Cospas-Sarsat uses **three types of satellites** to provide global coverage:
+
+### LEOSAR (Low Earth Orbit)
+| Satellite | Operator | Orbit |
+|-----------|----------|-------|
+| NOAA-15, 18, 19 | USA | ~850 km polar |
+| MetOp-A, B, C | EUMETSAT | ~817 km polar |
+| COSMOS (Sarsat-10,11,12) | Russia | ~1000 km polar |
+
+LEO satellites can **Doppler-locate** beacons (no GPS needed) but only see a portion of Earth at any time.
+
+### MEOSAR (Medium Earth Orbit)
+| Constellation | Satellites | Coverage |
+|---------------|------------|----------|
+| GPS | Block IIF/III (18 SAR payloads) | Global |
+| Galileo | 24 satellites | Global |
+| GLONASS | 24 satellites | Global |
+
+MEOSAR provides **near-instantaneous global coverage** and can locate GPS-equipped beacons within minutes.
+
+### GEOSAR (Geostationary)
+| Satellite | Position | Coverage |
+|-----------|----------|----------|
+| GOES-16/17 | 75°W / 137°W | Americas |
+| MSG (Meteosat) | 0° / 41.5°E | Europe/Africa |
+| INSAT-3D/3DR | 82°E / 74°E | Indian Ocean |
+| MTSAT/Himawari | 140°E | Asia-Pacific |
+
+GEO satellites provide **immediate alerting** but cannot determine position (beacon must have GPS).
+
+## Signal Specifications
+
+| Parameter | Value |
+|-----------|-------|
+| **Frequency** | 406.025 MHz (±1 kHz) |
+| **Modulation** | Phase modulation, Biphase-L encoded |
+| **Bit Rate** | 400 bps |
+| **Power** | 5W (37 dBm) minimum |
+| **Message Length** | 112 or 144 bits |
+| **Burst Duration** | ~440 ms every 50 seconds |
+
+### Frame Structure
+
+```
+┌─────────────┬──────────────────────────────────────────────────────┐
+│ Frame Sync  │                    PDS Frame (576 bits)              │
+│  15 bits    │                                                      │
+│   0x7FF     ├──────────────────┬──────────────────┬────────────────┤
+│             │  SARP Msg 1      │  SARP Msg 2      │  SARP Msg 3    │
+│             │  (24 bytes)      │  (24 bytes)      │  (24 bytes)    │
+│             │  Sync: 0xD60     │  Sync: 0xD60     │  Sync: 0xD60   │
+└─────────────┴──────────────────┴──────────────────┴────────────────┘
+```
+
 ## Blocks

-| Block | Description |
-|-------|-------------|
-| **Biphase-L Decoder** | Decodes Manchester/Biphase-L encoded bit stream |
-| **PDS Frame Sync** | Synchronizes and extracts 72-byte PDS frames |
-| **SARP Message Extractor** | Splits PDS frames into 24-byte SARP messages |
+| Block | Type | Description |
+|-------|------|-------------|
+| **Biphase-L Decoder** | `decim_block` | Decodes Manchester/Biphase-L symbols (2:1 decimation) |
+| **PDS Frame Sync** | `sync_block` | Detects frame sync, extracts 72-byte PDS frames |
+| **SARP Message Extractor** | `basic_block` | Splits frames into 24-byte SARP messages, validates sync |

 ## Installation

 ```bash
-# Install Python package
+# Clone
+git clone https://git.supported.systems/rf/gr-sarsat-modern.git
 cd gr-sarsat-modern
+
+# Install Python package
 pip install -e .

-# Copy GRC blocks to GNU Radio
+# Install GRC blocks
 cp grc/*.yml ~/.local/share/gnuradio/grc/blocks/
 ```

 ## Signal Chain

 ```
-RF Input (406 MHz)
-    |
-    v
-[FM Demod] -> [Clock Recovery] -> [Slicer]
-    |
-    v
-[Correlate Access Code - Tag]  (Frame sync: 0x7FF, tag: "pds_sync")
-    |
-    v
-[Biphase-L Decoder]
-    |
-    v
-[PDS Frame Sync]
-    |
-    v
-[SARP Message Extractor]
-    |
-    +---> valid (sync word OK)
-    +---> invalid (sync word mismatch)
+┌──────────────┐     ┌──────────────┐     ┌─────────────────┐
+│  RTL-SDR     │────▶│  FM Demod    │────▶│ Clock Recovery  │
+│  406.025 MHz │     │              │     │ MM, 400 bps     │
+└──────────────┘     └──────────────┘     └────────┬────────┘
+                                                   │
+                                                   ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  Correlate Access Code - Tag                                      │
+│  Pattern: 0x7FF (15 ones), Tag: "pds_sync"                        │
+└──────────────────────────────────────────────────┬───────────────┘
+                                                   │
+                                                   ▼
+┌──────────────────┐     ┌──────────────────┐     ┌────────────────┐
+│ Biphase-L Decode │────▶│ PDS Frame Sync   │────▶│ SARP Extract   │
+│ (2:1 decim)      │     │ (PDU out)        │     │ valid/invalid  │
+└──────────────────┘     └──────────────────┘     └────────────────┘
 ```

-## Protocol Background
+## Example Flowgraph

-Cospas-Sarsat is the international satellite-based search and rescue system:
+A minimal flowgraph for receiving SARSAT beacons:

- **Frequency**: 406.025 MHz
- **Modulation**: Phase-modulated carrier, Biphase-L encoded
- **Bit rate**: 400 bps
- **Frame structure**:
-  - 15-bit frame sync (0x7FF)
-  - 576-bit PDS frame (3 × 24-byte SARP messages)
-  - Each SARP message starts with 0xD60 sync word
+1. **Source**: RTL-SDR @ 406.025 MHz, 250 kHz sample rate
+2. **Filter**: Low-pass, 15 kHz bandwidth
+3. **FM Demod**: Quadrature demod
+4. **Clock Recovery**: M&M, omega=625 (250k/400), mu=0.5
+5. **Binary Slicer**: Threshold at 0
+6. **Correlate Access Code - Tag**: Pattern `0x7FF`, Threshold 0
+7. **Biphase-L Decoder**: Our block
+8. **PDS Frame Sync**: Our block, tag_name="pds_sync"
+9. **SARP Message Extractor**: Our block
+
+## Beacon Message Contents
+
+A decoded SARP message contains:
+
+- **Protocol Flag**: Standard or National Location
+- **Country Code**: 10-bit MID (Maritime Identification Digit)
+- **Beacon ID**: Unique identifier (MMSI for EPIRBs)
+- **Position**: Encoded lat/lon or GPS coordinates
+- **BCH Codes**: Error correction (can recover from bit errors)
+
+## References
+
+- [Cospas-Sarsat System Overview](https://www.cospas-sarsat.int/en/system-overview)
+- [406 MHz Beacon Specification (T.001)](https://www.cospas-sarsat.int/en/documents-pro/t-001-specification-for-cospas-sarsat-406-mhz-distress-beacons)
+- [Original gr-sarsat by zleffke](https://github.com/zleffke/gr-sarsat)

 ## License

-MIT License - Original work (c) 2018 zleffke
+MIT License
+
+- Original work (c) 2018 zleffke
+- GNU Radio 3.10 port (c) 2025 supported.systems