Dokumentacja Techniczna i Podręcznik Użytkownika

1. Wymagania systemowe i architektura sprzętowa

SPLogbook jest wysoce zoptymalizowaną, natywną aplikacją napisaną w języku Rust (edycja 2024) z interfejsem graficznym renderowanym natywnie przez bibliotekę egui / eframe ze sprzętowym przyspieszeniem GPU (wgpu/OpenGL). Aplikacja nie korzysta z powłok Electron, WebView ani środowisk uruchomieniowych takich jak Node.js czy Java.

2. Instalacja i pierwsze uruchomienie

Program jest dostarczany jako przenośny pakiet (portable). Nie wymaga instalatora systemowego ani modyfikacji rejestru Windows.

2.1 System Windows (x64)

1. Pobierz archiwum SPLogbook-Windows-x64.zip z oficjalnej sekcji pobierania lub z GitHub Releases.
2. Zweryfikuj sumę kontrolną SHA-256 w konsoli PowerShell:
   Get-FileHash .SPLogbook-Windows-x64.zip -Algorithm SHA256
   Oczekiwany hash dla wersji v1.2.0: bd2164e3f73d779b4f8ded93310f6d990db978a67f840a70b4a834eb3b2da4a0.
3. Rozpakuj archiwum do wybranego katalogu (np. C:SPLogbook). Unikaj katalogu C:Program Files, jeżeli chcesz przechowywać bazę danych lokalnie w katalogu programu bez praw administratora.
4. Uruchom SPLogbook.exe.

2.2 System Linux (x86_64)

W systemach Linux wypakuj archiwum tar.gz i nadaj uprawnienia wykonywalności:

tar -xvf SPLogbook-Linux-x86_64.tar.gz
cd SPLogbook
chmod +x SPLogbook
./SPLogbook

3. Konfiguracja operatora i stacji

Podczas pierwszego uruchomienia SPLogbook wyświetla kreator wstępnej konfiguracji stacji. Wszystkie parametry można w każdej chwili zmienić w menu Ustawienia -> Stacja i Operator.

• Znak stacji (Station Call): Główny znak wywoławczy stacji używany jako domyślny nadawca w logu (np. SP6IN).
• Lokator QTH (Maidenhead Grid): 4- lub 6-znakowy lokator geograficzny (np. JO80is). Służy do automatycznego obliczania azymutu rotora antenowego oraz odległości do korespondenta.
• Operator (Operator Call): Znak bieżącego operatora logującego łączności (kluczowe przy pracy stacji klubowej lub pracy Multi-Op).
• Gmina PGA (SPPA): Kod polskiej gminy dla programu Dyplomu PGA (np. WA01). Wprowadzenie kodu ułatwia korespondentom zaliczenie gminy podczas aktywacji.
• Profile stacji: Możliwość zdefiniowania wielu profili (np. Home Station, SOTA Portable /P, Field Day). Zmiana profilu jednym kliknięciem aktualizuje znak, lokator, moc oraz używane radio.

4. Wprowadzanie i rejestracja łączności (QSO)

Okno wprowadzania QSO zostało zaprojektowane z myślą o ergonomii zawodniczej i pracy w warunkach polowych. Obsługa odbywa się w 100% z poziomu klawiatury bez konieczności sięgania po mysz.

4.1 Super Check Partial (SCP) i autouzupełnianie

Wbudowana baza Super Check Partial (SCP) w formacie binarnym przeszukuje w ułamku milisekundy tysiące aktywnych znaków. W miarę wpisywania kolejnych znaków w polu wywoławczym na dolnym pasku pojawiają się pasujące znaki z bazy SCP, poprzednie łączności (B4/Dupe alert) oraz historia korespondenta z lokalnej bazy.

4.2 Skróty klawiszowe operatora

5. Podsystem NATIVE-CAT (Sterowanie Radiem)

SPLogbook v1.2.0 zawiera całkowicie przepisany, natywny silnik NATIVE-CAT zoptymalizowany pod kątem minimalnych opóźnień (asynchroniczny model Tokio, ramkowanie bezalokacyjne). Silnik obsługuje jednocześnie 8 protokołów sterowania sprzętowego.

5.1 RigHub i Dual-Radio (Radio 1 & Radio 2)

Moduł RigHub zarządza wieloma radiostacjami podłączonymi do jednego komputera. Umożliwia niezależną konfigurację parametrów komunikacji (port szeregowy COM/tty, baudrate, protokół) dla Radia 1 (Główne) oraz Radia 2 (Sub/In-Band).

5.2 TxArbiter & Interlock (Ochrona przed równoczesnym nadawaniem)

