|

Rozdział 10: Troubleshooting i Logi (Dlaczego to nie działa?)

Część 1: Przyjazna Encyklopedia (Dla Każdego)

Witaj w prawdziwym świecie robotyki! Kiedy łączysz komputery, zaawansowaną elektronikę, silniki o ogromnej mocy i sieci bezprzewodowe, zawsze nadejdzie moment, w którym auto po prostu... nie pojedzie. Nie panikuj. System RCSIM został zaprojektowany tak, aby z Tobą "rozmawiać". W tym rozdziale nauczymy Cię, jak słuchać swojego robota i błyskawicznie diagnozować najpopularniejsze problemy.

🕵️ 1. Gdzie szukać wskazówek? (Logi stacji GCS)

Zanim zaczniesz rozkręcać auto śrubokrętem, sprawdź, co mówi oprogramowanie stacji GCS. RCSIM prowadzi szczegółowy, tekstowy dziennik zdarzeń w pliku o nazwie rcsim_gcs.log.

Gdzie go znaleźć?

  • Jeśli uruchamiasz wersję instalacyjną (plik .EXE): Wciśnij na klawiaturze skrót Win + R, wpisz %LOCALAPPDATA%\RCSIM\logs\ i wciśnij Enter. Otworzy się folder systemowy z plikiem rcsim_gcs.log.

  • Jeśli uruchamiasz wersję deweloperską (z kodu źródłowego): logi GCS są w katalogu RCSIM_PC/pc_app/logs/. Proces SLAM zapisuje dodatkowo pliki slam_process_<PID>.log w tym samym katalogu logów.

Otwórz ten plik w dowolnym notatniku, przewiń na sam dół i poszukaj linii oznaczonych jako ERROR, WARNING lub CRITICAL (np. Nieprzechwycony wyjątek (CRITICAL)).

Wskazówka telemetryczna: system logowania zapisuje dane operacyjne i sesje AI w zunifikowanym katalogu logów. Sesje Tub mają manifest.json, rekordy record_*.json i klatki frame_*.jpg; CSV treningowe (telemetry.csv, controls.csv) są generowane z rekordów JSON przez narzędzia AI loggera.

Konsola AI w zakładce AI pokazuje komunikaty z potoku treningu, eksportu, logowania i wdrożenia. Ogólne błędy aplikacji nadal weryfikuj przede wszystkim w pliku rcsim_gcs.log oraz w logach procesu SLAM.

🚑 2. Najczęstsze problemy i ich rozwiązania (Szybka Ściąga)

Problem: Czerwona ikona braku połączenia w GCS (Brak telemetrii)

Włączasz auto, ale stacja GCS w ogóle go nie widzi. Obraz się nie ładuje, zegary stoją w miejscu.

  • Krok 1: Czy wpisałeś poprawne IP auta w stacji GCS? Sprawdź w panelu routera, jaki adres IP otrzymało Twoje Raspberry Pi.

  • Krok 2: Firewall! Upewnij się, że Windows Defender lub Twój antywirus nie blokuje portów UDP (często wymagane jest zezwolenie na ruch w sieciach prywatnych).

  • Krok 3: Czy auto i komputer są w tej samej sieci Wi-Fi (lub wpięte do tego samego routera)? Z domowej sieci "Gość" zazwyczaj nie połączysz się z urządzeniami lokalnymi!

Problem: Auto jest połączone, obraz działa, ale NIE JEDZIE!

Widzisz telemetrię, poruszasz drążkami na padzie (i widzisz, że słupki w GCS reagują), ale auto stoi jak wryte.

  • Rozwiązanie 1: Wciśnij przycisk ARM! Ze względów bezpieczeństwa auto uruchamia się z zablokowanym silnikiem. Musisz wcisnąć zdefiniowany na padzie przycisk Uzbrojenia (ARM) lub klawisz SPACJA. OSD powinno przestać migać na czerwono, a napis "DISARMED" zniknie.

  • Rozwiązanie 2: Bateria w aucie. Silnik główny (ESC) i serwa potrzebują potężnego pakietu LiPo. Jeśli podłączyłeś tylko powerbanka zasilającego samo Raspberry Pi, auto będzie z Tobą "rozmawiać", ale nie będzie miało prądu, żeby zakręcić kołami!

  • Rozwiązanie 3: Kalibracja ESC. Regulator po prostu nie wie, że wciskasz gaz. Przeprowadź 3-stopniową kalibrację ESC w stacji diagnostycznej GCS (opisaną w Rozdziale 5).

