Maritieme integraties: de vertrouwensscore op de brug

De maritieme vertrouwensscore van Kshana (MARITIME-TRUST.md) is bereikbaar vanuit software die schippers al gebruiken: een plug-in voor een Signal K-server en OpenCPN via NMEA in gate-modus over TCP. Een referentiebouw zet haar op een kleine computer naast de ontvanger.

Adviserende software. Kshana is geen typegoedgekeurde navigatieapparatuur (IEC 61108, IEC 61162) en is niet getoetst aan enige prestatienorm. Alles op deze pagina is een hulpmiddel bij het oordeel van de navigator. De exploitant blijft verantwoordelijk voor de veilige navigatie van het vaartuig en voor elke beslissing om op een positiebepaling te vertrouwen of daarmee te stoppen. Niets hier zendt uit, en niets hier maakt een positiebepaling nauwkeuriger.

Alles leest één ding: de uitvoer van kshana receiver-trust live (JSON-regels, de zin $PKSHT, de gate). De draadformaten staan in MARITIME-TRUST.md. De Signal K-plug-in houdt haar kennis daarvan in één bestand, integrations/signalk/lib/adapter.js; een formaatwijziging is een bewerking van één bestand.

Signal K-plug-in#

Geen npm-afhankelijkheden. De plug-in zelf draait op Node 18 of nieuwer; huidige releases van signalk-server vereisen Node 22 of nieuwer, dus gebruik in de praktijk 22. Kopieer of koppel integrations/signalk/ in de node_modules van de server (bijvoorbeeld ~/.signalk/node_modules/signalk-kshana-trust), start de server opnieuw en schakel Kshana GNSS trust in onder Server, Plugin Config.

Waar de epochs vandaan komen (source)#

Een stream die al wordt gespooft wanneer de monitor voor het eerst verbinding maakt, heeft geen schone basislijn (de eerste calibration_s seconden worden nooit gescoord). Start hem vóór de reis.

Gepubliceerde paden#

Elke epoch werkt bij (bron kshana-trust):

De plug-in stuurt bij de start ook eenmalig Signal K-metadata voor deze paden. score is de vertrouwensscore van Kshana van 0 tot 100, een score en geen verhouding of kans, dus zij heeft geen SI-eenheid; haar metadata geeft het bereik, een beschrijving en zones die de onderstaande drempels volgen. reasons[].points zijn scorepunten die van die score van 0 tot 100 worden afgetrokken.

De melding is normal, alert, warn of alarm. Zij wordt gewist door status normal te publiceren, niet null: een consument die alleen null als gewist beschouwt, moet normal ook als gewist beschouwen. Standaard geeft de band degraded warn en de band untrusted alarm, met method: ["visual","sound"]. Zij wordt verlaagd na clearAfterEpochs epochs op een betere status. Als er staleAfterS seconden geen epoch binnenkomt, waarschuwt zij dat de score niet wordt bijgewerkt. Kalibratie geeft nooit een melding. De bron $PKSHT draagt geen lijst alarms (de zin heeft alleen de band, de score en de twee belangrijkste redenen).

Configuratie (elke drempel)#

De plug-in fungeert niet als gate: zij wijzigt nooit een positiebepaling. Een positiebepaling voor een kaartsysteem ongeldig markeren is de gate, hieronder.

Tests#

cd integrations/signalk && npm test

node:test, geen afhankelijkheden, geen netwerk behalve 127.0.0.1. De tests parseren en spelen een uittreksel van 66 epochs af van de JSON-regels en $PKSHT-zinnen die kshana receiver-trust live schreef voor de synthetische Baltic-demo (verzonnen gegevens, alleen tekst), en controleren de overeenstemming tussen de twee formaten, het vasthoud- en wisgedrag, de scoremodus, veroudering en de drie invoerpaden tegen een lokale feed en een stand-in-kindproces. Die tests starten geen echte Signal K-server; een aparte gescripte run doet dat wel, zie hieronder.

Draaien in een echte Signal K-server#

integrations/signalk/evidence/ bevat een script dat de plug-in laadt in het vastgepinde pakket signalk-server 2.33.0 (in een privé-netwerknaamruimte met alleen loopback) en vastlegt wat de eigen REST- en WebSocket-API's van de server tonen. De vertrouwenspaden verschijnen, de melding gaat naar warn, alarm, normal (na het vasthouden) en weer naar warn wanneer de gegevens stoppen, en met de echte kshana, gevoed door de eigen NMEA-invoer van de server, publiceerde hij ook reportedPosition, nooit navigation.position. Eén serverversie, één run, geen echt vaartuig; beperkingen en reproductie in de README van het bewijs.

OpenCPN#

OpenCPN leest NMEA van het netwerk, en kshana receiver-trust live --gate kan de gegate stream zelf op een TCP-poort aanbieden.

Aanbevolen: de directe verbinding.

some-nmea-source | kshana receiver-trust live session.toml --gate --listen tcp:10110

(some-nmea-source is de seriële poort van de ontvanger gelezen met stty en cat, een multiplexer, of de invoer --tcp/--udp van kshana zelf; kshana-gate.service van de referentiebouw doet dit onder systemd.) --listen tcp:<port> bindt het loopback-adres; een willekeurig aantal alleen-lezen clients mag verbinden, en een client die het niet bijhoudt wordt verwijderd zonder de andere te vertragen.

Alternatief: het relay. integrations/opencpn/nmea-tcp-relay.mjs is een afhankelijkheidsvrije Node-fan-out die hetzelfde doet voor een kshana zonder --listen, of een andere regelstream aanbiedt (de containeroptie gebruikt het voor de JSON-epochs):

some-nmea-source | kshana receiver-trust live session.toml --gate --json trust.jsonl \
  | node integrations/opencpn/nmea-tcp-relay.mjs --listen 10110

Het stuurt bytes ongewijzigd door, alleen hele regels, en verwijdert een client die niet leest. Geef de voorkeur aan de directe verbinding: één proces minder in de keten.

In OpenCPN: Options, Connections, Add Connection, Network, protocol TCP, adres 127.0.0.1, poort 10110, richting Input. Zolang het vertrouwen niet is ingestort, is de stream die van de ontvanger zelf, plus een $PKSHT-zin per cyclus. Zodra het is ingestort, heeft de doorgestuurde GGA kwaliteit 0, RMC-status V, en geven de modusindicatoren aan dat er geen positiebepaling is, met opnieuw berekende controlesommen: de apparatuur ziet de ontvanger zelf de positiebepaling ongeldig verklaren en geeft haar eigen alarm. De $PKSHT-zinnen zijn zichtbaar in het NMEA-debugvenster van OpenCPN (Options, Connections, "NMEA debug window"). De positievelden blijven zoals ontvangen.

Lees "Gate mode" in MARITIME-TRUST.md voordat u hierop vertrouwt: het is opt-in, voegt latentie toe (een cyclus wordt vastgehouden totdat haar epoch is gescoord), is één enkel punt in de keten, en kan een goede positiebepaling tegenhouden en een vervalste doorlaten.

Tests#

cd integrations/opencpn && npm test

test/relay.test.mjs speelt een vastgelegd uittreksel van de synthetische gegate stream af (186 zinnen rond het moment waarop het vertrouwen instort, geschreven door kshana receiver-trust live --gate) via het relay over een echte TCP-socket en controleert wat een consument ontvangt: de stream byte voor byte bij willekeurige chunking; geldige controlesommen op elke zin, ook de herschreven; GGA en RMC die overeenstemmen, geldig en dan ongeldig zonder flikkering; één $PKSHT per cyclus met zijn gate-veld W precies waar de positiebepaling ongeldig is; twee consumenten identiek; een gedeeltelijke regel nooit doorgestuurd. Dit controleert de stream die OpenCPN krijgt, niet het eigen scherm van OpenCPN.

Een end-to-end-controle met de echte binary, geen onderdeel van de standaardtests (zij vereist een gebouwde 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 consumer

Beide voeren de synthetische demo van een uur uit en controleren dat de positiebepaling geldig wordt en daarna ongeldig, met een $PKSHT per epoch.

Native plug-in#

integrations/opencpn/plugin/ is een scorepaneel voor OpenCPN (score, band, gate, belangrijkste redenen, een waarschuwing wanneer het vertrouwen untrusted wordt) dat $PKSHT uit de eigen NMEA-stream van OpenCPN leest, zodat zij geen andere verbinding nodig heeft dan de hierboven genoemde. Zij wordt met CMake gebouwd tegen het headerbestand van de plug-in-API van OpenCPN (meegeleverd, met zijn bron-commit) en wxWidgets; ctest voert de wx-vrije logicatests uit en controleert dat de bibliotheek de ingangspunten exporteert die OpenCPN opzoekt. Zij is uitgevoerd binnen OpenCPN 5.8.4 onder een virtueel scherm op de synthetische gegate stream (OpenCPN gaf $PKSHT door aan de plug-in, het paneel werd rood, en de eigen positie van OpenCPN bevroor toen de gate in werking trad; schermafbeeldingen, log en script in integrations/opencpn/evidence/), maar niet op een echte desktop, andere versies of platforms, en zij is niet verpakt voor de pluginmanager van OpenCPN. Zie de README.md van de plug-in. Zij valt onder GPL-3.0-or-later, anders dan de rest van de repository (LICENSING.md).

Schermafbeeldingen van die run, in integrations/opencpn/evidence/ (één run, OpenCPN 5.8.4 onder een virtueel scherm, synthetische gegevens; README.md geeft de beperkingen):

Deze tonen de leidingen en de gegate positiebepaling die OpenCPN bereikt, niet dat enig alarm tijdig of juist is voor een echt vaartuig. Adviserende software, geen typegoedgekeurde apparatuur.

Referentiebouw#

deploy/reference-build/: een generieke onderdelenlijst, OS-installatie, twee systemd-units (de adviserende monitor en de opt-in gate), een containeroptie en de Signal K-bedrading. deploy/reference-build/check-units.sh voert systemd-analyze verify uit op de units zonder iets te starten.

Beperkingen#

• De score is slechts zo goed als de controles erachter, die naar de natuurkunde van een schip en zijn andere sensoren kijken; een zelfconsistente vervalsing met een overeenkomende klok wordt door monitors die alleen op NMEA werken niet gezien (MARITIME-TRUST.md). Het uitblijven van een alarm is geen bewijs van een goede positiebepaling.
• Geen cijfer op deze pagina is een gemeten detectie- of valsalarmpercentage. De tests hierboven controleren de leidingen op synthetische tekst; zij zeggen niets over hoe enige monitor het doet bij echte interferentie.
• Geen typegoedgekeurde apparatuur; de exploitant blijft verantwoordelijk.