APRS-CoT Gateway

Lokalna bramka do mostkowania ruchu pomiędzy:

• SARTrack
• APRS
• Meshtastic
• CoT / ATAK jako wyjściem rozwojowym

Projekt działa jako asynchroniczny router zdarzeń. Odbiera pozycje i wiadomości z kilku wejść, normalizuje je do wspólnego modelu, filtruje duplikaty i przekazuje dalej do aktywnych adapterów.

Najbardziej praktyczne ścieżki w obecnej wersji:

• SARTrack -> lokalny serwer APRS-IS -> gateway -> Meshtastic
• SARTrack -> Dire Wolf / AGWPE -> gateway -> Meshtastic
• Meshtastic -> gateway -> APRS-IS / AGWPE server

Aktualny stan

Repozytorium zawiera działającą implementację:

• runtime asyncio z centralnym routerem zdarzeń
• wspólny model PositionEvent i MessageEvent
• deduplikację zdarzeń i podstawową ochronę przed pętlami
• lokalny panel operatorski HTTP z podglądem stanu, zdarzeń, logów i testowym TX
• trwały zapis części zmian runtime z GUI z powrotem do config.py
• wejście APRS przez klienta AGWPE
• serwer AGWPE, który potrafi przyjmować i nadawać ramki monitorowe T oraz V
• lokalny serwer APRS-IS dla klientów SARTrack i innych klientów TCP
• klient SARTrack APRS, który łączy się do zewnętrznego serwera APRS-IS i publikuje odebrane ramki do routera
• natywny serwer SARTrack TCP dla prostych rekordów pozycji i wiadomości
• adapter Meshtastic TCP z reconnectem, backoffem, odbiorem tekstu i pozycji oraz mapowaniem callsign <-> node
• stub adaptera CoT

Architektura

Główne katalogi:

• core/
  • model zdarzeń
  • router
  • cache deduplikacji
  • in-memory state store dla GUI i logów
• aprs/
  • klient AGWPE
  • serwer AGWPE
  • lokalny serwer APRS-IS
  • parser APRS
  • generatory ramek APRS
• sartrack/
  • serwer SARTrack TCP
  • klient SARTrack APRS
  • parser prostych rekordów SARTrack
• mesh/
  • adapter Meshtastic TCP
  • parser pakietów Meshtastic
• cot/
  • adapter i generator XML CoT
• gui/
  • panel operatorski oparty o FastAPI
• utils/
  • konfiguracja logowania

Punkty wejścia:

• main.py
• config.py

Model zdarzeń

Gateway rozróżnia dwa typy pozycji:

• station
• object

To rozróżnienie jest używane przy:

• generowaniu APRS TX
• prezentacji zdarzeń w GUI
• budowie waypointów Meshtastic
• kształtowaniu przyszłego wyjścia CoT

PositionEvent przechowuje między innymi:

• id
• lat, lon
• entity_kind
• tactical_name
• object_name
• owner_id
• symbol_table, symbol_code

MessageEvent przechowuje między innymi:

• id
• target
• message
• message_id

Obsługiwane wejścia i wyjścia

APRS przez AGWPE klienta

Adapter aprs.agwpe odbiera ruch APRS z serwera AGWPE i publikuje go do routera. Wspiera reconnect oraz defensywne odrzucanie niepoprawnych ramek.

AGWPE server

Adapter aprs.agwpe_server działa jako serwer kompatybilny z klientami AGWPE:

• nasłuchuje na TCP
• przyjmuje komendy monitoringu
• odbiera ramki M i V
• dekoduje z nich APRS
• wysyła zrouterowane zdarzenia z powrotem do klientów jako T i/lub V

To pozwala podłączyć narzędzia oczekujące interfejsu AGWPE bez stawiania pełnego Dire Wolf po drugiej stronie.

Lokalny APRS-IS server

Adapter aprs.is_server udostępnia prosty lokalny serwer APRS-IS:

• przyjmuje logowanie user ...
• odbiera ramki APRS od klientów TCP
• parsuje pozycje, obiekty i wiadomości
• rozsyła odebrane i wygenerowane ramki do innych podłączonych klientów

To jest obecnie najwygodniejsza ścieżka do testów z wieloma klientami SARTrack w LAN.

SARTrack APRS client

Adapter sartrack.aprs_server_client potrafi połączyć się do zewnętrznego serwera APRS-IS i przekazywać odebrane ramki APRS do wewnętrznego routera.

Natywny SARTrack TCP server

Adapter sartrack.tcp_server nasłuchuje prostych rekordów tekstowych SARTrack. Parser akceptuje kilka formatów:

• POS|ID|LAT|LON|komentarz
• MSG|ID|TARGET|tresc
• warianty rozdzielane przecinkami
• warianty rozdzielane spacjami
• warianty key=value

Obsługiwane są rekordy pozycji i wiadomości.

Meshtastic TCP

Adapter mesh.adapter wspiera:

• połączenie TCP z radiem / daemonem Meshtastic
• cichy start połączenia i heartbeat-safe wrapper
• reconnect z konfigurowalnym backoffem
• odbiór tekstu i pozycji z Meshtastic
• wysyłkę wiadomości tekstowych
• wysyłkę pozycji jako:
  • waypointy
  • albo tekstowe payloady APRS_POS|...
• mapowanie APRS callsignów do node ID na podstawie aliasów i informacji z sieci
• prostą ochronę przed echem mostka

Jeżeli wiadomość APRS ma target, adapter próbuje wysłać ją bezpośrednio do odpowiedniego node Meshtastic. Jeśli mapowanie nie istnieje, wiadomość jest odrzucana z ostrzeżeniem w logu.

CoT

Adapter cot.cot jest obecny jako rozszerzalny stub. Projekt generuje kanoniczne dane dla przyszłego eksportu CoT, ale nie jest to jeszcze pełna integracja z TAK Server.

Parser APRS

W tej wersji parser APRS obsługuje:

• pozycje ! i =
• obiekty ;
• wiadomości :

Rozpoznawane podtypy wiadomości:

• private_message
• ack
• encrypted_message
• group_message
• bulletin
• ping
• query
• status_response

Dodatkowo parser zachowuje:

