|

Rozdział 3: Deployment Tool (Magia jednego kliknięcia)

Nienawidzisz terminala Linuxa? Myślisz, że "Docker" to rasa psa, a "SSH" to skrót od nazwy nowej gry? Świetnie! Narzędzie RCSIM Deployment Tool powstało właśnie dla Ciebie. Jego zadaniem jest wykonanie całej brudnej roboty za Twoimi plecami.

Dla deweloperów i inżynierów przygotowaliśmy drugą część tego rozdziału (Sekcję Inżynieryjną), w której wchodzimy głęboko pod maskę kontenerów, optymalizacji zapisu na kartę SD oraz streamingu wideo.

🚀 1. "Nie muszę znać Linuxa" – Jak to działa?

Zamiast ręcznie wpisywać dziesiątki komend w terminalu, Deployment Tool automatycznie łączy się z Twoim Raspberry Pi 5 i konfiguruje cały system operacyjny.

Co dokładnie dzieje się "pod maską"?

  • Instalacja Docker: System przygotowuje izolowane środowisko (kontenery), co gwarantuje, że RCSIM zadziała identycznie i stabilnie na każdym fizycznym RPi.

  • Konfiguracja Tailscale: Tworzony jest bezpieczny tunel VPN, umożliwiający sterowanie przez internet i omijający problemy z routerami.

  • Optymalizacja Hardware: Program automatycznie włącza magistrale I2C, UART oraz konfiguruje natywny dostęp do kamery i akceleratora Hailo-8.

  • Zależności AI: Pobierane i instalowane są biblioteki niezbędne do uruchamiania sieci neuronowych w czasie rzeczywistym.

UWAGA!Przed pierwszym deployment należy używając CMD zalogować się do RPi używając ssh pi@IP_RPi(np.192.168.1.11) i wpisać YES/YES

Dzięki tej operacji RPi wie, że twój komputer jest bezpiecznym urządzeniem z którym można się połączyć.

🛠️ 2. Instrukcja Krok po Kroku

  • Narzędzie znajduje się w repozytorium w katalogu RCSIM_deployment_tool/. Wersję wykonywalną uruchamiaj z paczki dist/, a w środowisku deweloperskim możesz je przebudować skryptem build_deployment_tool.bat z głównego katalogu projektu.

  • Uruchom plik RCsimDeployment.exe albo, w trybie deweloperskim, skrypt RCSIM_deployment_tool/RCSIM_deployment_tool/RCsimRPi5deploymentapp.py.

(Opcja dla deweloperów: Możesz samodzielnie wygenerować plik .exe uruchamiając skrypt build_deployment_tool.bat, lub uruchomić aplikację bezpośrednio ze skryptu w Pythonie: RCsimRPi5deploymentapp.py).

  • Parametry Połączenia:

  • IP Address: Wpisz lokalny adres IP Twojego RPi w domowej sieci (np. 192.168.1.15).

  • Password: Wpisz hasło ustawione podczas wypalania karty SD w Raspberry Pi Imager (z Rozdziału 1).

Zobaczysz Zieloną ikonę obok adresu IP.

  • Możesz też wykonać Test SSH. Jeśli zobaczysz zielony napis "Connection OK", , oznacza to, że tunel SSH działa poprawnie.

  • Konfiguracja Parametrów Pojazdu: Zanim klikniesz start, musisz ustawić parametry swojego pojazdu. Oto co oznaczają poszczególne opcje:

  • Adres IP w sieci Tailscale: Adres Twojego komputera, powinien zostać wykryty automatycznie.

  • Porty: Zalecamy nie zmieniać tych ustawień.

Tryb komunikacji: GCS obsługuje m.in. RPi WebRTC (Wideo + Dane), RPi UDP, MAVLink RF (Nomad / XR4), CRSF Direct, Arduino, ESP32, Symulator (DonkeyCar) i Mock. Deployment musi być zgodny z trybem wybranym później w Kokpicie.

  • WEBRTC: Najnowocześniejsza metoda. Cechują ją bardzo niskie opóźnienia (Low Latency), co daje niemal natychmiastową reakcję na ruchy kierownicą. Automatycznie radzi sobie z przebijaniem się przez zapory sieciowe i routery (NAT traversal) podczas sterowania przez sieć komórkową LTE/5G. Wideo i telemetria lecą w tym samym czasie przez tzw. Data Channels.

  • UDP: Klasyczny, bardzo prosty i szybki protokół. Najlepiej sprawdza się w stabilnej, lokalnej sieci Wi-Fi, ale może mieć problemy, gdy sterujesz pojazdem "przez świat".

  • AUTO: System sam spróbuje wykryć, które połączenie jest w danej chwili najbardziej stabilne i szybkie.

Protocol (MAVLINK / NATIVE): To "język", jakim mówią urządzenia.

  • MAVLINK: Profesjonalny standard używany w dronach i łazikach (np. ArduPilot).

  • NATIVE: Lekki, uproszczony protokół stworzony specjalnie dla RCSIM.

  • Sys ID dla Mavlink: Unikalny identyfikator pojazdu w sieci (zostaw domyślne, jeśli masz jedno auto).

  • Częstotliwość wysyłania telemetrii: Określa, ile razy na sekundę (Hz) mają być odświeżane dane o stanie pojazdu. 20Hz to złoty środek między płynnością a obciążeniem procesora.

Opcje związane z systemem RTK (Wymagany GPS RTK):

    1. Co to jest RTK? Real-Time Kinematic to technika pozwalająca "podbić" dokładność GPS do poziomu 1-2 centymetrów. Jest to kluczowe, jeśli chcesz, aby pojazd precyzyjnie jeździł po ścieżkach (waypointach), tworzył idealnie równe mapy SLAM i wiedział, po której stronie krawężnika się znajduje.
    1. Co to jest NTRIP? Aby RTK działało, pojazd musi otrzymywać poprawki. Zamiast stawiać własną drogą stację bazową, NTRIP pobiera te poprawki przez internet (LTE/Tailscale).
    1. Co oznaczają te pola?
  • NTRIP Host (np. system.asgeupos.pl): Polska sieć państwowych stacji referencyjnych.

  • NTRIP Port (np. 2101): Standardowy "kanał" nadawania poprawek.

  • NTRIP Mountpoint: Tworzy "wirtualną stację bazową" dokładnie tam, gdzie znajduje się pojazd, dając najwyższą precyzję w Polsce.

  • User/Password: Twoje prywatne dane dostępowe do systemu (np. ASG-EUPOS).

Podsumowując: Włączenie tej opcji sprawia, że pojazd zaczyna widzieć swoją pozycję z dokładnością centymetrową, co jest niezbędne do profesjonalnego mapowania terenu.

Wybór IMU: To ustawienie wybiera sterownik dla Twojego sensora orientacji (Inertial Measurement Unit).

    1. Co to jest IMU? To "błędnik" Twojego pojazdu. Najważniejszy sensor (poza kamerą i GPS), dzięki któremu system wie jak bardzo pojazd jest pochylony (Roll/Pitch), w którą stronę jest zwrócony (Heading/Magnetometr - kompas) i jak szybko przyspiesza. Bez sprawnego IMU algorytmy SLAM nie będą działać, ponieważ system nie wie, jak pojazd poruszył się.
    1. Co oznacza np. "native_bmx160_bmp388"? Oznacza to układ zainstalowany w Raspberry Pi. Przedrostek native oznacza, że sterownik jest "zaszyty" bezpośrednio w kodzie, gwarantując najszybszy odczyt bez opóźnień.
  • Najlepsze wybory (Full Fusion): native_bmx160_bmp388 (Zalecany złoty standard od Boscha, mały szum i barometr), native_bno08x ("Król" sensorów, najdroższy, sam oblicza orientację, idealny do SLAM), native_mpu9250 / native_gy91.

  • Budżetowe / Ograniczone: native_mpu6050 (Tani, ale nie ma kompasu - nie wie gdzie jest północ, słaby do SLAM).

  • Sensory pomocnicze (Jedna funkcja): native_bmp280 / native_bmp180 (Tylko barometry), native_qmc5883l / native_ak8963 (Tylko kompasy).

  1. Automatyczna detekcja w RCSIM: RPi samo w sobie nie wykrywa urządzeń I2C automatycznie jak Windows USB. RCSIM posiada mechanizm SensorRegistry, który skanuje magistralę.
  • Logi: Jeśli IMU zostanie wykryte, w logach kontenera zobaczysz Auto-detected IMU: [Nazwa_Drivera]. System sprawdza standardowe adresy 0x68, 0x69, 0x48, 0x4a.

  • Diagnostyka ręczna: Możesz połączyć się przez SSH i wpisać w terminalu i2cdetect -y 1. Jeśli sensor jest widoczny, zobaczysz liczbę np. 68.

  • Diagnostyka przez narzędzie: Użyj przycisku "Run Diagnostics" w aplikacji wdrożeniowej. Jeśli sprzęt nie jest widoczny fizycznie, w logach pojawi się ostrzeżenie Auto-detection: No known IMU found on I2C bus.

Uwaga, możesz samemu dopisać swoje sterowniki. Szczegóły w załączniku.

Porty dla GPS, Lidar, Odbiornika ELRS: Sekcja komunikacji szeregowej (UART/USB) dla kluczowych akcesoriów:

  • Enable GPS: Port (zazwyczaj /dev/ttyAMA0 na pinach 14 i 15 GPIO), Baudrate (np. 115200 to nowoczesny standard dla szybkiego odświeżania pozycji).

  • Enable Lidar (LD08): Lidar Port (sugerowane /dev/ttyUSB0 przez przejściówkę USB). Lidar skanuje otoczenie laserem 360 stopni, pojazd "widzi" ściany, co pozwala budować mapy (2D SLAM) i unikać kolizji.

  • Enable RF Link (ELRS/MAVLink): RF Port (wykorzystuje dodatkowy UART, np. /dev/ttyAMA3). Umożliwia podłączenie systemu radiowego ExpressLRS o ogromnym zasięgu. MAVLink pozwala na przesyłanie telemetrii na ekran (stan baterii, tryb jazdy).

  • Krótka rada: Jeśli po podłączeniu urządzenia "nie widać" danych, najczęściej winny jest zły Port (np. zamienione USB0 z USB1) albo błędny Baudrate (urządzenie "mówi" inną prędkością niż oczekuje system).

Krótka rada: Jeśli po podłączeniu urządzenia "nie widać" danych, najczęściej winny jest albo zły Port (np. zamienione USB0 z USB1), albo błędny Baudrate (urządzenie "mówi" z inną prędkością niż oczekuje system).

Ustawienia Kamery: To co tu ustawisz, bezpośrednio wpływa na jakość wizji na drodze:

  • Camera Port: W RPi 5 wybierasz cam0 lub cam1 w zależności, w które gniazdo wpięto taśmę.

  • Camera Type: np. imx219. To model sensora (najpopularniejsza kamera RPi v2 8MP). Wybór odpowiedniego typu decyduje o doborze sterowników przez Raspberry Pi.

  • Resolution & FPS: Opcja 1280x720 (HD Ready) i 30 FPS to optymalne parametry. Obraz jest wyraźny, ale nie obciąża nadmiernie procesora.

  • Bitrate: Ilość przesyłanych danych na sekundę. 10 Mbps to bardzo wysoka jakość, ale wymaga świetnego Wi-Fi. Jeśli obraz "haczy", zmniejsz do 2-5 Mbps.

  • Przycisk: Low Latency Profile: Funkcja "jednego kliknięcia", która automatycznie ładuje parametry optymalne dla osiągnięcia absolutnie najniższych opóźnień (zwykle niższa rozdzielczość kosztem responsywności).

Jeśli obraz "haczy" lub się zacina, warto zmniejszyć tę wartość do 2-5 Mbps, są to wartości maksymalne dla systemu. Dodatkowo korzystając ze standardu WebRTC RCSIM aktywnie dostosowuje transmisję wideo do aktualnie panujących warunków łącza.

Przycisk: Low Latency Profile: Funkcja "jednego kliknięcia", która automatycznie ładuje parametry optymalne dla osiągnięcia absolutnie najniższych opóźnień (zwykle niższa rozdzielczość kosztem responsywności).

  • Rozpoczęcie Instalacji: Kliknij START DEPLOYMENT.

  • WAŻNE (Autoryzacja Tailscale): W trakcie instalacji, w oknie logów pojawi się unikalny link. Musisz go skopiować i otworzyć w przeglądarce, aby zalogować się i dodać auto do swojej prywatnej sieci VPN. Bez tego kroku zdalne sterowanie z GCS nie będzie możliwe!

  • Finał: Pierwsza instalacja trwa od 5 do 15 minut (w zależności od prędkości Twojego internetu). Gdy pasek postępu osiągnie 100%, Twoje auto jest gotowe do jazdy.