W pracy wieloradialnej (SO2R — Single Operator 2 Radios lub Multi-Operator) kluczowe jest wyeliminowanie ryzyka przypadkowego równoczesnego załączenia nadawania (TX) na obu radiach, co mogłoby doprowadzić do uszkodzenia stopni odbiorczych lub naruszenia regulaminu zawodów.

TxArbiter to mechanizm programowej blokady (software interlock) operujący w przestrzeni mikrosekundowej. Jeżeli Radio 1 przechodzi w stan TX (nadawanie), żądanie PTT dla Radia 2 zostaje natychmiast zablokowane z rejestracją zdarzenia w audycie bezpieczeństwa.

5.3 Hamlib rigctld (:4532) & Hamlib Proxy (:4534)

SPLogbook potrafi łączyć się ze standardowym demonem rigctld sieciowo na domyślnym porcie 4532. Ponadto SPLogbook udostępnia własny wbudowany Hamlib Proxy Server nasłuchujący na porcie 4534.

5.4 Icom CI-V

Natywna implementacja protokołu Icom CI-V obsługuje pełny pakiet ramek binarnych FE FE ... FD.

• Adres CI-V: Konfigurowalny adres heksadecymalny radia (np. 0x94 dla IC-7300, 0xA2 dla IC-7610, 0x70 dla IC-7000).
• Tryb Transceive: Obsługa automatycznych asynchronicznych rozgłoszeń zmian częstotliwości z pokrętła VFO radia.
• Prędkość transmisji: Obsługa baudrate od 4800 do 115200 bps.

5.5 Kenwood PC Control

Protokół tekstowy ASCII oparty na dwuliterowych komendach zakończonych średnikiem (FA;, FB;, MD;, TX;, RX;). Pełne wsparcie dla transceiverów Kenwood TS-590S/SG, TS-890S, TS-990S oraz starszych modeli serii TS-480 i TS-2000.

5.6 Yaesu CAT & CP2105 Dual COM

Wsparcie dla nowoczesnych protokołów Yaesu (FT-dx10, FT-710, FT-991A, FTDX101D) oraz modeli klasycznych (FT-857D, FT-897D, FT-450D).

5.7 Elecraft K3/K4

Rozszerzony zestaw poleceń dla transceiverów Elecraft K3, K3S, KX3 oraz K4. Pełna obsługa odczytu VFO-A, VFO-B, RIT/XIT oraz szybkiego przełączania split.

5.8 FlexRadio SmartSDR (TCP :4992)

Bezpośrednia integracja sieciowa z radiostacjami programowalnymi FlexRadio serii 6000/8000 przez protokół SmartSDR TCP na porcie 4992. Umożliwia śledzenie wielu wycinków odbiornika (Slices) oraz synchronizację częstotliwości bez instalowania wirtualnych portów szeregowych CAT na Windowsie.

5.9 FLRig XML-RPC (:12345)

Mostek protokołu XML-RPC łączący SPLogbook z popularnym programem sterującym FLRig na domyślnym porcie 12345. Doskonałe rozwiązanie dla operatorów korzystających z niestandardowych interfejsów lub nietypowych transceiverów wspieranych przez bibliotekę W1HKJ.

5.10 TCI WebSocket (Expert Electronics / SunSDR)

Transceiver Control Interface (TCI) oparty na protokole WebSocket nasłuchującym domyślnie na porcie 40001. Zapewnia błyskawiczną dwukierunkową wymianę danych z oprogramowaniem ExpertSDR (SunSDR2 PRO, SunSDR2 DX, MB1) z zerowym opóźnieniem.

5.11 Status walidacji Hardware-in-the-Loop (Stage 7B HIL)

6. Szyfrowana synchronizacja LAN Multi-Op v2

Protokół synchronizacji lokalnej SPLogbook LAN Sync v2 powstał z myślą o pracy zespołowej w zawodach (stacje Multi-Single, Multi-Two, Multi-Multi) oraz ekspedycjach polowych. Działa w architekturze rozproszonej bez konieczności konfiguracji zewnętrznych serwerów bazodanowych MySQL czy PostgreSQL.

6.1 Architektura sieciowa

• TCP Port 4550 (Transmisja danych): Zabezpieczony kanał przesyłania pakietów synchronizacyjnych QSO, blokad pasm oraz statusu operatorów.
• UDP Port 4551 (Wykrywanie stacji): Rozgłoszeniowy mechanizm autowykrywania węzłów SPLogbook w lokalnej podsieci LAN bez konieczności ręcznego wpisywania adresów IP.

6.2 Kryptografia i bezpieczeństwo transmisji

Wszystkie pakiety w sieci LAN są szyfrowane symetrycznie algorytmem XChaCha20-Poly1305 (uwierzytelnione szyfrowanie AEAD z 192-bitowym nonce). Klucz sesyjny jest wyprowadzany z hasła współdzielonego za pomocą funkcji Argon2id (odpornej na ataki GPU/ASIC).