Problem: Pad nie działa w aplikacji

  • Odłącz i podłącz pada. Wejdź w zakładkę Mapowanie Sterowania i sprawdź, czy nazwa Twojego kontrolera widnieje na liście urządzeń (np. "Xbox Wireless Controller").

  • Jeśli masz podłączoną kierownicę, dżojstik lotniczy i pada jednocześnie – odłącz zbędne urządzenia. Windows potrafi ustawić losowy kontroler jako "Główny".

Problem: LiDAR (laser) się nie kręci lub "nie widzi" otoczenia

  • Sprawdź kabel USB. Konwerter LiDARu musi być wpięty bezpośrednio w port USB Raspberry Pi.

  • Upewnij się, że mały silniczek z paskiem napędowym w LiDARze nie jest fizycznie zablokowany np. przez kurz czy wkręcone włosy.

Problem: Tryb MCS (Mobile Control Station) i kierownice USB (np. Thrustmaster T128X)

  • W trybie MCS komputer PC jest całkowicie zbędny na torze. Wystarczy Raspberry Pi 5 (generujące własny punkt dostępowy Wi-Fi z WebUI do konfiguracji z telefonu/tabletu) oraz mikrokontroler RP2350 generujący sygnały. Kontroler USB / kierownicę podłączamy bezpośrednio do portu USB w RPi 5.
  • Kierownica Thrustmaster T128X: Upewnij się, że tryb pedałów jest ustawiony na Separate (Domyślny) w jej firmware (robimy to w Panelu Sterowania na Windowsie przed podpięciem do RPi 5). Tryb Combined powoduje konflikt osi na Linuxie.
  • Bindowanie i Profile: Kreator autodetekcji w interfejsie (/api/wizard/detect) posiada obniżony próg czułości (do 0.5% zakresu lub delty > 20 jednostek) dla osi o małym fizycznym skoku (np. pedał hamulca). Wszelkie profile w UI bindowane są po unikalnej, stabilnej nazwie urządzenia (device_name), a nie ścieżce systemowej /dev/input/event*, która może się zmieniać przy restartach.

Problem: Niska płynność FPV (USB Grabber) lub zrywanie obrazu WebRTC

  • Limit 9.4 FPS na OpenCV: Standardowe grabbery USB na Windows negocjują format YUY2, który dławi się na USB 2.0. Aby wymusić MJPG 60 FPS w rozdzielczości 1080p, należy przekazać parametry w konstruktorze cv2.VideoCapture: params = [cv2.CAP_PROP_FRAME_WIDTH, 1920, cv2.CAP_PROP_FRAME_HEIGHT, 1080, cv2.CAP_PROP_FPS, 60, cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*'MJPG')] cap = cv2.VideoCapture(index, cv2.CAP_DSHOW, params)
  • Watchdog wideo FPV (zrywanie co 3 sekundy): Zbyt agresywny watchdog powoduje niepotrzebne restarty WebRTC podczas negocjowania kluczowych klatek. Zawsze stosuj co najmniej 15-sekundowy okres karencji od uzyskania statusu connected przed zezwoleniem na restart.
  • Brak obrazu na VPN (Tailscale): Usługa MediaMTX na RPi bez podanego serwera STUN wysyła niekompatybilne adresy lokalne. W pliku mediamtx.yml w konfiguracji webrtcICEServers należy wpisać publiczny serwer STUN, np.: webrtcICEServers: [stun:stun.l.google.com:19302]

Część 2: Inżynieryjny Deep Dive (Dla Specjalistów)

Kiedy problemy wykraczają poza odpięty kabel, musimy zejść do poziomu systemu operacyjnego Linux (Debian/Ubuntu) na Raspberry Pi 5 oraz narzędzi diagnostycznych wiersza poleceń. Poniżej znajduje się kompendium rozwiązywania problemów ze sprzętem (I/O) i usługami systemowymi.

🛠️ 1. Diagnostyka procesów pokładowych (Docker vs Systemd)

Oprogramowanie pokładowe RCSIM na Raspberry Pi może być uruchomione na dwa sposoby, w zależności od wybranej metody wdrożenia (Deploymentu). Jeśli wystąpi błąd interpretera Pythona (np. SyntaxError, ImportError, błąd inicjalizacji magistrali), proces zostanie natychmiast ubity, a logi wskażą dokładne miejsce awarii (Traceback).

A. Diagnostyka w środowisku kontenerowym (Główna Metoda)

