maszyna/pr-reviews/PR-172.md

Review PR #172 — UART MaSzyna Hardware Protocol v2

Autor: @Hirek193 · base: master · 34 pliki, +4860/−185 · ostatnia aktualizacja 10.10 https://github.com/MaSzyna-EU07/maszyna/pull/172

Werdykt: Request changes — konflikty, wątek startowany zawsze, brak testów kodeka

Przegląd wyrywkowy: architektura, hardware_manager, protocol_codec, konfiguracja, zmiany w Train.cpp/zmq_input. protocol_session.cpp (1327 linii) tylko pobieżnie.

Podsumowanie

Nowy podsystem hardware/: transport (serial, przygotowany pod TCP), kodek ramek (COBS + CRC32C), sesja protokołu z heartbeatem, rejestry stanów/komend/symboli, subskrypcje, panel diagnostyczny w UI. Wspólny rejestr stanu TrainState używany też przez ZMQ. Nowe klucze uart2* w eu07.ini; stary UART działa bez zmian.

Co jest dobrze

• Przemyślany protokół z dokumentacją na wiki i biblioteką Arduino.
• Kodek ostrożny wobec danych z portu: cobs_decode sprawdza index + runlength > Size, reader::require() przed odczytem, limit rozmiaru ramki, CRC32C. ✔
• Stary UART nietknięty, nowy włączany osobnymi kluczami — zgodne z zasadami kompatybilności eu07.ini.
• get_engine_voltage() wydzielone z TTrain::Update() bez zmiany logiki (sprawdziłem gałęzie: ED → |Im·5|, Mn > 0 && |Im| > 0 → wzór, inaczej 0). ✔
• ZMQ: nazwy pól wyjściowych zachowane w rejestrze (sprawdziłem m.in. shp, springbrake_active, hv_current_3, time_millisecond_of_day). ✔

Uwagi blokujące

1. Konflikty — GitHub pokazuje stan dirty, ostatnia aktualizacja 10.10. Rebase na aktualny master.
2. Wątek roboczy startuje zawsze. WITH_HARDWARE_PROTOCOL_V2 jest domyślnie ON, a hardware_manager uruchamia std::thread „even with no links configured” i co kilka sekund skanuje porty szeregowe. U każdego gracza, który nie ma żadnego sprzętu. Na Windows enumeracja COM-ów (np. porty Bluetooth) potrafi trwać, a dla niektórych sterowników jest widoczna. CLAUDE.md: nowa funkcja ma się dać wyłączyć i bez niej ma być jak dawniej. Proponuję startować wątek dopiero gdy jest uart2 w eu07.ini albo gdy użytkownik otworzy panel diagnostyczny.
3. Testy jednostkowe kodeka. protocol_codec (COBS, CRC32C, frame_decoder::feed, reader/writer) to czyste funkcje — idealne do tests/unit. Proszę o testy: round-trip, ramka uszkodzona/ucięta, przekroczony limit rozmiaru, sklejone ramki w jednym feed(). To kod parsujący dane z zewnątrz, więc testy są tu szczególnie ważne.

Pozostałe uwagi

4. Sonar / CLAUDE.md:
   • std::thread → std::jthread (S6168; tutaj wątek jest zawsze joinowany w destruktorze, więc zamiana bezpieczna),
   • std::lock_guard → std::scoped_lock (S5997),
   • s_instance — globalny wskaźnik na singleton (S5421); rozważyć przekazanie przez drivermode_input,
   • protocol_session.cpp 1327 linii — prawie na pewno S3776/S134; proszę przejrzeć raport Sonara po rebase.
5. uart2ratelimit czyta 3 wartości bez walidacji (w odróżnieniu od pozostałych kluczy z ParseOneClamped) — wartości ujemne/zero mogą zablokować komunikację.
6. Refaktor ZMQ w tym samym PR. Przeniesienie pól ZMQ do wspólnego rejestru jest sensowne, ale zmienia działające API dla istniejących klientów. Proszę potwierdzić test z realnym klientem ZMQ (np. pulpit z kolejki SOPI) albo wydzielić do osobnego PR-a.
7. version_info.h.in / gałąź w VERSION_INFO — niezwiązane z UART, a zmienia linię wersji w logu. W CI (detached HEAD) rev-parse --abbrev-ref HEAD zwróci HEAD. Osobny mały PR.
8. Opis PR to tylko 2 linki — dopisać: co testowano (jaki sprzęt, ile linków naraz, reconnect po wypięciu kabla), wpływ na wydajność, i że stary uart działa obok (na różnych portach).
9. Komentarze po polsku bez polskich znaków (napiecie, pradu) — drobne, ale reszta kodu używa UTF-8.