docs(gps): document tracking quality and Doppler pipeline

soc/software/gps_system/README.md

@@ -17,11 +17,17 @@ gps_system.c
     -> initialize GPS, IMU and optional ESKF
     -> wfi
     -> timestamped IMU queue -> navigation_fusion prediction
-    -> GPS events -> coherent WLS -> gps_nav_solution_t
-    -> valid GPS -> fusion_gps_measurement_t -> navigation_fusion update
+    -> 20 ms tracking mailbox -> C/N0 + Doppler/range-rate
+    -> GPS events -> coherent position/velocity WLS -> gps_nav_solution_t
+    -> valid GPS position -> fusion_gps_measurement_t -> navigation_fusion update
     -> navigation_fusion_output_t -> corrected lat/lon publish
 ```
 
+Doppler WLS'nin ECEF velocity, speed ve residual sonucu
+`fusion_gps_measurement_t` icine aktarilir ve UART'ta yayinlanir. Mevcut
+`navigation_fusion` update'i henuz bu velocity alanlarini state correction
+olarak kullanmaz; ESKF'ye giren aktif GPS olcumu position'dir.
+
 Kaynak ve public header agaci ayni modul sinirlarini izler:
 
 ```text
@@ -698,34 +704,114 @@ corrected_abs_sample = (double)ABS_SAMPLE - ((double)REM_CODE_PHASE_REG / CODE_F
 
   `REM_CODE_PHASE_REG` pozitif crossing residue olarak yakalandigi icin isaret eksi kullanilir: code boundary, raw `ABS_SAMPLE` sample kenarindan `REM_CODE_PHASE_REG / CODE_FREQ_BASIS` sample kadar once gerceklesmistir. Raw `ABS_SAMPLE` yine `gps_last_nav_solve_abs_sample` icinde saklanir ve wrap/coherence delta hesaplari icin kullanilir; corrected double sadece pseudorange/navigation hesabina girer.
 - Least-squares `A` matrisi satirlari geometric range ile normalize edilir. Pseudorange ile normalize etmek DOP ve pozisyon hesaplamasini bozabilir.
-- WLS weight artik yalniz elevation'a bagli degildir. Subframe 1'den parse edilen URA/SVA index nominal metre degerine cevrilir ve her satellite icin asagidaki model kullanilir:
+- WLS weight artik yalniz elevation'a bagli degildir. Subframe 1'den parse edilen URA/SVA index nominal metre degerine cevrilir; tracking mailbox'tan
+  hesaplanan C/N0 da code-tracking kalite terimine donusturulur:
 
 ```text
-variance = ura_sigma_m^2 + (3.0 m / sin(max(elevation, 10 deg)))^2
+cn0_sigma_m = clamp(3.0 * 10^((45 - cn0_dbhz) / 20), 0.5, 30.0)
+variance = ura_sigma_m^2
+         + (3.0 m / sin(max(elevation, 10 deg)))^2
+         + cn0_sigma_m^2
 weight   = 1 / variance
 ```
 
-  Ilk receiver konumu henuz yoksa ilk iteration URA-only weight kullanir. Azimut/elevation olustuktan sonra URA ve elevation birlikte kullanilir. Relative weight'ler her iteration en buyuk weight `1.0` olacak sekilde normalize edilir. URA index 15 accuracy prediction saglamadigi veya `svhlth` alani sifir olmadigi icin uygun olmayan satellite navigation-ready snapshot'a alinmaz.
-- Formuldeki `3.0 m`, GPS yayini veya ICD tarafindan verilen bir deger degildir. Mevcut donanim canli signal-quality olcumu saglamadigi icin secilmis, konservatif ve tune edilmesi gereken zenith residual sigma varsayimidir. Elevation 90 derecede `3 m`, 30 derecede `6 m`, 10 derece ve altinda yaklasik `17.3 m` sigma uretir.
-- Tracking donanimindan ileride C/N0 veya SNR geldiginde ham register degeri dogrudan `3.0` yerine yazilmamalidir. Once gercek pseudorange/code tracking hatasina karsilik gelen metre cinsinden `sigma_cn0` degerine kalibre edilmelidir. Hedef measurement modeli asagidaki yapida olmalidir:
+  Ilk receiver konumu henuz yoksa elevation terimi kullanilmaz; gecerli C/N0
+  varsa URA + C/N0 weight yine uygulanir. Azimut/elevation olustuktan sonra uc
+  terim birlikte kullanilir. Relative weight'ler her iteration en buyuk weight
+  `1.0` olacak sekilde normalize edilir. URA index 15 accuracy prediction
+  saglamadigi veya `svhlth` alani sifir olmadigi icin uygun olmayan satellite
+  navigation-ready snapshot'a alinmaz.
+
+  Formuldeki iki `3.0 m` katsayisi GPS yayini veya ICD tarafindan verilen
+  degerler degildir; receiver'a ozel, kart olcumleri arttikca kalibre edilmesi
+  gereken baslangic modelleridir. Elevation terimi zenith'te `3 m`, 30
+  derecede `6 m`, 10 derece ve altinda yaklasik `17.3 m` sigma uretir.
+  C/N0 terimi 45 dB-Hz'de `3 m` sigma uretir ve `0.5..30 m` araliginda
+  sinirlanir. Multipath/elevation ile C/N0 ayni belirsizligi temsil ediyorsa
+  ileride cift sayimi onlemek icin kart verisiyle birlikte tune edilmelidir.
+
+### 20 ms C/N0, Doppler ve velocity WLS
+
+Her tracking kanali navigation bit epoch'unda 20 adet 1 ms prompt orneginden
+`sum_i`, `sum_q` ve wideband power (`WBP`) snapshot'i verir. Software
+narrowband/wideband power estimator'ini kullanir:
 
 ```text
-variance = ura_sigma_m^2 + sigma_cn0_m^2 + sigma_residual_atmosphere_m^2
-weight   = 1 / variance
+R = (sum_i^2 + sum_q^2) / WBP
+C/N0_linear = 1000 * (R - 1) / (20 - R)
+C/N0_dbhz = 10 * log10(C/N0_linear)
 ```
 
-  Kalibre edilmis C/N0 modeli dusuk-elevation signal degradation ve multipath etkisini yeterince temsil ederse mevcut `3 m / sin(elevation)` terimi kaldirilabilir. Bunlari tam temsil etmiyorsa ayni terim daha kucuk bir residual-atmosphere tabani olarak korunur; iki model ayni belirsizligi iki kez saymamalidir. EKF eklendiginde ayni toplam variance satellite measurement covariance `R` icinde kullanilmalidir.
-- Konum cozumu URA/elevation agirlikli WLS kullanmaya devam eder; raporlanan DOP degerleri ise bu normalize relative weight'lerden uretilmez. GDOP/PDOP/TDOP agirliksiz geometri matrisinden, HDOP/VDOP de ayni covariance ECEF'ten lokal ENU eksenlerine donduruldukten sonra hesaplanir. Boylece loglanan degerler klasik geometrik DOP anlamini korur.
+Gecersiz oranlar reddedilir; sonuc `10..60 dB-Hz` araliginda sinirlanir.
+Bir-bit estimator jitter'i ayni PRN'in ard arda olcumlerinde software
+IIR'i ile `alpha=0.2` kullanilarak yumusatilir.
+
+Carrier register'i signed Q7 toplam NCO frekansidir. Doppler ve range-rate
+donusumu:
+
+```text
+doppler_hz = carrier_q7 / 128 - 4092000
+range_rate_mps = -doppler_hz * c / 1575420000
+```
+
+Ham 20 ms carrier snapshot'inda kartta gorulen birkac hertz jitter, L1'de
+metre/saniye seviyesinde range-rate gurultusune ve zayif geometride daha buyuk
+receiver velocity hatasina donusur. Bu nedenle Doppler ayni PRN icin software
+ISR state'inde:
+
+```text
+doppler_filtered = 0.05 * doppler_raw + 0.95 * doppler_previous
+```
+
+ile filtrelenir ve range-rate filtrelenmis Doppler'dan tekrar hesaplanir.
+50 Hz measurement cadence'inde bu yaklasik `0.39 s` zaman sabitidir.
+Reacquisition/PRN degisiminde eski kanal state'i kullanilmaz.
+
+IIR donanimda da uygulanabilirdi; bunun icin kanal basina state,
+coefficient-multiply, rounding/saturation ve reacquisition reset kurali
+gerekir. Mevcut sistemde gerekli degildir: RTL'nin gorevi ham, atomik ve
+20 ms sabit olcumu sunmaktir; C/N0/WLS zaten software'dedir, katsayi hareket
+profiline gore bitstream almadan degistirilebilir ve ham Doppler debug icin
+korunur. Board testinde CPU/interrupt yolu measurement kaybetmedigi icin
+RTL filtresinin karsilayacagi bir bant genisligi veya latency problemi de
+gorulmemistir. Ileride tamamen RTL icinde bir tuketici eklenirse ham register
+yaninda ayri bir filtered register mantikli olabilir.
+
+Velocity WLS her uydu icin satellite velocity ve clock drift'i hesaba katar:
+
+```text
+observation = measured_range_rate
+            - satellite_LOS_rate
+            + c * satellite_clock_drift
+H = [-u_x, -u_y, -u_z, 1]
+state = [receiver_vx, receiver_vy, receiver_vz, receiver_clock_drift_mps]
+sigma_rate = clamp(30 * 10^(-C/N0_dbhz / 20), 0.05, 5.0)
+weight = 1 / sigma_rate^2
+```
+
+En az dort uydu gerekir. Dort uyduda velocity residual serbestlik derecesi
+yoktur; bes uydu ve dusuk PDOP'ta bile zayif geometri velocity gurultusunu
+buyutebilir. Sonuc `velocity_valid`, ECEF velocity, `speed_mps` ve
+`velocity_residual_rms_mps` alanlarinda yayinlanir, fakat henuz ESKF update'ine
+fusion edilmez.
+
+- Konum cozumu URA/elevation/CN0 agirlikli WLS kullanir; raporlanan DOP degerleri ise bu normalize relative weight'lerden uretilmez. GDOP/PDOP/TDOP agirliksiz geometri matrisinden, HDOP/VDOP de ayni covariance ECEF'ten lokal ENU eksenlerine donduruldukten sonra hesaplanir. Boylece loglanan degerler klasik geometrik DOP anlamini korur.
 - Troposfer correction her satellite icin bagimsiz hesaplanir ve dort satellite ile de aktiftir. Ilk konumsuz iteration sabit baslangic correction'i kullanir; receiver konumu olustuktan sonra elevation ve metre cinsinden receiver height modele verilir. Model kilometre bekledigi icin height donusumu yapilir ve dusuk elevation'da gecerli olabilen 5 m uzeri delay degerleri artik keyfi olarak sifirlanmaz.
 - Troposfer modelindeki mevcut `1013 hPa` basinc, `293 K` sicaklik ve `%50` bagil nem degerleri gecici fallback sabitleridir. Ileride gercek barometre/basinc, sicaklik ve nem sensorleri sisteme baglanacak; model her navigation cozumunde son gecerli sensor snapshot'indan beslenecektir. Sensor arayuzu modele basinci `hPa`, sicakligi `K` ve bagil nemi `%` olarak vermeli; birim donusumleri sensor surucusu ile navigation modeli arasinda tek bir yerde yapilmalidir. Sensor verisi henuz hazir degilse veya kullanilamiyorsa mevcut sabit atmosfer degerleriyle correction devam edecektir.
 - Least-squares veya DOP inverse matrisi singular/invalid olursa firmware artik `print_mat(NULL)` veya NULL matrix uzerinden load fault uretmez. Bu epoch sessizce skip edilir; ayrinti sadece `DEBUG_TRACE` seviyesinde gorulur ve onceki gecerli position bozularak 20 km ziplamaya zorlanmaz.
 
 ### Navigation Veri Yolu Notlari
 
-- Azimut ve elevasyon hesaplari aktif olarak elevation/URA weight ve Klobuchar correction icin kullanilir. `az` ve `el` heap matrisleri de doldurulur fakat mevcut solver bu matrisleri daha sonra okumaz. Satellite bazli metric arayuzu eklendiginde bu degerler matris yerine kalici metric kaydina tasinabilir.
+- Azimut ve elevasyon hesaplari aktif olarak elevation/URA/CN0 weight ve Klobuchar correction icin kullanilir. `az` ve `el` heap matrisleri de doldurulur fakat mevcut solver bu matrisleri daha sonra okumaz. Satellite bazli metric arayuzu eklendiginde bu degerler matris yerine kalici metric kaydina tasinabilir.
 - `rho0`/`range_t` eski range ve range-rate yolundan kalmistir. `computeRange()` icinde `rho` alanlarini dolduran eski blok kapali oldugu icin mevcut position-only akista `rho0` allocate edilir fakat sonuc uretmez.
-- `velocities` matrisi gelecekte Doppler/receiver-velocity veya EKF icin anlamlidir. Mevcut `satpos()` velocity hesaplamadigi ve aktif `computeRange()` bu matrise yazmadigi icin bugunku position solve'da kullanilmaz.
-- `computeRange()` icinde aktif parametreler `psTVLTime`, `sat_no`, `eph`, `clockCorr` ve `satellitePositions`'dir. `rho`, `ionoutc`, `xyz`, `tempPos` ve `velocities` eski genis API'den kalmistir. Ionosphere correction artik receiver azimut/elevasyonu hazir oldugunda WLS icinde uygulanir.
+- `satpos()` analitik satellite ECEF velocity ve clock drift hesaplar;
+  `computeRange()` bunlari `velocities` ve `clockDrift` matrislerine yazar.
+  Position WLS bu alanlari kullanmaz; Doppler velocity WLS kullanir.
+- `computeRange()` icinde aktif parametreler `psTVLTime`, `sat_no`, `eph`,
+  `clockCorr`, `clockDrift`, `satellitePositions` ve `velocities`'dir.
+  `rho`, `ionoutc`, `xyz` ve `tempPos` eski genis API'den kalmistir.
+  Ionosphere correction receiver azimut/elevasyonu hazir oldugunda WLS icinde
+  uygulanir.
 - Ephemeris alanlarinin mevcut isimleri ile ICD anlamlari su sekildedir: `omgdot` gercekte `Omega0`, `omg0` gercekte argument of perigee `omega`, `omgkdot` gercekte `OmegaDot` degeridir. `satpos()` bunlari dogru matematiksel yerde kullanir; konu su an hesap hatasi degil, ileride yapilacak kontrollu isim duzeltmesidir.
 - `POSTPONE_TOW=0.160` donanim/pipeline zaman kalibrasyonunun bir parcasidir; kaynagi dogrulanmadan kaldirilmamalidir.
 - Ilk nav-solve interrupt'i geldiginde o anda allocated, hardware busy ve nav-solve interrupt'i etkin olan kanallar epoch'un sabit bekleme maskesine alinir. Unlock interrupt'i gelen kanal artik tracked olmadigi icin bekleme maskesinden cikarilir; epoch ortasinda navigation-ready olan yeni kanal ise aktif maskeyi buyutmez ve sonraki epoch'tan itibaren beklenir. Kalan beklenen kanallarin tamami gelirse snapshot son interrupt'ta hemen yayinlanir. 30 ms holdoff dolarsa veya daha yeni fiziksel epoch baslarsa eksik eski epoch WLS calistirilmadan discard edilir; eski ve yeni olcumler birlestirilmez.
@@ -760,7 +846,7 @@ GPS_LOG(level, category, ...)
 
 | `GPS_DEBUG_LEVEL` | Eklenen cikti |
 | ---: | --- |
-| `1` | Temel telemetri: ham GPS/WLS `[LOCATION] source=gps`, gecerliyse ESKF `[LOCATION] source=imu_corrected`, DOP degerleri ve sifir tabanli donanim kanal numaralarini tasiyan `[TRK] tracked satellites=... prn_indices=[...]` (`0` = GPS PRN `G01`). Baslangicta fusion/IMU konfigurasyonu da bir kez yazilir. |
+| `1` | Temel telemetri: ham GPS/WLS `[LOCATION] source=gps` satirinda DOP ile birlikte `velocity_valid`, `speed` ve `velocity_rms`; gecerliyse ESKF `[LOCATION] source=imu_corrected`; sifir tabanli donanim kanal numaralarini tasiyan `[TRK] tracked satellites=... prn_indices=[...]` (`0` = GPS PRN `G01`). Baslangicta fusion/IMU konfigurasyonu da bir kez yazilir. |
 | `2` | Gelecekteki ek status ayrintilari icin ayrilmistir. Su an level 2'ye ozel mesaj yoktur; pratikte level 1 ile ayni ciktiyi verir. |
 | `3` | Level 1'e ek olarak acquisition/tracking/navigation durum gecisleri, warning/error mesajlari, integrity bilgileri ve periyodik ayrintili `[FUSION] state=...` durumu. |
 | `4` | Level 3'e ek olarak performans, scheduler, nav-bit/parser, uydu/olcum ve dusuk seviye TRACE tanilari. UART yuku en yuksek seviyedir. |
@@ -814,6 +900,23 @@ XLSX register dokumanlarina gore dogrulananlar:
   - nav timer `0x44`
   - reserved `0x48`
   - remaining code phase `0x4c`
+  - measurement meta `0x50`
+  - measurement sequence `0x54`
+  - measurement carrier Q7 `0x58`
+  - measurement absolute sample `0x5c`
+  - measurement remaining code phase `0x60`
+  - measurement prompt sum-I `0x64`
+  - measurement prompt sum-Q `0x68`
+  - measurement WBP low/high `0x6c/0x70`
+- TRCK measurement control/status bitleri:
+  - control bit 13: measurement interrupt enable
+  - control bit 14: measurement flag enable
+  - status bit 7: measurement flag
+- Measurement meta `[31:24]=version(1)`, `[12:8]=sample count`, bit 2 lock,
+  bit 1 navigation bit ve bit 0 valid alanlarini tasir.
+- Wrapper payload'i atomik register eder. Software yine de coherent read icin
+  sequence register'ini payload'dan once ve sonra okuyup iki degerin esit
+  oldugunu kontrol eder.
 - Interrupt clear davranisi write-one toggle/clear seklinde ele alindi.
 - TRCK XLSX icinde NAV_SOLVE flag aciklamasi ambiguous/copy-paste gibi gorunuyor; RTL davranisina gore nav timer solve flag olarak yorumlandi.
 
@@ -958,6 +1061,58 @@ Kalan warning'ler:
 - linker tarafinda RWX LOAD segment warning'i,
 - eski ASCII/comment formatting warning'i.
 
+20 ms tracking measurement degisiklikleri icin host/Linux ve RTL regression
+komutlari:
+
+```sh
+make -C soc/software/gps_system/tests run
+make -C soc/software/gps_system/tests sanitize
+make -C hardware/external/gps/rtl/trck_src/tb test
+```
+
+`run` ve `sanitize`, C/N0 estimator'i, Q7 Doppler/range-rate donusumu,
+coherent mailbox read'i, weighted velocity WLS ve satellite velocity/clock
+drift hesaplarini kapsar. RTL Questa/vlog-vsim testi prompt akumulasyonu,
+20 ms hold, synchronizer settle, atomik APB capture ve interrupt yolunu
+kapsar.
+
+### 2026-07-25 Genesys2 C/N0 ve Doppler Board Dogrulamasi
+
+Kart ve GPS anteni sabitken canli tracking mailbox olcumlerinde:
+
+- `M=20`, `valid=1` ve `lock=1` goruldu.
+- C/N0 kanala gore yaklasik `38..46 dB-Hz` araligindaydi; lock durumundaki
+  canli L1 C/A sinyali icin makul ve PRN'ler arasinda ayirt ediciydi.
+- Doppler kanala gore yaklasik `-3.9 kHz..+3.0 kHz` araligindaydi. Uydu
+  hareketi nedeniyle farkli PRN'lerde hem pozitif hem negatif deger
+  gorulmesi beklenen fiziksel davranistir.
+- Ham kanal Doppler jitter'i yaklasik `6..13 Hz RMS`, yani L1'de
+  `1.2..2.5 m/s` range-rate jitter'iydi. `alpha=0.05` software IIR sonrasi
+  kanal standard deviation'i yaklasik `1.1..2.2 Hz` oldu; `3x..6x`
+  iyilesme olculdu.
+- Ayni epoch'un offline karsilastirmasinda C/N0-weighted velocity WLS
+  `2.364 m/s`, equal-weight cozum `4.120 m/s` speed verdi. Bu tek epoch
+  kalite agirliginin dogru yonde fayda ettigini gosterir; genis veri seti
+  kalibrasyonunun yerine gecmez.
+- IIR yuklu firmware'de 5 uydu ve `PDOP=13..17` ile 213 velocity sonucunun
+  mean/median/p95/max speed degerleri sirasiyla
+  `2.495/2.158/6.020/11.344 m/s` oldu. Sabit alici icin sifir degildir;
+  dusuk uydu sayisi, kotu geometri ve code/ephemeris hatalari halen baskindir.
+- Satellite LOS rate cikarilip satellite clock drift eklendiginde kanallar
+  ortak yaklasik `129.9..130.8 m/s` receiver clock-drift teriminde
+  toplandi. Bu, Doppler isaretinin ve velocity observation modelinin
+  fonksiyonel olarak tutarli oldugunu dogruladi.
+- Kesintisiz kosuda `event_overflow=0`, `plic_drain_limit=0`,
+  `plic_repeat=0`, `measurement_missed=0` ve `measurement_invalid=0`
+  kaldi. Debugger ile tekrar tekrar halt edilen onceki olcumlerde gorulen
+  missed sayilari donanim mailbox/CDC kaybi olarak yorumlanmamalidir.
+
+C/N0 ve Doppler verisi fiziksel olarak makul, IIR velocity gurultusunu
+azaltiyor ve C/N0 weighting ornek epoch'ta sonucu iyilestiriyor. Buna ragmen
+position WLS'deki pseudorange/code-phase hata ve zayif geometriyi tek basina
+duzeltmiyor. Doppler velocity de henuz ESKF state update'inde kullanilmadigi
+icin `imu_corrected` cikisina dogrudan faydasi yoktur.
+
 ### 2026-07-08 ACQ Debug Notu
 
 `make fpga_debug_load APP=gps_system GDB=/usr/bin/gdb-multiarch` sonrasi GDB ile dogrulanan durum: