Rozdział 10: Diagnozowanie Problemów, Logi Systemowe i Baza Wiedzy (Gotchas 1-30)

Niniejszy rozdział zbiera sprawdzone procedury diagnostyczne oraz pełną bazę 30 kluczowych pułapek architektonicznych (Gotchas 1-30) zidentyfikowanych i rozwiązanych w rozwoju systemu RCSIM.

---

📋 1. Kompletna Tabela Pułapek Architektonicznych (RCSIM Gotchas 1-30)

#	Obszar	Wykryty Problem	Wdrożona Poprawka Architektoniczna
1	PySide6 & QPainter	Brak parowania wywołań w rysowaniu OSD zawiesza GUI.	Każdy painter.save() musi być ujęty w blok try...finally z painter.restore().
2	WebRTC / UDP MTU	Pakiety >1100B fragmentują i zrywają transmisję.	Obowiązkowy moduł chunking.py z kontrolerem __c: 1.
3	Qt Thread Affinity	Modyfikacja widgetów z pod-wątków powoduje wycieki pamięci.	Aktualizacja wyłącznie przez sygnały Qt (Signal.emit()).
4	NaN Guard Telemetria	Wartość NaN w telemetrii wywołuje crash GUI przy rzutowaniu int.	Obowiązkowa walidacja math.isfinite() przed przetwarzaniem danych.
5	AI Hailo-8 NPU	Niezgodność wymiarów macierzy rzuca wyjątek NPU.	Wymuszenie cv2.resize() oraz np.expand_dims(frame, axis=0).
6	BreezySLAM C-Locks	Równoległy odczyt silnika C powoduje Segmentation Fault.	Obowiązkowy threading.Lock() (SLAM Mutex) w pętli skanowania.
7	Tryb RCSIM-MCS	Wymóg bezkomputerowej pracy w terenie.	Headless RPi 5 + RP2350, własny AP Wi-Fi i sterowanie z WebUI.
8	Thrustmaster Pedals	Tryb Combined nakłada hamulec i gaz na oś skrętu Linux.	Wymuszony tryb Separate Mode w firmware kierownicy.
9	OpenCV DSHOW USB	Domyślne YUY2 na Windows obniża płynność do 9.4 FPS.	Przekazanie parametrów MJPG 60FPS bezpośrednio w konstruktorze VideoCapture.
10	WebRTC FPV Watchdog	Zbyt krótki timeout (3s) zrywa wideo przy braku enkodera.	Karencja co najmniej 15s od statusu connected przed resetem streamu.
11	Tailscale / MediaMTX	Brak serwera STUN w VPN zrywa pakiety wideo.	Wpisanie webrtcICEServers: [stun:stun.l.google.com:19302].
12	RP2350 USB CDC	Reset DTR przy otwarciu portu oraz przepełnienie bufora IN.	Ustawienie dtr=True, rts=True, delay 300ms oraz czyszczenie bufora.
13	Kolizja dead_zones	Konflikt typów pola dead_zones (LiDAR list vs PWM dict) powoduje crash AttributeError.	Walidacja wstępna @field_validator(mode="before") oraz sprawdzanie isinstance(raw, dict).
14	Audio PPM (Tier 0)	Wyciszenie do 0.0V wyzwala alarm Trainer signal lost w EdgeTX, a nadpisywanie bufora rwie fazę.	Double buffering na granicach ramek (pos == 0), ciągła ramka neutralna [1500]*8, szpilka 500µs.
15	Cykl życia QDialog	Zamykanie dialogu przez Esc lub done(result) omija closeEvent, powodując wyciek listenerów.	Czyszczenie listenerów i zatrzymywanie nasłuchiwania w nadpisanej metodzie done(result).
16	TTS na Windows (SAPI5)	Błąd comtypes w pyttsx3 gubi kolejne komunikaty po pierwszym wywołaniu runAndWait().	Bezpośrednie użycie COM win32com.client.Dispatch("SAPI.SpVoice") z zerowaniem referencji przed CoUninitialize().
17	PyTorch & CUDA DLL	Osierocone pliki c10_cuda.dll przy instalacji wersji CPU wywołują WinError 127.	Sekcja [InstallDelete] w instalatorze Inno Setup oraz usuwanie osieroconych DLL w main.py.
18	Odnośniki do Wydań	Wpisywanie niesprawdzonych tagów GitHub Releases prowadziło do błędów 404 dla użytkowników.	Dystrybucja aplikacji PC przez Steam; na stronie projektu nie udostępniamy instalatorów.
19	RadioMaster Nomad (MCS)	Błędny baudrate 420k na Linuxie oraz zmiana pinów USB UART0 (RX:3, TX:1) blokowały łączność.	Standardowy baudrate 115200 bps, ciągły strumień 100Hz i Heartbeat 0x0B co 100ms.
20	Obrazy MCS OS (PiShrink)	Obraz z karty SD zawierał domowe sieci Wi-Fi, hasła oraz niepotrzebny plik swap 1.2GB.	Skrypt sanityzacji clean_mcs_image.sh, pishrink.sh -s (ochrona uap0) oraz S3 Multipart na Cloudflare R2.
21	Konfigurator LUA (CRSF)	Firmware ELRS ignoruje pakiety zapisu parametrów (0x2D) z adresem nadajnika 0xEA.	Wymuszenie adresu LUA 0xEF (ADDR_ELRS_LUA), big-endian (>H, >f) i kolejkowanie 1 ramki/cykl.
22	Metadane Wydań	Niespójne rozmiary plików i sumy kontrolne między stroną a instalatorem.	Centralizacja w version.json, dynamiczny import w lib/release.ts oraz sync do RCSIM_Releases_PC_APP.
23	ER5C V2 GPS / PWM	Przypisanie portu GPS może zastąpić PWM na CH2.	Ustaw główny protokół GPS, CH3 Serial RX i opcjonalny CH2 Serial TX; przypisanie TX wyłącza PWM na CH2.
24	CRSF DISARM & Stop	Pętla transceivera po wyłączeniu stacji zatrzymywała ostatnie wychylenia gazu/skrętu.	Natychmiastowe zerowanie channels_norm do 1500µs, wymuszenie AUX1 (CH5) = 1000µs i pakiet STOP.
25	Dekodowanie RSSI CRSF	Błędna negacja signed int8_t (np. 230 jako -230 dBm) przy odbiornikach Semtech SX1280.	Obsługa kodu U2: dla raw > 127 przeliczenie raw - 256 (-26 dBm), dla raw <= 127 -raw.
26	CUDA Probe Bypass	Odpytywanie torch.cuda.is_available() przy starcie wywoływało Access Violation 0xC0000005 na PC bez RTX.	Bezpieczna inicjalizacja domyślnego urządzenia CPU w SyncInferenceEngine, weryfikacja GPU dopiero przy jawnym ładowaniu wag modelu.
27	Pamięć Podręczna Kafelków	Zapis bufora mapy do Program Files rzucał błąd Windows UAC [WinError 5] Access is denied dla standardowych kont.	Przeniesienie domyślnego katalogu tile_cache do katalogu użytkownika %LOCALAPPDATA%\RCSIM\tile_cache.
28	Cykl Życia Dialogów QDialog	Zamknięcie dialogu klawiszem Esc lub Anuluj omijało closeEvent(), powodując wyciek listenerów bindowania.	Zwalnianie zasobów i odłączanie sygnałów zaimplementowane w nadpisanej metodzie done(result).
29	Pakiet Diagnostyczny & Czarna Skrzynka	Brak informacji o stanie stacji przed awarią oraz czasochłonna ręczna diagnostyka systemowa.	Bufor kołowy 50 zdarzeń telemetrii (FlightRecorder) zrzucany w excepthooku oraz automatyczny eksporter raportu ZIP na Pulpicie.
30	Dynamiczny Krok dt IMU & Interpolator	Sztywny krok $dt = 0.02s$ generował do 800 ms opóźnienia fazowego przy telemetrii 12-20 Hz dla SimHub i FFB.	Monotoniczny pomiar $dt$ w filtrach orientacji oraz dwutorowy moduł IMUInterpolator (SLERP 60 FPS dla OSD + Dead Reckoning).

---

🛠️ 2. Procedura Generowania i Analizy Raportów Diagnostycznych (.zip)

W razie wystąpienia problemów z łącznością radiową, kontrolerami USB, grafiką lub zawieszeniem stacji naziemnej, system oferuje automatyczny generator pakietu diagnostycznego:

1. Generowanie Raportu z GUI:
   • Przejdź do zakładki: Ustawienia (Settings) -> Karta Deweloper (Developer).
   • Kliknij przycisk Eksportuj raport (.zip).
   • Aplikacja w ułamku sekundy stworzy na Twoim Pulpicie plik o nazwie RCSIM_Diagnostic_Report_YYYYMMDD_HHMMSS.zip.
2. Zawartość Raportu Diagnostycznego:
   • hardware_specs.txt – Szczegółowa specyfikacja sprzętowa PC (nazwa procesora, taktowanie, liczba rdzeni, ilość wolnej pamięci RAM, model karty graficznej GPU oraz wersje sterowników DirectX / OpenGL / Vulkan).
   • rcsim_gcs.log – Pełny dziennik zdarzeń stacji naziemnej wraz z inwentarzem urządzeń USB/HID, parametrami portów szeregowych i zdarzeniami pętli sterowania.
   • crash_handler.log – Zrzuty krytycznych wyjątków natywnych C++ (SIGSEGV / SIGABRT) przechwycone przez mechanizm faulthandler.
   • package_versions.txt – Zestawienie wersji zainstalowanych bibliotek (PySide6, OpenCV, PyTorch, NumPy, PySerial itp.).
   • rc_config.json oraz hardware_profiles.json – Aktualne pliki konfiguracyjne stacji do analizy nastaw PID, filtrów i kalibracji osi.
3. Analiza Czarnej Skrzynki (FlightRecorder):
   • W przypadku wystąpienia nieobsłużonego błędu, na końcu pliku rcsim_gcs.log bezpośrednio przed stosem wywołań awarii (Traceback) zrzucany jest blok === RECENT TELEMETRY EVENTS (FLIGHT RECORDER) ===.
   • Pozwala to inżynierom prześledzić dokładnie 50 ostatnich operacji (np. przejście w tryb ARMED -> ruch kierownicą -> spadek napięcia poniżej 6.8V -> utrata pakietów -> awaria).