Námořní integrace: skóre důvěryhodnosti na můstku
Námořní skóre důvěryhodnosti Kshana (MARITIME-TRUST.md) je dostupné ze softwaru, který už plavci používají: plugin serveru Signal K a OpenCPN přes NMEA v režimu brány po TCP. Referenční sestava ho nasadí na malý počítač vedle přijímače.
Software pouze poradního charakteru. Kshana není typově schválené navigační zařízení (IEC 61108, IEC 61162) a nebyl posuzován podle žádné výkonové normy. Vše na této stránce je pomůckou pro úsudek navigátora. Za bezpečnou navigaci plavidla a za jakékoli rozhodnutí spolehnout se na fix, nebo se na něj přestat spoléhat, zůstává odpovědný provozovatel. Nic zde nevysílá a nic zde neučiní fix přesnějším.
| Součást | Kde | Stav ve verzi 0,35 |
|---|---|---|
| Zásuvný modul Signal K | integrations/signalk/ |
dodáno, jednotkově testováno na zaznamenaném syntetickém výstupu; nepublikováno do npm |
| OpenCPN přes NMEA v režimu brány po TCP | integrations/opencpn/ |
dodáno a testováno (přehrání na straně příjemce); samotné uživatelské rozhraní OpenCPN žádný test neovládá |
| Nativní plugin OpenCPN s panelem skóre | integrations/opencpn/plugin/ |
sestaveno, logika jednotkově testována a spuštěna uvnitř OpenCPN 5.8.4 pod virtuálním displejem (důkazy v integrations/opencpn/evidence/); nebalíčkováno pro správce pluginů; bude dodáno až po revizi |
| Referenční sestava | deploy/reference-build/ |
díly, kroky pro OS, jednotky systemd (zkontrolováno nanečisto), možnost kontejneru; netestováno na plavidle |
Vše čte jedinou věc: výstup kshana receiver-trust live (řádky JSON, věta $PKSHT, brána). Formáty přenosu jsou v MARITIME-TRUST.md. Plugin Signal K drží svou znalost o nich v jediném souboru, integrations/signalk/lib/adapter.js; změna formátu je úprava jednoho souboru.
Zásuvný modul Signal K#
Žádné závislosti npm. Samotný plugin běží na Node 18 nebo novějším; současná vydání signalk-server vyžadují Node 22 nebo novější, takže v praxi použijte 22. Zkopírujte nebo odkazem připojte integrations/signalk/ do adresáře node_modules serveru (například ~/.signalk/node_modules/signalk-kshana-trust), restartujte server a zapněte Kshana GNSS trust v části Server, Plugin Config.
Odkud epochy pocházejí (source)#
source |
Co plugin dělá |
|---|---|
spawn-signalk-nmea (výchozí) |
Spouští kshana receiver-trust live <sessionFile> a každou surovou větu NMEA 0183, kterou server přijme (událost nmea0183 serveru), zapisuje na jeho standardní vstup. Pokud skončí, restartuje jej s prodlevou | Používejte jej pouze na serveru s jediným zdrojem NMEA: předává každou větu od každého poskytovatele, promíchaně, takže druhý přijímač GNSS nebo AIS vypadá jako jeden přijímač, jehož poloha skáče, a může být ohodnocen jako spoofing. Při více než jednom zdroji použijte spawn-args s vlastním proudem --tcp daného přijímače nebo tcp-pksht z brány. |
spawn-args |
Spouští kshana receiver-trust live <sessionFile> <inputArgs...>, například ["--tcp","192.0.2.10:10110"] nebo ["--udp","10110"] |
tcp-json |
Připojí se k proudu řádků JSON, které zapisuje kshana (například z relay v integrations/opencpn/) |
tcp-pksht |
Připojí se k proudu NMEA (například k výstupu brány služby nebo kontejneru v referenční sestavě, port 10110) a čte pouze jeho věty $PKSHT |
Proud, který je již podvržen v okamžiku, kdy se monitor poprvé připojí, nemá čistý základ (prvních calibration_s sekund se nikdy nehodnotí). Spusťte jej před plavbou.
Zveřejněné cesty#
Každá epocha aktualizuje (zdroj kshana-trust):
| Cesta | Hodnota |
|---|---|
navigation.gnss.kshana.band |
calibrating, nominal, degraded nebo untrusted |
navigation.gnss.kshana.score |
0 až 100 nebo null během kalibrace |
navigation.gnss.kshana.reasons |
[{monitor, points}], od největšího: které kontroly skóre snížily |
navigation.gnss.kshana.alarms |
monitory, které jsou aktuálně nad svým prahem |
navigation.gnss.kshana.gate |
off, passed nebo withheld (když brána běží jinde; null z $PKSHT, pokud chybí) |
navigation.gnss.kshana.reportedPosition |
{latitude, longitude, altitude}: poloha, kterou testovaný přijímač v dané epoše hlásil (schéma JSON 1,1 nebo novější; nezveřejňuje se, pokud ji proud neobsahuje, například z $PKSHT nebo starší verze kshana). Pouze kontext důvěry: plugin nikdy nezapisuje navigation.position, takže cesta vlastní polohy plavidla zůstává nedotčena |
notifications.navigation.gnss.kshana.trust |
vyvolá se při změně stavu: {state, method, message} |
Plugin také jednou při startu odešle metadata Signal K pro tyto cesty. score je skóre důvěryhodnosti Kshana od 0 do 100, skóre, nikoli poměr ani pravděpodobnost, takže nemá jednotku SI; jeho metadata uvádějí rozsah, popis a zóny, které sledují prahy níže. reasons[].points jsou body skóre odečtené z tohoto skóre od 0 do 100.
Oznámení je normal, alert, warn nebo alarm. Zruší se zveřejněním stavu normal, nikoli null: příjemce, který za zrušené považuje pouze null, by měl za zrušené považovat i normal. Ve výchozím nastavení dává pásmo degraded hodnotu warn a pásmo untrusted hodnotu alarm, s method: ["visual","sound"]. Sníží se po clearAfterEpochs epochách v lepším stavu. Pokud po dobu staleAfterS sekund nepřijde žádná epocha, varuje, že skóre se neaktualizuje. Kalibrace nikdy oznámení nevyvolá. Zdroj $PKSHT neobsahuje seznam alarms (věta nese pouze pásmo, skóre a dva hlavní důvody).
Konfigurace (každý práh)#
| Klíč | Výchozí hodnota | Význam |
|---|---|---|
source |
spawn-signalk-nmea |
viz výše |
command |
kshana |
spustitelný soubor (režimy spawn). Spouští libovolný spustitelný soubor jako uživatel serveru: konfiguraci pluginu by měl moci měnit pouze správce serveru Signal K |
sessionFile |
/etc/kshana/session.toml |
meze plavidla, prahy a váhy skóre (režimy spawn) |
inputArgs |
[] |
argumenty přidané k kshana receiver-trust live <sessionFile> v obou režimech spawn: vstup pro spawn-args, další přepínače, například --replay (uložený záznam přiváděný rychleji než v reálném čase) pro spawn-signalk-nmea. Plugin odmítá --gate, --listen, --json a --pksht (čte JSON z kshana na standardním výstupu) a pro spawn-signalk-nmea také vstupní přepínače (--stdin, --file, --tcp, --udp, --follow, --from-end) |
host, port |
127.0.0.1, 10111 |
Režimy TCP (brána slouží na 10110: port nastavte pro tcp-pksht) |
thresholdMode |
band |
band: pásmo, které Kshana hlásí, s hranicemi v souboru relace. score: dvě skóre níže |
warnBelowScore |
90 |
režim score: pod touto hodnotou je stav degradedState (výchozí hranice Kshana pro nominal) |
alarmBelowScore |
55 |
režim score: pod touto hodnotou je stav alarm (výchozí hranice Kshana pro degraded) |
degradedState |
warn |
stav pro pásmo degraded: normal, alert nebo warn |
raiseAfterEpochs |
1 |
po sobě jdoucí epochy v horším stavu, než se oznámení vyvolá |
clearAfterEpochs |
10 |
po sobě jdoucí epochy v lepším stavu, než se oznámení sníží |
staleAfterS |
10 |
varovat, pokud po tuto dobu nepřijde žádná epocha; 0 to vypne |
method |
["visual","sound"] |
způsoby oznámení |
Plugin nefunguje jako brána: nikdy fix nezmění. Označení fixu za neplatný pro kartografický systém je brána, níže.
Testy#
cd integrations/signalk && npm testnode:test, žádné závislosti, žádná síť kromě 127.0.0.1. Testy zpracují a přehrají 66epochový výřez řádků JSON a vět $PKSHT, které kshana receiver-trust live zapsal pro syntetickou baltskou ukázku (vymyšlená data, pouze text), a kontrolují shodu obou formátů, chování držení a zrušení, režim skóre, zastarání a tři vstupní cesty proti místnímu proudu a zástupnému podřízenému procesu. Tyto testy nespouštějí skutečný server Signal K; to dělá samostatný skriptovaný běh, viz níže.
Běh ve skutečném serveru Signal K#
integrations/signalk/evidence/ obsahuje skript, který načte plugin do připnutého balíčku signalk-server 2.33.0 (v soukromém jmenném prostoru sítě pouze se smyčkou loopback) a zaznamená, co ukazují vlastní rozhraní REST a WebSocket serveru. Cesty důvěry se objeví, oznámení přejde na warn, alarm, normal (po držení) a znovu na warn, když data přestanou přicházet, a se skutečným kshana, krmeným vlastním vstupem NMEA serveru, zveřejnil také reportedPosition, nikdy navigation.position. Jedna verze serveru, jeden běh, žádné skutečné plavidlo; omezení a postup reprodukce jsou v README s důkazy.
OpenCPN#
OpenCPN čte NMEA ze sítě a kshana receiver-trust live --gate dokáže filtrovaný proud sám nabízet na portu TCP.
Doporučeno: přímé připojení.
some-nmea-source | kshana receiver-trust live session.toml --gate --listen tcp:10110(some-nmea-source je sériový port přijímače čtený pomocí stty a cat, multiplexor, nebo vstupy --tcp/--udp samotného kshana; kshana-gate.service z referenční sestavy to dělá pod systemd.) --listen tcp:<port> se naváže na adresu loopback; může se připojit libovolný počet klientů pouze pro čtení a klient, který nestíhá, je odpojen bez zdržení ostatních.
Alternativa: relay. integrations/opencpn/nmea-tcp-relay.mjs je rozdvojovač v Node bez závislostí, který totéž dělá pro kshana bez --listen nebo nabízí jakýkoli jiný proud řádků (možnost kontejneru jej používá pro epochy JSON):
some-nmea-source | kshana receiver-trust live session.toml --gate --json trust.jsonl \
| node integrations/opencpn/nmea-tcp-relay.mjs --listen 10110Předává bajty beze změny, pouze celé řádky, a odpojí klienta, který nečte. Dávejte přednost přímému připojení: o jeden proces méně v řetězci.
V OpenCPN: Options, Connections, Add Connection, Network, protokol TCP, adresa 127.0.0.1, port 10110, směr Input. Dokud důvěra nezkolabovala, je proud vlastním proudem přijímače plus jedna věta $PKSHT na cyklus. Po zkolabování má předávaná GGA kvalitu 0, RMC stav V a indikátory režimu hlásí žádný fix, s přepočítanými kontrolními součty: zařízení vidí, že přijímač sám prohlašuje fix za neplatný, a spustí vlastní alarm. Věty $PKSHT jsou vidět v ladicím okně NMEA v OpenCPN (Options, Connections, „NMEA debug window“). Pole polohy zůstávají tak, jak byla přijata.
Než se na to spolehnete, přečtěte si „Gate mode“ v MARITIME-TRUST.md: je volitelný, přidává latenci (cyklus se drží, dokud není jeho epocha ohodnocena), je jediným bodem v řetězci a může zadržet dobrý fix stejně jako propustit padělaný.
Testy#
cd integrations/opencpn && npm testtest/relay.test.mjs přehrává zaznamenaný výřez syntetického filtrovaného proudu (186 vět kolem okamžiku, kdy důvěra zkolabuje, zapsaných příkazem kshana receiver-trust live --gate) skrz relay po skutečném socketu TCP a kontroluje, co příjemce dostane: proud bajt po bajtu při libovolném dělení na části; platné kontrolní součty u každé věty, včetně přepsaných; shodu GGA a RMC, platné a poté neplatné bez blikání; jednu větu $PKSHT na cyklus s polem brány W přesně tam, kde je fix neplatný; dva příjemce shodné; částečný řádek nikdy nepředaný. Kontroluje se proud, který OpenCPN dostane, nikoli vlastní obrazovka OpenCPN.
Kontrola od začátku do konce se skutečným binárním souborem, není součástí výchozích testů (vyžaduje sestavený kshana):
KSHANA_BIN=target/release/kshana npm run e2e # kshana --gate --listen | TCP consumer; the consumer's bytes must equal the gate's stdout
KSHANA_BIN=target/release/kshana npm run e2e -- relay # kshana --gate | relay | TCP consumerOba spouštějí hodinovou syntetickou ukázku a kontrolují, že fix je nejprve platný, poté neplatný, s větou $PKSHT na epochu.
Nativní plugin#
integrations/opencpn/plugin/ je panel skóre pro OpenCPN (skóre, pásmo, brána, hlavní důvody, upozornění, když se důvěra změní na untrusted), který čte $PKSHT z vlastního proudu NMEA OpenCPN, takže nepotřebuje žádné jiné připojení než výše uvedené. Sestavuje se pomocí CMake proti hlavičce API pluginů OpenCPN (přibalené, s commitem zdroje) a wxWidgets; ctest spouští testy logiky bez wx a kontroluje, že knihovna exportuje vstupní body, které OpenCPN vyhledává. Byl spuštěn uvnitř OpenCPN 5.8.4 pod virtuálním displejem na syntetickém filtrovaném proudu (OpenCPN předal $PKSHT pluginu, panel zčervenal a vlastní poloha OpenCPN zamrzla, když se brána zapnula; snímky obrazovky, log a skript v integrations/opencpn/evidence/), ale ne na skutečné pracovní ploše, jiných verzích ani platformách a není balíčkován pro správce pluginů OpenCPN. Viz README.md pluginu. Je licencován GPL-3.0-or-later, na rozdíl od zbytku repozitáře (LICENSING.md).
Snímky obrazovky z toho běhu, v integrations/opencpn/evidence/ (jeden běh, OpenCPN 5.8.4 pod virtuálním displejem, syntetická data; omezení uvádí README.md):
Ukazují vedení potrubí a filtrovaný fix, který se dostává do OpenCPN, nikoli že by jakýkoli alarm byl včasný nebo správný pro skutečné plavidlo. Software pouze poradního charakteru, nikoli typově schválené zařízení.
Referenční sestava#
deploy/reference-build/: obecný seznam dílů, nastavení OS, dvě jednotky systemd (poradní monitor a volitelná brána), možnost kontejneru a zapojení Signal K. deploy/reference-build/check-units.sh spouští systemd-analyze verify na jednotkách, aniž cokoli spustí.
Omezení#
- Skóre je tak dobré, jako kontroly, které za ním stojí a které sledují fyziku lodi a její další senzory; sebekonzistentní padělek se souhlasnými hodinami monitory pouze s NMEA nevidí (
MARITIME-TRUST.md). Nepřítomnost alarmu není důkazem dobrého fixu. - Žádná hodnota na této stránce není změřená míra detekce ani falešných poplachů. Výše uvedené testy kontrolují vedení potrubí na syntetickém textu; nic nevypovídají o tom, jak si jakýkoli monitor vede proti skutečné interferenci.
- Nejde o typově schválené zařízení; odpovědný zůstává provozovatel.