• symbol_table
• symbol_code
• object_timestamp_raw
• znormalizowany object_timestamp_utc
• nazwę taktyczną z komentarza [:nazwa
• owner_callsign i object_name dla obiektów

Parser jest tolerancyjny:

• błędne ramki są odrzucane bez crasha procesu
• nieobsługiwane payloady są logowane ostrzeżeniem
• duplikaty są odfiltrowywane w routerze

Panel operatorski

GUI startuje jako lokalny serwer HTTP oparty o FastAPI i uvicorn.

Funkcje panelu:

• status komponentów
• liczniki zdarzeń i duplikatów
• lista ostatnich zdarzeń
• inspektor pełnego rekordu zdarzenia
• logi z filtrowaniem po poziomie i loggerze
• podgląd błędów
• runtime update konfiguracji wybranych adapterów
• ręczny reconnect adapterów
• testowe wysyłanie pozycji i wiadomości z GUI
• gotowe presety testowe
• podgląd aktywnych klientów lokalnego serwera APRS-IS

Najważniejsze endpointy:

• GET /api/status
• GET /api/events/recent
• GET /api/events/{event_id}
• GET /api/logs
• GET /api/errors
• GET /api/adapters
• POST /api/adapters/{name}/config
• POST /api/adapters/{name}/reconnect
• POST /api/test/send-position
• POST /api/test/send-message

Domyślny adres GUI:

• http://127.0.0.1:8080

Konfiguracja

Cała konfiguracja startowa jest trzymana w config.py.

Najważniejsze sekcje:

• AGWPE
• AGWPE_SERVER
• APRS_IS_SERVER
• KISS
• SARTRACK_TCP
• SARTRACK_APRS
• COT
• GUI
• LOGGING
• DEMO
• MESH_ADAPTERS
• MESH_CALLSIGN_ALIASES

Wybrane zmiany wprowadzone z GUI są zapisywane z powrotem do config.py, więc przetrwają restart procesu.

Domyślne porty i ustawienia

Aktualne wartości domyślne z config.py:

• AGWPE: 127.0.0.1:8000, domyślnie wyłączony
• AGWPE_SERVER: 0.0.0.0:8002, domyślnie wyłączony
• APRS_IS_SERVER: 0.0.0.0:10152, domyślnie włączony
• KISS: 127.0.0.1:8001
• SARTRACK_TCP: 0.0.0.0:8005, domyślnie wyłączony
• SARTRACK_APRS: 127.0.0.1:10152, domyślnie wyłączony
• GUI: 127.0.0.1:8080, domyślnie włączone
• COT: domyślnie wyłączony
• MESH_ADAPTERS: jedna definicja mesh4405, domyślnie wyłączona, host 192.168.0.117, port 4405

Typowe tryby uruchomienia

1. SARTrack + lokalny APRS-IS server

Najprostszy tryb testowy:

SARTrack -> APRS-IS server -> gateway -> Meshtastic / AGWPE server / CoT

Polecany do:

• testów LAN
• pracy z wieloma klientami
• testowania obiektów APRS
• diagnozowania typów wiadomości

2. SARTrack + Dire Wolf + AGWPE

Klasyczny tryb APRS:

SARTrack -> KISS -> Dire Wolf -> AGWPE -> gateway

Polecany do:

• porównań z klasycznym APRS
• pracy z logami Dire Wolf
• testów kompatybilności z istniejącym stosem AGWPE

3. Meshtastic jako wejście i wyjście

Możliwy jest też ruch z sieci Meshtastic do routera i dalej do aktywnych adapterów APRS:

Meshtastic -> gateway -> APRS-IS / AGWPE server

W tym trybie kluczowe jest poprawne mapowanie callsignów do node ID.

Szybki start

Windows PowerShell

py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python .\main.py

Linux / macOS

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

Wymagania

Pakiety z requirements.txt:

• meshtastic
• fastapi
• uvicorn
• paho-mqtt
• pytak

Zalecany Python:

• 3.11+

Logowanie

Logi są zapisywane do pliku i równolegle trafiają do StateStore, z którego korzysta GUI.

Przydatne miejsca:

• logs/gateway.log
• panel logów w GUI

Przykładowe logger names:

• main
• router
• agwpe
• agwpe.server
• aprs.is
• aprs.parser
• sartrack.tcp
• sartrack.aprs
• meshtastic.mesh4405
• cot
• gui

Testy

Repo zawiera testy parsera APRS w tests/test_aprs_parser.py.

Obecnie pokrywają między innymi:

• obiekty APRS z różnymi symbolami
• nazwy taktyczne
• timestampy obiektów
• wiadomości prywatne
• ack
• wiadomości szyfrowane SARTrack
• wiadomości grupowe
• bulletiny
• PING
• ?APRSS
• odpowiedzi statusowe SARTrack

Uruchomienie:

python -m unittest tests.test_aprs_parser

Ograniczenia

• CoT nadal jest stubem, nie pełną integracją TAK
• mapowanie APRS target -> Meshtastic node zależy od aliasów lub danych poznanych po połączeniu
• KISS ma konfigurację, ale nie jest osobnym aktywnym adapterem runtime w main.py
• nie wszystkie scenariusze interoperacyjności Meshtastic są jeszcze domknięte
• GUI jest narzędziem operatorskim i nadal ewoluuje

Przydatne pliki na start

• main.py
• config.py
• core/model.py
• core/router.py
• core/state.py
• aprs/parser.py
• aprs/is_server.py
• aprs/agwpe_server.py
• mesh/adapter.py
• sartrack/parser.py
• gui/server.py

Licencja

Repozytorium nie zawiera jeszcze pliku licencji.