diff --git a/soc/software/fusion/README.md b/soc/software/fusion/README.md index 1e62cac..49e2afd 100644 --- a/soc/software/fusion/README.md +++ b/soc/software/fusion/README.md @@ -1,11 +1,130 @@ -# Stationary GPS / ICM-4268x fusion +# GPS / IMU ESKF fusion Bu klasör Genesys2 kartından UART ile alınan GPS WLS konumlarını ve PMOD SPI -üzerindeki ICM-42686/ICM-42688 ölçümlerini Python'da işler. Filtre 15 hata -durumlu bir ESKF'dir: ENU konum/hız, quaternion tutum, ivmeölçer biası ve -jiroskop biası. Kartın durağan olduğu deneyde zero-velocity update (ZUPT) +üzerindeki TDK ICM-4268x veya ST LSM6DSOX ölçümlerini Python'da işler. Filtre +15 hata durumlu bir ESKF'dir: ENU konum/hız, quaternion tutum, ivmeölçer biası +ve jiroskop biası. Kartın durağan olduğu deneyde zero-velocity update (ZUPT) uygulanır ve GPS innovation değerlerine aykırı-ölçüm kapısı konur. +## Güncel durum ve devralma notu (2026-07-16) + +Bu bölüm yeni bir geliştirme oturumunun nereden devam edeceğini tek yerde +özetler. Aşağıdaki Python model ve bare-metal C uygulaması aynı problemi çözer, +fakat aynı program değildir: + +```text +Offline model: +UART GPS + IMU logları -> Python parser -> fixed/adaptive ESKF -> CSV/grafik/harita + +Ürün yolu: +GPS WLS ---------> fusion_bus --\ + -> fusion_engine -> 15-state ESKF -> fused LLH/ENU +TDK veya ST IMU -> imu_sensor ----/ +``` + +Python tarafındaki giriş noktaları: + +- `serial_capture.py`: UART akışını zaman damgalı CSV olarak toplar; +- `fusion_eskf.py`: GPS ve TDK/ST IMU kayıtlarını offline ESKF'de oynatır; +- `compare_eskf_models.py`: sürekli stationary kısıtlı model ile hareketi + algılayıp ZUPT'yi açıp kapatan adaptif modeli aynı veri üzerinde karşılaştırır; +- `map_player.py`: ham GPS ve düzeltilmiş ESKF noktalarını Linux masaüstü + penceresinde OpenStreetMap üzerinde zamana göre oynatır; +- `compare_firmware_logs.py` ve `synthetic_firmware_ab.py`: standalone GPS + firmware A/B ve sentetik WLS bütünlük analizlerini üretir. + +Bare-metal ürün mimarisi sürücüden bağımsızdır. `imu_sensor` aktif TDK veya ST +backend'ini seçer, `imu_calibration` SI birimine ve ortak eksen takımına +dönüştürür, `fusion_engine` ise sensör markasını bilmeden motion detector ve +ESKF'yi çalıştırır. IMU ve GPS asenkrondur; ikisi de aynı monotonik CLINT/CPU +tick alanında ölçüm anında damgalanır. GPS WLS geç tamamlanırsa fixed-lag IMU +history replay ile update gerçek ölçüm epoch'unda uygulanır. + +Doğrulama durumu: + +- Linux/GCC sentetik hareket, stationary, ani ivmelenme/fren, dönüş, ZUPT, + GPS NIS rejection, gecikmiş GPS replay, covariance invariantları ve + ASan/UBSan testleri geçti. Ayrıntılı sonuçlar aşağıdadır. +- STEVAL-MKI217V1 üzerindeki LSM6DSOX'un SPI Mode-0 okuması ve 60 saniyelik + stationary ham veri kaydı gerçek Genesys2 kartında doğrulandı. Bu, tek başına + bütünleşik fusion doğrulaması değildir. +- PMOD asynchronous input -> 3FF synchronizer -> PLIC device 11 -> C ISR yolu + ASIC/Questa simülasyonunda geçti. +- Genesys2 fiziksel sensör interrupt girişi son tasarımda `JC9/AK30`, GPS PPS + çıkışı `JC10/AK28`'dir. JC9'a geçişin kaynak/XDC/standalone test değişiklikleri + 2026-07-16 denetiminde henüz ayrı commit/push yapılmamıştı. +- GPS + ST/TDK + ESKF'nin aynı gerçek firmware koşusunda hareketli platform + testi, Rocket `rdcycle` yük ölçümü, mounting dönüşümü ve sample-loss testi + henüz tamamlanmadı. Sentetik metre sonuçları gerçek saha accuracy iddiası + değildir. + +Git devralma durumu: aktif branch `tdk_ekf`, yerel HEAD `35fbc5b` ve +`origin/tdk_ekf` `df563aa` idi; yani yerel branch remote'dan bir commit ilerideydi. +Çalışma ağacında JC9 XDC/wrapper/test değişikliklerinin yanında çok sayıda +üretilmiş bitstream, object, simülasyon ve log dosyası bulunuyordu. Yeni oturum +önce `git status`, `git diff` ve `git log --oneline --decorate -5` ile tekrar +kontrol etmeli; üretilmiş dosyaları ayırmadan `git add -A` kullanmamalıdır. + +Sonraki ana adımlar: + +1. JC9 kaynak/XDC ve test dokümanlarını seçerek commit etmek ve remote'a push + etmek; build/sim çıktısını bu commite karıştırmamak. +2. Genesys2 üzerinde fiziksel JC9 interrupt sayacı ile LSM6DSOX INT1/sample + sayısını birlikte doğrulamak. +3. `gps_system` içinde ST veya TDK seçerek GPS + IMU + ESKF UART telemetry'sini + gerçek karttan toplamak; fused LLH/ENU, hız, motion state, NIS, GPS accept/ + reject, IRQ/sample-loss ve queue sayaçlarını kaydetmek. +4. Stationary -> ani hareket -> sabit hız -> fren -> tekrar stationary testini + yapmak; hareket sırasında ZUPT'nin kapalı kaldığını doğrulamak. +5. PPS için aşağıdaki lock teşhisini tamamlamak. + +### PPS çıkmıyor: lock problemi ve teşhis + +Gözlenen belirti GPS konumunun UART'ta gelmesi fakat JC10'da PPS pulse +görülmemesidir. Bu henüz kesinleşmiş bir RTL hatası değildir. Mevcut PPS +tasarımı lock oluşmadan fiziksel çıkışı bilinçli olarak LOW tutar; dolayısıyla +konum çözülmesi tek başına PPS üretildiğini kanıtlamaz. + +İlk kabul edilen WLS/PPS commit'i yalnız coarse alignment yapar. Ardından faz +hatası en fazla sekiz adet 125 MHz tracking-clock tick'i, yani 64 ns olan beş +ardışık PI update gerekir. Lock kazanıldıktan sonra 256 ns üzerindeki yeni bir +faz hatası lock'u düşürür. WLS receiver-clock bias/pseudorange jitter'ı veya +epoch capture belirsizliği beş ardışık ölçümde 64 ns koşulunu bozarsa konum +gelmeye devam ederken PPS pini sürekli LOW kalabilir. Bu şu an en güçlü +olasılıktır; register ölçmeden eşik değiştirilmemelidir. + +Firmware ancak WLS başarılı, `solution_valid=true`, PPS referans satırı FDE ile +dışlanmamış ve referans kanalın capture sequence'i sıfır değilse PPS mailbox'a +commit yapar. Bunlardan biri sağlanmazsa PPS daha coarse alignment'a bile +ulaşmaz. + +Genesys2 post-route checkpoint kontrolünde `gps_pps` portunun `JC10/AK28`, +LVCMOS33 olarak yerleştiği, sabit 0/1'e bağlanmadığı ve PPS core +`pps_out_p_reg/Q` tarafından sürüldüğü doğrulandı. Canlı ayrım için çalışan +kartta GDB ile şu register'lar okunmalıdır: + +```gdb +x/wx 0x1002a07c +x/wx 0x1002a000 +x/wx 0x1002a004 +x/wx 0x1002a048 +x/wx 0x1002a074 +``` + +| Register | Beklenen/yorum | +|---|---| +| `VERSION @ 0x1002a07c` | `0x00020100`; farklıysa ELF/bitstream eşleşmiyor | +| `CONTROL @ 0x1002a000` | Enable + track açıkken alt bitler genellikle `0x3` | +| `STATUS @ 0x1002a004` | `0x1`: commit/alignment yok; alt bitler `0x7`: aligned fakat lock değil; bit 11 set ve alt bitler `0xf`: locked/valid | +| `ACTIVE_SEQUENCE @ 0x1002a048` | `0`: firmware hiç geçerli PPS commit'i yapmamış; artıyorsa WLS referansları PPS'ye ulaşıyor | +| `PULSE_COUNT @ 0x1002a074` | Artıyorsa RTL pulse üretiyor; sorun JC10/prob/GND tarafındadır | + +Sağlıklı ve sticky hata biti olmayan tipik lock durumu `STATUS=0x0000080f`'tir. +`ACTIVE_SEQUENCE` artarken `STATUS` yaklaşık `0x7` kalıyorsa problem pin değil, +lock acquisition/faz jitter'ıdır. `STATUS` lock gösteriyor ve `PULSE_COUNT` +artıyorsa JC10 sinyali JC11 GND referansıyla osiloskop veya logic analyzer'da +ölçülmelidir; pulse saniyede bir yaklaşık 100 ms HIGH'dır. + ## Çalıştırma UART kaydı: diff --git a/soc/software/gps_system/README.md b/soc/software/gps_system/README.md index 6628eb9..dc7191e 100644 --- a/soc/software/gps_system/README.md +++ b/soc/software/gps_system/README.md @@ -15,7 +15,7 @@ ST LSM6DSOX ------/ - `src/tdk_icm42688.c`: TDK ICM42688'e ozel SPI, register, interrupt ve ham-veri donusumu. - `src/st_lsm6dsox.c`: STEVAL-MKI217V1 uzerindeki ST LSM6DSOX'e ozel SPI, - register, foreground polling ve ham-veri donusumu. + register, INT1 data-ready interrupt ve ham-veri donusumu. - `src/imu_sensor.c`: ortak init/start/stop/IRQ/service/measurement arayuzu. - `src/imu_calibration.c`: markadan bagimsiz bias, 3x3 scale/cross-axis/mounting donusumu ve opsiyonel sicaklik katsayisi. @@ -70,23 +70,27 @@ secer. Bu ozellikle `auto` icin onemlidir; TDK ve ST'nin ortak bir ODR degeri yoktur. Desteklenen ODR'ler TDK icin 25/50/100/200/500/1000 Hz, ST icin 52/104/208 Hz'dir. -TDK veri-hazir interrupt'i ile calisir ve ana dongu `wfi` kullanir. Mevcut ST -baglantisinda interrupt pini bagli olmadigi icin ST surucusu foreground'da -ODR'nin iki kati hizda status poll eder; yeni ornekleri sensor ODR'sinde -uretir. Bu yontem fonksiyoneldir fakat CPU'nun `wfi` ile uyumasini engeller. -Uzun WLS islemi sirasinda foreground durdugu icin sensorun yeni ornekleri -overwrite olabilir. Bu nedenle interruptsiz ST yolu stationary bring-up ve log -testi icindir; hareketli fusion icin kayipsiz bir yol kabul edilmez. -Uretim baglantisinda ST INT pini eklendiginde yalniz ST backend acquisition -yontemi interrupt'a cevrilecek (alternatif olarak sensor FIFO ve sensor -timestamp'i kullanilacak); ortak arayuz ve ESKF degismeyecektir. +TDK ve ST veri-hazir interrupt'i ile calisir ve ana dongu `wfi` kullanabilir. +Genesys2 son pin planinda ortak aktif sensor interrupt girişi `JC9/AK30` +uzerinden wrapper'daki 3FF synchronizer'a, oradan PLIC device 11'e gider. ST +surucusu LSM6DSOX accel data-ready olayini INT1'e yonlendirir; ISR local CLINT +timestamp'ini basta alir, latched kaynagi temizler, ayni sample'in gyro ve +sicaklik alanlarini okuyup statik SPSC kuyruğa koyar. `imu_sensor_service()` +interrupt backend'lerde no-op'tur. + +Standalone LSM6DSOX SPI okuma ve stationary log kartta dogrulanmistir. Buna +karsilik JC9 fiziksel interrupt yolu ile GPS + ST + ESKF'nin ayni urun firmware +kosusundaki end-to-end testi henuz tamamlanmis sayilmamalidir. ASIC/Questa +simulasyonunda asynchronous input -> 3FF -> PLIC device 11 -> C ISR yolu +gecmistir. Yuksek ODR ve uzun WLS sirasinda sample kaybini daha da azaltmak +gerekirse sonraki gelistirme sensor FIFO + sensor timestamp kullanmaktir; +ortak IMU arayuzu ve ESKF bunun icin degismeyecektir. Sensor ODR'si ile GPS nav-solve periyodu birbirinden bagimsizdir. Her IMU ve GPS olcumu ayni local monotonic CPU tick domaininde kendi olcum zamaniyla tasinir; -ESKF olaylari timestamp sirasinda isler. TDK interrupt timestamp'i data-ready -kenarini yakindan temsil eder. Poll edilen ST timestamp'i ise data-ready'nin -foreground'da goruldugu andir ve bir polling gecikmesi tasir. Hareketli nihai -sistemde ST INT veya FIFO timestamp kullanma gereksiniminin nedeni budur. +ESKF olaylari timestamp sirasinda isler. TDK ve ST ISR timestamp'i data-ready +kenarini yakindan temsil eder. Daha kesin ve WLS/interrupt latency'sinden +bagimsiz yuksek-ODR zamanlama gerekirse sensor FIFO timestamp'i kullanilmalidir. ### Kalibrasyon ve sicaklik politikasi diff --git a/soc/software/pmod_irq_test/README.md b/soc/software/pmod_irq_test/README.md index ca7f3d6..abf72c2 100644 --- a/soc/software/pmod_irq_test/README.md +++ b/soc/software/pmod_irq_test/README.md @@ -1,8 +1,8 @@ -# Genesys2 JB1 direct PLIC test +# Genesys2 JC9 direct PLIC test This standalone image tests only the asynchronous PMOD interrupt path: -`JB1 (V29) -> wrapper 3FF synchronizer -> Rocket interrupt bus -> PLIC 11` +`JC9 (AK30) -> wrapper 3FF synchronizer -> Rocket interrupt bus -> PLIC 11` The input is LVCMOS33 with a weak FPGA pull-down. The Rocket PLIC gateway is level-sensitive, so the ISR masks source 11 on its first assertion before it @@ -16,14 +16,14 @@ make -C soc/software/pmod_irq_test clean all ``` After loading `build/pmod_irq_test.elf`, wait for `PMOD_IRQ_READY`. Start with -JB1 disconnected, then connect JB1 to a Genesys2 PMOD 3.3 V pin once. A working +JC9 disconnected, then connect JC9 to a Genesys2 PMOD 3.3 V pin once. A working path prints `PMOD_IRQ_PASS`. Remove the 3.3 V connection before resetting or reloading the image. -Never apply 5 V to JB1 and never short a PMOD supply pin to ground. +Never apply 5 V to JC9 and never short a PMOD supply pin to ground. For a voltage-source-independent loopback test, connect the FPGA-driven JC4 -SPI clock output directly to the JB1 interrupt input. After +SPI clock output directly to the JC9 interrupt input. After `LOOPBACK_READY`, send `t` over UART. The firmware emits 16 SPI transfers; the first SCK HIGH must produce `PMOD_IRQ_PASS`. This loopback is confined to the standalone diagnostic and does not add GPIO or alter the production PLIC diff --git a/soc/software/steval_mki217v1_test/README.md b/soc/software/steval_mki217v1_test/README.md index b53fb43..583eb13 100644 --- a/soc/software/steval_mki217v1_test/README.md +++ b/soc/software/steval_mki217v1_test/README.md @@ -1,11 +1,10 @@ -# STEVAL-MKI217V1 polling test (Genesys2) +# STEVAL-MKI217V1 INT1 data-ready test (Genesys2) This standalone bare-metal application reads the LSM6DSOX on the -STEVAL-MKI217V1 over the existing Genesys2 PMOD SPI peripheral. It does not -use INT1/INT2. The LIS2MDL magnetometer on the module is not enabled in this -first electrical/readout smoke test; it is internally reachable through the -LSM6DSOX sensor hub and will be integrated separately after the IMU link is -verified. +STEVAL-MKI217V1 over the existing Genesys2 PMOD SPI peripheral and uses INT1 +for data-ready interrupts. The LIS2MDL magnetometer on the module is not +enabled; it is internally reachable through the LSM6DSOX sensor hub and will +be integrated separately after the IMU link is verified. ## Wiring @@ -15,12 +14,13 @@ verified. | SDA | JC2 | SPI MOSI / SDI | | SDO | JC3 | SPI MISO | | SCL | JC4 | SPI clock / SPC | +| INT1 | JC9 | active-high data-ready interrupt | | VDD | 3.3 V | sensor supply | | VDDIO | 3.3 V | digital I/O supply | | GND | GND | common ground | -`CS` is mandatory for four-wire SPI. Never feed 5 V to VDDIO. JB1 is the -optional sensor interrupt pin but is deliberately unused here. +`CS` is mandatory for four-wire SPI. Never feed 5 V to VDDIO. JC9 is routed +through the FPGA 3FF synchronizer to PLIC device 11. ## Hardware bring-up results (2026-07-13)