166 lines
8.7 KiB
Markdown
166 lines
8.7 KiB
Markdown
# Galileo receiver baseband model
|
||
|
||
This repository is a modular Python reference model for a Galileo receiver
|
||
baseband and a starting point for bit-true/RTL verification. It currently
|
||
implements E1B data and E1C pilot processing with a BOC(1,1) local replica,
|
||
streaming real-IF or complex-IQ front ends, FFT PCPS acquisition, independent
|
||
tracking channels, fixed-point boundary models, and hardware sizing models.
|
||
The floating reference uses `numpy.float64`/`numpy.complex128` throughout;
|
||
single-precision formats are accepted only when explicitly reading legacy files.
|
||
|
||
The repository intentionally contains **no fabricated Galileo PRN sequences**.
|
||
`SyntheticCodeProvider` creates deterministic non-ICD codes for closed-loop
|
||
verification. These codes cannot receive a live Galileo signal. Validated
|
||
official tables can be installed under `data/` and loaded through
|
||
`FileCodeProvider` without changing acquisition or tracking APIs.
|
||
|
||
An external `globsky/SignalSim` checkout is now validated as a second code and
|
||
sample source. `SignalSimCodeProvider` parses that checkout at run time without
|
||
copying its tables. The installed commit generates combined E1B/E1C BOC(1,1)
|
||
complex IQ; both acquisition and tracking pass on its IQ8 output. See the
|
||
[measured SignalSim integration report](docs/signalsim_integration.md).
|
||
|
||
## Status and limitations
|
||
|
||
- E1 profile: 1.023 Mcps, 4092 chips, 4 ms, 1575.42 MHz.
|
||
- BOC(1,1) is implemented; CBOC and unambiguous BOC are API extension points.
|
||
- E1B bit-transition hypotheses and E1C secondary wipeoff/search are available
|
||
for acquisition. E1C tracking jointly searches the 25-symbol phase and
|
||
residual carrier frequency before continuous secondary-code wipeoff.
|
||
- The code-table provider, not the DSP engine, determines whether codes are
|
||
synthetic or official.
|
||
- The floating-point model is executable. The fixed PCPS model is bit-true at
|
||
I/O, FFT output, product, power, and accumulator boundaries; an FFT
|
||
vendor/butterfly schedule must be selected before claiming bit identity with
|
||
a particular RTL FFT core.
|
||
- Channel impairments include Doppler rate, sampling-clock offset, carrier
|
||
offset, AWGN, clipping, and quantization. Multipath, jerk, oscillator phase
|
||
noise, and interference are future channel-model plug-ins.
|
||
- The default navigation architecture acquires E1C, synchronizes/wipes its
|
||
25-symbol secondary code, and drives shared carrier/code states, C/N0, and
|
||
BOC-aware lock monitoring from E1C. A phase-coherent E1B branch supplies only
|
||
Prompt I/Q to I/NAV decoding. E1B-only tracking remains a regression mode.
|
||
- Code lock is derived from smoothed VE/E/P/L/VL BOC-shape powers with explicit
|
||
metric validity, hysteresis, and side-peak/signal-loss tests; the legacy
|
||
instantaneous Prompt/Early/Late ratio is diagnostic-only.
|
||
- E1B I/NAV word types 1–6 are decoded from tracked RF prompts. Almanac parsing,
|
||
OSNMA authentication, and PVT are deliberately not implemented yet.
|
||
|
||
## Install and test
|
||
|
||
Python 3.11 or newer is required.
|
||
|
||
```bash
|
||
python -m pip install -e '.[test]'
|
||
python -m pytest
|
||
```
|
||
|
||
All automated tests use deterministic seeds and run headlessly. Plots import
|
||
Matplotlib only when explicitly requested.
|
||
|
||
## Configuration and CLI
|
||
|
||
YAML keys map to strict dataclasses in `galileo_rx.config`; unknown keys and
|
||
unsafe long integrations raise descriptive errors. Physical quantities carry
|
||
unit suffixes. See [configuration details](docs/configuration.md).
|
||
|
||
```bash
|
||
python -m galileo_rx.cli generate --config configs/acquisition_example.yaml --output samples.bin
|
||
python -m galileo_rx.cli acquire --config configs/acquisition_example.yaml --input samples.bin --output acquisition.json
|
||
python -m galileo_rx.cli track --config configs/tracking_example.yaml --input samples.bin --acquisition-result acquisition.json --output tracking.csv
|
||
python -m galileo_rx.cli run --config configs/acquisition_example.yaml --input samples.bin
|
||
python -m galileo_rx.cli compare-fixed --config configs/acquisition_example.yaml --input samples.bin
|
||
python -m galileo_rx.cli validate-signalsim --signalsim-path signalsim/SignalSim --config configs/signalsim_validation.yaml --output-dir reports/signalsim_validation
|
||
python -m galileo_rx.cli collect-navigation --config configs/navigation_collection.yaml --output-dir reports/navigation_run
|
||
python -m galileo_rx.cli collect-navigation --config configs/navigation_collection.yaml --output-dir reports/navigation_e1b --tracking-mode e1b_only
|
||
python tools/compare_e1_tracking_modes.py --config configs/navigation_collection.yaml --output-dir reports/e1_tracking_mode_comparison
|
||
python -m galileo_rx.cli prompts-to-symbols --input verification/navigation/signalsim_navigation_multisat_e1c_pilot_aided_e1b/prn_01/prompt_epochs.npz --prn 1 --output-dir reports/navigation_replay/prn_01
|
||
python -m galileo_rx.cli decode-inav --input verification/navigation/signalsim_navigation_multisat_e1c_pilot_aided_e1b/prn_01/prompt_epochs.npz --prn 1 --output-dir reports/navigation_replay/prn_01
|
||
python -m galileo_rx.cli inspect-navigation --input verification/navigation/signalsim_navigation_multisat_e1c_pilot_aided_e1b/prn_01
|
||
```
|
||
|
||
The CLI uses synthetic codes by design. Replace the provider with
|
||
`FileCodeProvider` after installing independently validated tables for live
|
||
signal work.
|
||
|
||
`validate-signalsim` is the exception: it explicitly uses the detected external
|
||
SignalSim table and IQ conventions and writes quantitative JSON/Markdown/plot
|
||
artifacts. Its quick regression is:
|
||
|
||
```bash
|
||
MPLBACKEND=Agg pytest -m signalsim -v
|
||
```
|
||
|
||
Runnable source examples are in `examples/`:
|
||
|
||
```bash
|
||
python examples/generate_e1_signal.py
|
||
python examples/run_acquisition.py
|
||
python examples/run_tracking.py
|
||
python examples/run_complete_receiver.py
|
||
```
|
||
|
||
## Architecture
|
||
|
||
The generic acquisition and tracking engines depend on `SignalProfile` and
|
||
`CodeProvider`, not E1 constants. Adding E5a/E5b therefore means defining a
|
||
profile, modulation replica, and validated code provider; engine interfaces do
|
||
not change.
|
||
|
||
```text
|
||
sample source -> streaming front end -> sample buffer -> PCPS acquisition
|
||
| |
|
||
+---- tracking manager
|
||
+-- E1C pilot master
|
||
+-- shared NCO phases
|
||
+-- E1B navigation branch
|
||
|
||
float blocks <-> fixed block boundaries <-> cycle transactions <-> RTL
|
||
```
|
||
|
||
The floating algorithms and equations are in [algorithms.md](docs/algorithms.md),
|
||
fixed-point assumptions and starting widths in
|
||
[fixed_point_plan.md](docs/fixed_point_plan.md), and the two acquisition plus two
|
||
tracking hardware options in [rtl_mapping.md](docs/rtl_mapping.md). The
|
||
module-level contract is duplicated close to the code in
|
||
`src/galileo_rx/rtl_model/architecture.md`.
|
||
|
||
Exact phase-gate test and example commands are recorded in
|
||
[development_phases.md](docs/development_phases.md).
|
||
|
||
## E1B navigation decoding
|
||
|
||
The I/NAV pipeline preserves 4 ms Prompt I/Q epochs and their sample timestamps,
|
||
recovers confidence-bearing symbols, resolves page polarity explicitly, applies
|
||
the official 30×8 deinterleaver and soft Viterbi decoder, validates CRC-24Q, and
|
||
parses typed word 1–6 data. Ephemerides are committed atomically only when words
|
||
1–4 have matching IODnav; the previous valid set survives incomplete updates.
|
||
|
||
The measured 32.2 s SignalSim regression decoded 70/70 CRC-valid pages. Four of
|
||
five tracked satellites produced complete ephemerides, clocks, healthy status,
|
||
and GST; PRN 19 correctly remained incomplete because word 1 was outside the
|
||
observation. Post-decode comparison against SignalSim's RINEX source passed at
|
||
the broadcast quantization resolution. No simulator truth is accepted by the
|
||
normal decoder API.
|
||
|
||
See [ICD mapping](docs/inav_icd_mapping.md), the
|
||
[hardware/software partition](docs/navigation_hardware_software_partition.md),
|
||
[BOC-aware lock design](docs/boc_aware_lock_detector.md),
|
||
[pilot-aided tracking architecture](docs/e1_pilot_aided_tracking.md),
|
||
the [collection report](reports/navigation_run/inav_collection_report.md), and
|
||
the [readiness gate](reports/navigation_readiness_review.md). Saved artifacts
|
||
under `verification/navigation/` can replay navigation decoding without RF
|
||
acquisition or tracking.
|
||
|
||
## Phase completion record
|
||
|
||
1. Profiles, typed configuration, code providers, BOC, generator, and I/O.
|
||
2. Streaming front end, FFT PCPS, detector metrics, long integration, plots.
|
||
3. Stateful EPL/VEVL tracking, FLL/PLL/DLL, locks, C/N0.
|
||
4. Multi-channel manager and separate E1B/E1C handling.
|
||
5. Fixed formats, NCO, mixer/correlator, PCPS boundary model, comparison/sweep.
|
||
6. Cycle transaction types, scheduler/resource equations, RTL documentation.
|
||
|
||
Assumptions and unresolved implementation choices are called out in the linked
|
||
documents rather than hidden in constants.
|