Domyślnie RCSIM uruchamia się w zoptymalizowanym, izolowanym kontenerze Docker. Aby śledzić logi aplikacji w czasie rzeczywistym, połącz się z RPi przez protokół SSH i wykonaj komendę:

  • docker logs rcsim -f --tail 100

  • -f (Follow): Strumieniuje logi na żywo, działając jak aktywna konsola.

  • --tail 100: Wyświetla ostatnie 100 wierszy przy uruchomieniu polecenia.

B. Diagnostyka w instalacji bezpośredniej (Zapasowy Daemon Systemd)

Jeśli oprogramowanie działa bezpośrednio w systemie hosta operacyjnego (Bare Metal) jako usługa systemd, użyj narzędzia dziennika systemowego journalctl:

  • sudo journalctl -u rcsim.service -f -n 100

C. Diagnostyka serwera wideo (MediaMTX)

Za kompresję i wysyłanie strumienia wideo WebRTC/RTSP do stacji GCS nie odpowiada główna pętla Pythona, lecz niezależny demon MediaMTX (rtsp-simple-server). Jeśli masz pełną telemetrię UDP, ale ekran FPV pozostaje całkowicie czarny, sprawdź status i błędy serwera wideo:

  • sudo journalctl -u mediamtx -f -n 100

🔌 2. Rozwiązywanie Błędów Sprzętowych I/O

A. Magistrala I2C (Sterownik PCA9685 PWM)

Jeśli w logach pojawia się błąd: OSError: [Errno 121] Remote I/O error w module pca9685.py.

  • Znaczenie: Raspberry Pi próbowało wysłać bajty pod adres I2C mikrokontrolera PWM (zazwyczaj 0x40), ale urządzenie sprzętowo nie odpowiedziało bitem ACK.

  • Diagnoza niskopoziomowa: Zainstaluj narzędzia I2C (sudo apt install i2c-tools) i przeskanuj magistralę:sudo i2cdetect -y 1

  • Jeśli w wyrysowanej tabeli nie ma wartości 40, oznacza to usterkę elektryczną:

  • Sprawdź przewody danych SDA (GPIO 2) i SCL (GPIO 3). Czy nie są odwrotnie podłączone?

  • Sprawdź pin zasilania logiki układu (VCC 3.3V). Uwaga: Nie myl zasilania logiki układu scalonego z potężnym zasilaniem prądowym dla serw (V+), które podłączasz z zewnętrznego zasilacza (BEC)!

B. Interfejs UART / USB (Permission Denied dla LiDARu)

Jeśli w logach widać: PermissionError: [Errno 13] Permission denied: '/dev/ttyUSB0'

  • Znaczenie: LiDAR wykorzystuje mostek UART-do-USB (np. CP2102). W systemach Linux pliki urządzeń w /dev/ttyUSB* należą w 99% przypadków do grupy dialout. Twój aktualny użytkownik systemowy (np. pi) najprawdopodobniej nie ma do niej uprawnień.

  • Rozwiązanie: Dodaj swojego użytkownika do grupy dialout, wykonaj wylogowanie i ponowne zalogowanie (lub newgrp dialout) i zrestartuj system:sudo usermod -a -G dialout $USER

  • sudo reboot

C. Autokalibracja oscylatora na ESP32 (V3.2)

Aby zapewnić absolutną precyzję sygnałów PWM, firmware ESP32V2autocalibPCA.ino realizuje pętlę kalibracji sprzętowej.

  • Połączenie fizyczne: Wymagane jest spięcie fizyczną zworką (jumperem) wyjścia PWM Kanału 15 sterownika PCA9685 bezpośrednio z pinem GPIO Pin 12 na module ESP32.
  • Bezpieczeństwo: Podczas trwania procedury model musi być unieruchomiony (np. na stojaku serwisowym), aby uniknąć przypadkowego szarpnięcia silnikiem podczas impulsów testowych.

D. Diagnostyka Akceleratora Hailo-8L (Magistrala PCIe)

Jeśli mostek AI uparcie degraduje się do trybu awaryjnego "Mock" (CPU), mimo zamontowanego modułu NPU na szynie M.2 (PCIe/HAT).

  • Krok 1: Weryfikacja PCIe w jądrze (Kernel). Sprawdź, czy karta została w ogóle wykryta elektrycznie na szynie PCIe przez BIOS/Kernel Linuxa:lspci | grep -i hailo

  • Zwrócony wynik powinien brzmieć: Co-processor: Hailo Technologies Ltd. Hailo-8. Jeśli komenda nic nie zwraca – sprawdź wpięcie taśmy FPC modułu M.2 HAT do złącza PCIe na płycie Raspberry Pi 5.

  • Krok 2: Weryfikacja Sterowników (dmesg). Upewnij się, że sterownik kernela załadował moduł bez błędów alokacji pamięci:dmesg | grep -i hailo

  • Krok 3: HailoRT CLI. Użyj oficjalnego narzędzia klienckiego do weryfikacji zdrowia procesora neuronowego:hailortcli fw-control identify