Integralność sekwencji zabezpiecza 64-bitowy licznik monotoniczny, uniemożliwiający ataki powtórzeniowe (replay attacks) oraz gwarantujący automatyczne pobranie brakujących łączności (catch-up log) po chwilowym zerwaniu połączenia Wi-Fi/Ethernet.

7. Zawody i eksport Cabrillo 3.0

SPLogbook zawiera dedykowany moduł zawodniczy wspierający najważniejsze zawody krajowe i międzynarodowe:

• SP DX Contest (SPDXC) — automatyczne rozliczanie polskich województw i stacji zagranicznych.
• SP DX RTTY Contest — dedykowany moduł dla łączności dalekopisowych.
• PGA Round (Zawody PGA) — obsługa wymiany raportów z gminami i prefiksami.
• CQ World Wide DX Contest (CW / SSB) — podział na strefy CQ, kraje DXCC.
• CQ WPX Contest (CW / SSB / RTTY) — prefiksy jako mnożniki.
• IARU HF World Championship — obsługa stacji HQ i stref ITU.
• ARRL International DX Contest — wymiana stanów USA / prowincji Kanady.

7.1 Licznik tempa (Rate Meter) i weryfikacja mnożników

Podczas trwania zawodów okno informacyjne prezentuje bieżące tempo pracy w oknach 10-minutowych, 60-minutowych oraz przewidywany wynik punktowy. Podwójne łączności (duplikaty) są natychmiast sygnalizowane wizualnie i dźwiękowo.

7.2 Eksport do formatu Cabrillo 3.0

Po zakończeniu zawodów program generuje w 100% poprawny plik w formacie Cabrillo v3.0, gotowy do wysłania przez roboty logów zawodów (tzw. log-checking robots) bez konieczności ręcznej edycji nagłówków START-OF-LOG i END-OF-LOG.

8. Moduł dyplomowy i 2477 gmin PGA

SPLogbook integruje kompletną, zweryfikowaną bazę 2477 gmin Rzeczypospolitej Polskiej według oficjalnego podziału administracyjnego Głównego Urzędu Statystycznego (TERYT) oraz regulaminu programu dyplomowego Polska Gmina Award (PGA).

Wpisanie znaku polskiej stacji lub prefiksu automatycznie podpowiada przypisaną gminę, powiat i województwo. Moduł statystyk dyplomowych pozwala natychmiast sprawdzić stan potwierdzeń dla programów:

• PGA (Polska Gmina Award) — stan zaliczenia 2477 gmin w podziale na pasma i emisje.
• SPPA (Polish Park Award) — łączności z obszarów parków narodowych i krajobrazowych.
• DXCC (Stan potwierdzeń 340 aktualnych podmiotów DXCC).
• WAZ (Worked All Zones) — 40 stref magazynu CQ.
• WAS (Worked All States) — 50 stanów USA.
• Kluby telegraficzne — dyplomy SPCWC, FOC, HSC, AGCW.

9. Emisje cyfrowe (WSJT-X / JTDX / JS8Call)

SPLogbook posiada wbudowany odbiornik pakietów UDP Broadcast (domyślny port 2237), w pełni zgodny z protokołem komunikacyjnym aplikacji WSJT-X, JTDX oraz JS8Call.

1. W programie WSJT-X przejdź do: File -> Settings -> Reporting.
2. Zaznacz opcję Prompt me to log QSO oraz Accept UDP requests.
3. Ustaw UDP Server: 127.0.0.1 oraz UDP Server port: 2237.
4. Z chwilą zatwierdzenia łączności w oknie WSJT-X, rekord QSO zostaje automatycznie przekazany do SPLogbooka, zweryfikowany z bazą PGA/DXCC i trwale zapisany w bazie SQLite bez potrzeby ręcznego importu plików ADIF.

10. Karty QSL i wektorowy druk etykiet Avery PDF

Zamiast korzystać z zewnętrznych, zawodnych arkuszy kalkulacyjnych, SPLogbook posiada wbudowany silnik generowania wektorowych dokumentów PDF oparty na bibliotece printpdf z precyzyjną siatką typograficzną w przestrzeni barw CMYK.

Obsługiwane szablony arkuszy A4:

• Avery 3474: 70.0 × 37.0 mm (24 etykiety na arkusz, siatka 3 × 8) — standard biura PZK.
• Avery 3425: 105.0 × 57.0 mm (10 etykiet na arkusz, siatka 2 × 5) — etykiety z pełnym raportem Multi-QSO.
• Avery 7160: 63.5 × 38.1 mm (21 etykiet na arkusz, siatka 3 × 7).

Generator umożliwia drukowanie potwierdzeń pojedynczych oraz zbiorczych (do 5 łączności na jednej etykiecie dla stacji DX-owych), automatycznie oznaczając w bazie łączności jako wysłane (QSL_SENT).

