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

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

---

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

#	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.	Bezpośrednie hostowanie i pobieranie instalatora z Cloudflare R2 (setup_RCSIM.exe).
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	ELRS na ESP8285 (ER5C V2)	Wybór protokołu GPS przejmował pin TX (CH2), odcinając wyjście serwa/ESC PWM.	Inicjalizacja SERIAL_RX_ONLY na porcie UART, odblokowanie pinu ESC oraz auto-baudrate GPS.
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.