🛰️ 3. Bezprzewodowe Aktualizacje (OTA / Hot Deploy)

RCSIM wspiera system Over-The-Air Updates. Nie musisz wyciągać karty SD, by zaktualizować kod!

  • Jeśli zaktualizujesz główną grę na Steam, stacja GCS automatycznie wykryje, że w aucie działa starsza wersja oprogramowania.

  • Jednym kliknięciem możesz wysłać poprawki kodu do pojazdu, nawet jeśli auto stoi na środku toru (wymagane jest jedynie aktywne połączenie LTE/WiFi przez Tailscale).

🔍 4. Rozwiązywanie Problemów (Quick Fix)

  • Błąd SSH (Connection Failed): Upewnij się, że komputer i auto są podłączone do tej samej sieci WiFi. Sprawdź, czy na etapie wgrywania systemu (Raspberry Pi Imager) na pewno włączyłeś obsługę SSH z autoryzacją na hasło.

  • Błąd Tailscale: Jeśli instalacja "zawiesza się" na kroku Tailscale, Twoje Raspberry Pi najprawdopodobniej nie ma dostępu do internetu. Spróbuj na czas instalacji podłączyć je bezpośrednio do routera kablem LAN (Ethernet).

  • Docker Error: Jeśli w logach widzisz czerwone błędy związane z kontenerami, użyj przycisku Clean Install. Opcja ta usunie stare wersje plików, wyczyści środowisko i pobierze system całkowicie od nowa.

🧠 Sekcja Inżynieryjna: Od Skryptu do Dockera (Deep Dive)

Wdrożenie RCSIM na Raspberry Pi 5 to potężna orkiestracja systemu Linux, kontenerów Docker i akceleratorów AI. Ta sekcja wyjaśnia architekturę procesu deploymentu.

1. Architektura Hybrydowa (Build on RAM)

Największym wrogiem i wyzwaniem dla systemów wbudowanych (Embedded) jest fizyczne zużycie (wear-out) komórek pamięci w kartach SD podczas częstych zapisów i kompilacji. RCSIM rozwiązuje to w nowatorski sposób:

  • Build on /dev/shm: Cały proces kompilacji i budowania obrazów w systemie Docker (docker compose build) odbywa się w wirtualnym dysku ulokowanym w pamięci RAM (/dev/shm). Przyspiesza to operację wdrożenia o 300-600% i całkowicie chroni fizyczną kartę pamięci przed degradacją z powodu tysięcy drobnych operacji wejścia/wyjścia.

  • Export to SD: Dopiero po pomyślnym zakończeniu budowania i weryfikacji obrazu, gotowy i skompresowany projekt trafia bezpiecznie na fizyczny nośnik do katalogu /home/pi/rcsim_project.

  • System Prune: Deployment Tool po instalacji automatycznie usuwa zbędny cache APT i Dockera, oszczędzając gigabajty przestrzeni na karcie.

2. Orkiestracja Serwisów (docker-compose.yml)

Logika na pokładzie auta jest podzielona, ale kluczową rolę gra serwis główny:

  • rcsim_industrial: To główny kontener (napisany w Pythonie). Uruchamiany jest z flagą privileged: true, co pozwala na bezpośrednie, niskopoziomowe mapowanie urządzeń systemowych z hosta (RPi) do wnętrza kontenera:

  • /dev/hailo0 – natywny dostęp do procesora NPU.

  • /dev/i2c-1 – dostęp do sprzętowej magistrali sensorów.

  • /dev/video10-15 – urządzenia V4L2 do strumieniowania obrazu.

  • network: host: Kontener nie używa wirtualnej podsieci Dockera (bridge). Korzysta bezpośrednio ze stosu sieciowego hosta, co całkowicie eliminuje narzut na wirtualny NAT i krytycznie zmniejsza opóźnienia telemetrii UDP.

  1. Streaming Wideo (Native MediaMTX)