11. Rotor antenowy i śledzenie satelitów

Moduł pozycjonowania anten integruje się z protokołem Hamlib rotctld na porcie 4533. Po wprowadzeniu znaku lub lokatora QTH system automatycznie wylicza azymut metodą koła wielkiego (Great Circle Beam Heading) i umożliwia przestawienie rotora za pomocą jednego skrótu klawiszowego.

Dla łączności przez satelity LEO (SO-50, AO-91, AO-92) oraz transponder liniowy QO-100 moduł satelitarny pobiera aktualne elementy dwuliniowe (TLE) z bazy CelesTrak, obliczając elewację, azymut oraz dynamiczną korekcję efektu Dopplera dla odbiornika i nadajnika radia.

12. Bezpieczeństwo i sejf sekretów (Vault)

SPLogbook stosuje restrykcyjne standardy bezpieczeństwa danych klasy korporacyjnej. Dane uwierzytelniające do serwisów zewnętrznych (takich jak eQSL.cc, ClubLog, LoTW, QRZ.com XML) nigdy nie są zapisywane jawnym tekstem w plikach konfiguracyjnych JSON czy INI.

• OS Keyring: Domyślnie hasła są delegowane do natywnego menedżera poświadczeń systemu operacyjnego (Windows Credential Manager na Windowsie, Secret Service API / libsecret na Linuxie).
• Kryptograficzny sejf awaryjny (vault.enc): W środowiskach bez działającego daemona kluczy tworzony jest plik vault.enc szyfrowany symetrycznie algorytmem ChaCha20-Poly1305 z kluczem wyprowadzonym za pomocą Argon2id.
• Uprawnienia plików: W systemach Unix plik sejfu i bazy danych jest tworzony z rygorystycznymi uprawnieniami 0o600 (odczyt i zapis wyłącznie dla właściciela procesu).
• Poufność telemetrii: Program posiada zerową telemetrię. Żadne dane o łącznościach, sprzęcie ani adresach IP nie są wysyłane do autorów programu ani podmiotów trzecich.

13. Baza SQLite WAL i kopie zapasowe

Silnik pamięci trwałej bazuje na transakcyjnym silniku SQLite 3 skonfigurowanym w przemysłowym trybie WAL (Write-Ahead Logging):

Dzięki temu operacje zapisu łączności nigdy nie blokują operacji odczytu, filtrowania ani przeszukiwania bazy, zapewniając zerowe ryzyko uszkodzenia pliku bazy danych nawet w przypadku nagłego zaniku zasilania radioshacku podczas zawodów.

13.1 Automatyczne migawki i kopie zapasowe (Backups)

SPLogbook wykonuje automatyczne kopie zapasowe bazy do katalogu backups/:

• Przed każdą operacją importu pliku ADIF.
• Przed wykonaniem masowej aktualizacji statusów dyplomowych.
• Cyklicznie przy każdym zamykaniu programu (z zachowaniem historii ostatnich 10 rotacji).

14. Diagnostyka i rozwiązywanie problemów

Wszystkie zdarzenia systemowe, błędy ramek komunikacyjnych oraz komunikaty diagnostyczne są rejestrowane w pliku dziennika:

• Windows: %APPDATA%\SPLogbook\logs\SPLogbook.log
• Linux: ~/.local/share/SPLogbook/logs/SPLogbook.log

Typowe scenariusze i rozwiązania:

15. Przewodnik dewelopera (Rust 2024)

SPLogbook jest projektem otwartoźródłowym tworzonym z zachowaniem najwyższych rygorów inżynierii oprogramowania. Zapraszamy do współtworzenia kodu!

15.1 Wymagania deweloperskie

• Rust: Wersja stabilna 1.99+ (Rust edycja 2024).
• Menedżer pakietów: Cargo.
• Zależności systemowe Linux: sudo apt install libasound2-dev libudev-dev libfontconfig1-dev libxkbcommon-dev

15.2 Pobranie źródeł i kompilacja

# Klonowanie repozytorium
git clone https://github.com/sp6ina/SPLogbook.git
cd SPLogbook

# Uruchomienie pełnego zestawu 1519 testów
cargo test --all-targets

# Budowanie binarnej wersji zoptymalizowanej (Release LTO)
cargo build --release

15.3 Weryfikacja sygnatury kryptograficznej Ed25519

Wszystkie oficjalne paczki binarne SPLogbook są podpisywane kluczem Ed25519 identyfikatora splogbook-release-2026-01. Plik manifestu release-manifest.json zawiera sumy kontrolne SHA-256 oraz skojarzony plik sygnatury release-manifest.json.sig. Narzędzie weryfikujące można uruchomić poleceniem: