gps/soc/software/pps_python/README.md

GPS PPS zaman modeli

Bu dizin, mevcut C navigation yolunu değiştirmeden önce WLS clock-bias ile 125 MHz PPS kontrol döngüsünün zaman davranışını incelemek için hazırlanmış event-driven Python modelidir.

Bu bir genel amaçlı GNSS simülatörü değildir. Özellikle aşağıdaki proje davranışlarını taklit eder:

• RF ABS_SAMPLE sayacı: 16.368 MHz, 32 bit ve wrap eden sayaç.

• Tracking/PPS sayacı: 125 MHz free-running sayaç.

• Navigation solve periyodu: NAV_SOLVE_TIMER=10, yani 200 ms.

• Ortak navigation bit transmit epoch'u ve uyduların farklı propagation delay'lerle art arda tracking olayı üretmesi.

• Firmware'deki corrected sample denklemi:

  corrected_abs = ABS_SAMPLE - REM_CODE_PHASE / 1.023e6
  

• gps_unwrap_corrected_abs_sample() ile aynı signed modulo-32 unwrap.

• gps_ip.c ile aynı pseudorange datum'u:

  precise_ms_i = abs_i / 16368 - minimum + 68.802
  P_i = precise_ms_i * c / 1000 + satellite_clock_i * c
  

• NavEquations.c ile aynı dört state:

  [ECEF_X, ECEF_Y, ECEF_Z, common_bias_m]
  

• Uydu saat düzeltmesi, Earth-rotation düzeltmesi, Klobuchar, aktif C troposfer modeli ve URA/elevation ağırlıkları.

• İlk 20 saniye 4 uydu, sonra 5 ve 7 uydu; ayrıca drop/re-acquisition senaryosu.

• WLS compute gecikmesi, APB gecikmesi, yapay CPU stall ve 125 MHz PI loop.

Çalıştırma

Software dizininden:

python3 pps_python/simulate_pps.py
python3 -m unittest pps_python/test_pps_model.py

Kısa veya farklı PI koşusu:

python3 pps_python/simulate_pps.py \
  --duration 300 \
  --loop-bandwidth-hz 0.02 \
  --max-slew-ppm 10

Varsayılan çıktılar pps_python/output/ altına yazılır:

• 01_wls_time_model.png: raw WLS bias, doğru zaman rekonstrüksiyonu, konum hatası ve referans uydu değişimi.
• 02_latency_timeline.png: satellite arrival span, WLS ve APB gecikmeleri.
• 03_pi_loop_response.png: timestamp'lı PI, free-run ve yanlış APB-now davranışı.
• 04_pps_edge_error.png: 8 ns çıkış quantization dahil PPS kenar hatası.
• 05_startup_tow_alignment.png: ilk HOW, propagation delay ve WLS ile coarse PPS hizalama karşılaştırması.
• epoch_results.csv: bütün epoch sonuçları.
• summary.txt: RMS ve percentile özeti.

Matplotlib GUI kullanmaz; grafikler doğrudan PNG üretilir.

Teknik PDF raporu

Teori, mevcut C/RTL mapping'i, LNAV/HOW/subframe zaman şemaları, WLS bias türetimi, 125 MHz cross-timestamp, APB commit ve PI mimarisi tek raporda:

GPS_PPS_Teori_Proje_Mapping.pdf

Grafikler güncellendikten sonra raporu yeniden üretmek için:

python3 pps_python/simulate_pps.py
python3 pps_python/generate_report.py

Rapor A4, 27 sayfadır. generate_report.py içindeki şemalar PDF'e vektörel olarak yazılır; simülasyon sonuç sayfaları output/ altındaki PNG'leri kullanır.

Modeldeki doğru zaman bağı

Mevcut observation denkleminde WLS bias doğrudan PPS fazı değildir. Minimum kanal için yaklaşık ilişki:

b/c = STARTOFFSET - signal_flight_time_min

Bu nedenle doğru GPS referansı:

GPS_TIME_AT_CAPTURE = transmit_epoch_TOW + STARTOFFSET - b/c

ile kurulur ve minimum kanala ait tracking_tick_125 ile eşlenir. Referans uydu değiştiğinde raw b/c milisaniyeler seviyesinde basamak yapabilir; TOW ve eşlenmiş timestamp ile oluşturulan GPS zamanı ise sürekli kalır. Üretilen ilk grafik bu farkı açıkça gösterir.

Raw b/c değerini PI phase error olarak doğrudan kullanmak doğru değildir.

İlk HOW ve PPS başlangıcı

parse_subframe() HOW Z-count alanını 6 s ile çarpıp tow.sec yapar. Bu, uydunun transmit subframe sınırı etiketidir. Full-subframe interrupt'ının receiver'a ulaştığı an değildir.

Mevcut hardware, subframe doğrulama/parity akışında takip eden subframe'den 8 bit daha bekler. Navigation data 50 bit/s olduğu için bu sabit readout gecikmesi 8 × 20 ms = 160 ms olur ve yazılımda POSTPONE_TOW=0.160 ile temsil edilir. Bu yüzden ilk teslim edilen subframe için:

transmit_epoch_TOW = HOW_TOW + POSTPONE_TOW
GPS_TIME_AT_CAPTURE = transmit_epoch_TOW + STARTOFFSET - b/c

POSTPONE_TOW signal flight time veya receiver clock bias değildir; hardware readout/pipeline epoch düzeltmesidir. Bundan sonra ayrıca uydu clock düzeltmesi ve yaklaşık 65--85 ms signal flight time gelir.

Mevcut baremetal kodda eph->tow.sec raw HOW değerini tutmaya devam eder; satpos() kullanım anında eph->tow.sec + POSTPONE_TOW hesaplar. PPS yolu da epoch-aligned transmit time'ı baremetal navigation katmanında tam bir kez oluşturmalıdır. PPS APB periferiki kendisine verilen GPS reference time'a POSTPONE_TOW değerini tekrar eklememelidir.

İlk HOW'un hangi kanaldan geleceği sadece uydunun yakınlığına bağlı değildir. Acquisition tamamlanma anı, bit lock ve bir sonraki tam subframe sınırı çoğu zaman propagation delay farkından daha baskındır. Monte Carlo startup modeli bu üç etkiyi ayrı gösterir.

Önerilen ownership:

1. Raw 125 MHz counter resetten itibaren free-running çalışır.
2. İlk geçerli HOW week/6-second mutlak zaman etiketini sağlar; ilk hardware delivery epoch'u için 160 ms sabit readout düzeltmesi ayrıca eklenir.
3. İlk coherent WLS çözümünde minimum corrected-ABS kanalının uçuş süresi STARTOFFSET - b/c ile elde edilir.
4. Bu receive GPS zamanı aynı kanalın yakalanmış 125 MHz timestamp'ıyla eşlenerek PPS accumulator coarse-align edilir.
5. Sonraki çözümler aynı eşleşmeden residual phase error üretip PI'yi besler.

Minimum kanal yalnız zaman datum'unu seçer; b bütün WLS uydularıyla beraber çözülür. İstenirse çözüm sonrası her uydu için (rho + iono + tropo) / c - satellite_clock hesaplanıp kendi timestamp'ına bağlanabilir. Doğru hizalamada bunların hepsi aynı receiver time mapping'ini vermelidir; bu ayrıca güçlü bir coherency testi olur.

Compute ve APB gecikmesi

Doğru model şu çifti taşır:

(GPS_TIME_AT_CAPTURE, TRACKING_COUNTER_AT_CAPTURE, epoch_sequence)

Commit anında peripheral geçen süreyi 125 MHz raw counter farkından ekler. WLS/APB gecikmesi böylece faz ölçümünün içine girmez; yalnızca kontrol komutunun gecikmesi olarak loop transfer fonksiyonunda kalır.

Karşılaştırma amacıyla untagged APB-now modeli eski GPS referansını APB yazıldığı anda geçerli kabul eder. Bunun sonucu compute/APB gecikmesine yakın milisaniyelik PPS faz hatasıdır. PI bunu oscillator hatasından ayıramaz.

PI modeli

PI, raw 125 MHz sayacı değiştirmez. Ayrı GPS time accumulator'ın rate word'ünü ayarlar:

integrator += Ki * phase_error * update_period
rate_command = integrator + Kp * phase_error

Varsayılan katsayılar ikinci dereceden düşük bant genişlikli bir loop için:

natural frequency = 0.035 Hz
damping           = 0.9
maximum slew      = 20 ppm

Bunlar Q2.46 donanım katsayılarının ilk çalışma değerleridir. Karttan clock-bias serisi ve oscillator drift ölçüldükten sonra Allan deviation/phase-noise davranışına göre yeniden ayarlanmalıdır.

C kodu analizi sırasında görülen önemli noktalar

1. leastSquaresSTD() artık aynı başarılı çözümün x/y/z/b vektörünü çağırana çıkarıyor; PPS yalnız bu çağrıdaki b değerini kullanıyor.
2. normVect(xVec) C'de yalnız ilk üç elemanı okuyor. Dolayısıyla convergence kararı XYZ update'e göre veriliyor; son clock update ayrıca kontrol edilmiyor. Python model bu davranışı aynen taklit eder ve CSV'ye final_clock_update_m yazar. PPS uygulamasından önce gerçek loglarda bunun dağılımı incelenmelidir.
3. Pseudorange her epoch'ta minimum ile yeniden normalize edildiği için RF counter'ın mutlak fazı WLS observation'da iptal olur. RF frequency error ise uyduların arrival-time farklarını ölçeklediği için tamamen iptal olmaz.
4. PPS tarafı array'in ilk elemanını referans kabul etmiyor; minimum corrected ABS kanalının TOW'u ve aynı nav-solve olayındaki C125 capture'ı birlikte taşınıyor.
5. POSTPONE_TOW=0.160, hardware'ın mevcut subframe'i doğrulamak için takip eden subframe'den 8 bit daha beklemesinden oluşan sabit readout gecikmesidir. Uydu konum/saat epoch'u buna göre 160 ms ileri alınır. Bu değer signal flight time veya WLS receiver clock bias ile birleştirilmemelidir. Mevcut satpos() zaten kullanım anında bir kez ekler; PPS peripheral tekrar eklemez.
6. 125 MHz timestamp ABS_SAMPLE ve REM_CODE_PHASE ile aynı hardware nav-solve eventinde per-channel bank'a latch ediliyor. ISR yalnız önceden yakalanmış değeri okuyor; interrupt/WLS gecikmesi epoch'a karışmıyor.

Sınırlar

• Satellite ephemeris orbitleri gerçek almanac dosyasından alınmıyor; gerçekçi ECEF/azimuth/elevation geometrisi sentetik kuruluyor.
• Multipath ve atmosfer residual'ları elevation-dependent Gaussian modeldir.
• 16.368 ve 125 MHz clock'larda ortak ve bağımsız drift bileşenleri vardır; gerçek kart spektrumu ölçülünce bunlar değiştirilmelidir.
• PPS edge sonucu 125 MHz için 8 ns grid'e quantize edilir. Bu, ölçüm doğruluğunun otomatik olarak 8 ns olduğu anlamına gelmez.