🌐 3. Debugowanie Sieci WebRTC i UDP

Jeżeli wskaźniki telemetrii (słupki gazu, wykresy napięcia oparte na UDP) działają płynnie i bez opóźnień, ale wideo FPV (WebRTC) ładuje się w nieskończoność lub zgłasza czarny ekran – problem leży w negocjacji ICE (Interactive Connectivity Establishment).

  • P2P WebRTC jest ekstremalnie wrażliwe na topologię NAT (szczególnie symetryczny NAT w routerach domowych). Wymaga ono precyzyjnej wymiany kandydatów przed przebiciem tunelu wideo.

  • Upewnij się, że stacja GCS (PC) oraz demon mediamtx na Raspberry Pi wymieniają pakiety sygnalizacyjne (Signaling) przez protokół WebSockets (port TCP, zazwyczaj 8080). Do samego przesyłu strumienia wideo (WHEP) wymagany jest również otwarty port 8889.

  • Adaptacyjny Bitrate Wideo: System automatycznie dostosowuje jakość obrazu do warunków sieciowych w zakresie 0.5 Mbps - 5.0 Mbps. Jeśli ping przekroczy 200ms, bitrate zostanie agresywnie obniżony, aby zachować płynność sterowania.

  • Test ratunkowy: Spróbuj na chwilę całkowicie wyłączyć zaporę sieciową w Windowsie (Windows Defender Firewall dla profilu prywatnego) oraz wyłączyć zaporę w Linuxie (sudo ufw disable), aby potwierdzić, czy zapora nie ucina pakietów STUN/TURN nawiązujących strumień WebRTC.

📊 4. Szybka Ściąga Parametrów (Source of Truth)

  • Progi HYBRID (Failover na VPN): RSSI ≤ -105 dBm LUB LQ ≤ 85%. System przełącza się na link internetowy natychmiast po przekroczeniu tych wartości.
  • Ramka Sterująca CT (43 bajty): [Nagłówek: 2B (0x43, 0x54)] [PWM: 32B] [Timestamp: 8B] [CRC: 1B].
  • Deduplikacja AI: Zapis TubWriter jest wstrzymywany po 20 klatkach postoju (prędkość < 0.05 m/s).

💡 5. Wytyczne deweloperskie i architektoniczne (Gotchas)

Podczas modyfikowania lub rozszerzania kodu źródłowego stacji naziemnej (GCS) i oprogramowania pokładowego bezwzględnie przestrzegaj poniższych zasad:

  1. PySide6 i QPainter (Zawieszenie GUI): Każde wywołanie painter.save() w kodzie rysującym (np. OSD HUD) musi być bezwzględnie sparowane z painter.restore() ujętym w blok try...finally. Dowolny nieobsłużony wyjątek między tymi wywołaniami spowoduje trwałe zawieszenie głównej pętli interfejsu graficznego.
  2. Thread Affinity w Qt: Elementy interfejsu mogą być modyfikowane wyłącznie w wątku głównym (Main Thread). Zewnętrzne wątki robocze (workery) muszą komunikować się z GUI za pomocą sygnałów (Signal.emit()). Bezpośrednie wywołania metod widżetów z innych wątków są zabronione – w razie potrzeby stosuj Signal Proxy.
  3. NaN Guard: Nigdy nie rzutuj surowej telemetrii przesyłanej z drona/auta bezpośrednio na typ int w GUI bez wcześniejszej walidacji przy użyciu math.isfinite(). Wartości NaN spowodują błędy rzutowania i zatrzymanie potoku wizyjnego.
  4. Blokady zasobów C (BreezySLAM Mutex): Dostęp do mapowania i silnika BreezySLAM (napisanego w C) musi być chroniony przez blokadę mutexową (threading.Lock()), co zapobiega błędom Segmentation Fault przy jednoczesnym dostępie z wielu wątków.
  5. Limit MTU i chunking map: Pakiety przesyłane przez sieć UDP/WebRTC nie powinny przekraczać limitu 1100 bajtów, aby zapobiec fragmentacji IP. Większe obiekty (np. mapy SLAM) przesyłaj partiami za pomocą dedykowanego modułu dzielenia pakietów (chunking.py).
← POPRZEDNIRozdział 9: Autonomia AINASTĘPNY →Załączniki & Developer Guide