Zrezygnowaliśmy ze starych skryptów startowych kamery i ciężkich koderów Pythonowych. System używa potężnego silnika MediaMTX jako natywnej usługi:

  • rpiCamera Source: MediaMTX na poziomie systemu operacyjnego zarządza kamerami MIPI-CSI (np. IMX219 / IMX708). Oszczędza to ogromne zasoby CPU, przenosząc enkoding H.264 bezpośrednio na sprzętowy koder sprzętowy Broadcoma (V4L2 M2M).

  • Protokoły: Usługa wystawia strumień na porcie 8554 (RTSP) dla szybkiego podglądu w sieci LAN, oraz na porcie 8889 (WebRTC) zapewniając ułamkowe opóźnienia przez internet (Tailscale VPN).

  1. Persistent Hot Deploy (Błyskawiczna Iteracja)

Wprowadziliśmy mechanizm Hot Deploy, który drastycznie skraca czas potrzebny na wdrożenie własnego kodu przez programistów:

  • Volume Mounts: Główne foldery z logiką biznesową (/app/core, /app/logic, /app/modules) nie są "wypalane" w obrazie Dockera. Są zamontowane jako wolumeny (bind mounts).

  • Natychmiastowa Synchronizacja: Kiedy klikniesz w GCS opcję ⚡ Hot Deploy, aplikacja przesyła zmienione pliki .py przez SFTP wprost do katalogów hosta. Kontener widzi te zmiany natychmiastowo, bez czasochłonnego przebudowywania całego obrazu (docker build).

  • Oznacza to, że poprawka algorytmu sterowania trafia do działającego auta i aktywuje się w ułamku sekundy.

  1. Wdrażanie Modeli AI (HEF Deployment)

Pliki "mózgu" (skompresowane sieci neuronowe .hef) są ogromne, dlatego ich cykl życia jest odseparowany od kodu źródłowego:

  • Katalog Docelowy: Modele trafiają bezpiecznie do /home/pi/rcsim_project/models/, współdzielonego z kontenerem jako wolumen.

  • Dynamiczne Ładowanie: Po transferze modelu z PC na RPi, stacja GCS nadpisuje ścieżkę w pliku rc_config.json. Kontener, po otrzymaniu flagi reload (lub błyskawicznym restarcie), ładuje nowe wagi bezpośrednio do pamięci operacyjnej układu Hailo-8. Procesowi temu towarzyszy logowanie sumy kontrolnej i weryfikacja przepływu strumieni DFC.

  1. Zaawansowany Troubleshooting Wdrożenia
  • Błąd "No Camera Found": Jeśli sprzętowe narzędzie rpicam-hello --list-cameras nie widzi matrycy:

  • Otwórz edytorem plik /boot/firmware/config.txt.

  • Upewnij się, że opcja camera_auto_detect=1 jest wyłączona (zakomentowana), a włączony jest konkretny hardware overlay (np. dtoverlay=imx219,cam0).

  • Telemetria XR4 (UART3) nie działa: Jeśli używasz odbiornika ELRS/Nomad i system nie odbiera MAVLinka:

  • Upewnij się, że w config.txt aktywowano wpis dtoverlay=uart3.

  • Sprawdź kable: TX odbiornika do GPIO 9 (RX RPi), a RX odbiornika do GPIO 8 (TX RPi).

  • Sprawdź, czy baudrate sprzętowy i ten w ustawieniach GCS wynosi dokładnie 57600 bps.

  • Problemy z widocznością w Tailscale: Jeśli skrypt instalacyjny zawiódł w kwestii autoryzacji sieciowej, połącz się z RPi przez SSH i wymuś ręczną rejestrację komendą: sudo tailscale up.

  • WSL2 i Kompilator AI: Przypominamy – środowisko Windows Subsystem for Linux (Ubuntu-22.04) jest absolutnie niezbędne na Twoim komputerze PC, aby kompilować modele pod akcelerator Hailo-8. Błędy kompilatora na PC zwykle oznaczają brak instalacji najnowszych bibliotek CUDA 12.x lub sterowników Nvidia.

Masz wgrany system? Przejdź do Rozdziału 4: GCS – Pierwsze Uruchomienie ➡️

🚨 UWAGA! Błędy połączenia SSH i autoryzacji

Jeśli podczas korzystania z programu Deployment Tool lub logowania przez CMD (ssh user@IP_RPi) napotkasz problemy, poniżej znajdziesz ich wyjaśnienie i proste rozwiązania.

1. Komunikat: "REMOTE HOST IDENTIFICATION HAS CHANGED!"

Jeśli program wyświetla poniższy (wyglądający na groźny atak hakerski) komunikat:

Dlaczego tak się dzieje? Prawdopodobnie już wcześniej łączyłeś się z tym Raspberry Pi ze swojego komputera, ale niedawno reinstalowałeś na nim system (wypalałeś nową kartę SD). Twój system Windows zapamiętał stary "odcisk palca" (klucz) przypisany do tego adresu IP i teraz ostrzega Cię, że klucz uległ zmianie.

Jak to naprawić? Masz dwie opcje:

  • Opcja A (Szybsza, przez CMD): Otwórz wiersz polecenia w Windows i wpisz komendę usuwającą stary klucz dla tego IP (zmień IP na adres swojej Maliny): ssh-keygen -R 192.168.1.11

  • Opcja B (Ręczna): Otwórz Eksplorator Windows, przejdź do folderu C:\Users\TWOJA_NAZWA_UZYTKOWNIKA.ssh\ i usuń znajdujący się tam plik o nazwie known_hosts.

2. Pytanie o "Authenticity" (Zupełnie normalne!)

Gdy łączysz się z nowym urządzeniem po raz pierwszy, komputer zapyta:

Czy na pewno to jest to urządzenie, za które się podaje?

Wyświetli Ci się tzw. fingerprint (odcisk palca) klucza bezpieczeństwa.

  • Co zrobić? Po prostu wpisz słowo yes i wciśnij Enter. Twój komputer doda ten adres IP do listy "zaufanych" w pliku known_hosts. Robisz to tylko raz!
  1. Błąd: "Connection closed by... port 22"

To jest moment, w którym połączenie zostało brutalnie przerwane przez Raspberry Pi zaraz po tym, jak Twój komputer spróbował się "przywitać". Zamiast zapytać o hasło, system Cię wyrzucił.

Najczęstsze powody:

  • Zły użytkownik: Próbujesz połączyć się jako domyślny użytkownik pi (ssh pi@...). W najnowszych systemach Raspberry Pi OS domyślny użytkownik pi już nie istnieje (musiałeś stworzyć własnego podczas instalacji systemu na karcie SD w aplikacji Imager).

  • Wyłączone logowanie hasłem: Twoje Raspberry Pi może być skonfigurowane tak, że przyjmuje tylko klucze SSH, a odrzuca próby logowania zwykłym hasłem.

  • Błąd usługi SSH: Usługa na Raspberry Pi mogła się zawiesić lub ma błędną konfigurację (np. zabrania logowania temu konkretnemu użytkownikowi).

  • Blokada IP (Fail2Ban): Jeśli wcześniej kilka razy z rzędu wpisałeś błędne hasło, Malina mogła tymczasowo zablokować Twój adres IP ze względów bezpieczeństwa.

Co zrobić teraz? Aby Deployment Tool mógł działać, musisz mieć możliwość zalogowania się przez SSH. Spróbuj wykonać te kroki:

  • Upewnij się, że używasz poprawnej nazwy użytkownika (tej, którą ustawiłeś w Raspberry Pi Imager).

  • W Deployment Tool (w sekcji Connection Details) upewnij się, że wpisujesz dokładnie te same dane (IP, User), których próbujesz użyć w terminalu.

  • Jeśli masz dostęp do monitora i klawiatury podpiętej bezpośrednio do Raspberry Pi, sprawdź status usługi wpisując w terminalu: sudo systemctl status ssh

  • Dla zaawansowanych: Wygeneruj klucz SSH na swoim komputerze Windows i dodaj go do Maliny – logowanie będzie odbywać się automatycznie i w pełni bezpiecznie, bez konieczności wpisywania hasła.

Jak znaleźć adres IP Twojego auta? W Rozdziale 1 skonfigurowałeś WiFi, ale Raspberry dostaje adres automatycznie od routera. Aby go znaleźć:

  • Sprawdź w aplikacji mobilnej Fing (przeskanuj domowe WiFi).

  • Zaloguj się do panelu swojego routera i poszukaj urządzenia o nazwie "RCsim".

  • Jeśli masz już włączone Tailscale, adres IP (zaczynający się od 100.x.y.z) znajdziesz na swoim koncie Tailscale lub w aplikacji na PC.