Merenkulun integraatiot: luottamuspistemäärä sillalla
Kshanan merenkulun luottamuspistemäärä (MARITIME-TRUST.md) on käytettävissä ohjelmistoista, joita veneilijät jo ajavat: palvelinliitännäinen ohjelmistolle Signal K sekä OpenCPN gate-tilan NMEA:n kautta TCP:llä. Referenssiversio asentaa sen pienelle tietokoneelle vastaanottimen viereen.
Ohjeellinen ohjelmisto. Kshana ei ole tyyppihyväksytty navigointilaite (IEC 61108, IEC 61162), eikä sitä ole arvioitu suhteessa mihinkään suorituskykystandardiin. Kaikki tämän sivun sisältö on apuväline navigoijan harkinnalle. Käyttäjä vastaa edelleen aluksen turvallisesta navigoinnista ja kaikista päätöksistä luottaa paikkaratkaisuun tai lopettaa sen luottaminen. Mikään tässä ei lähetä mitään, eikä mikään tässä tee paikkaratkaisusta tarkempaa.
| Osa | Missä | Tila versiossa 0,35 |
|---|---|---|
| Signal K -lisäosa | integrations/signalk/ |
toimitettu, yksikkötestattu tallennetulla synteettisellä tulosteella; ei julkaistu npm:ään |
| OpenCPN gate-tilan NMEA:n kautta TCP:llä | integrations/opencpn/ |
toimitettu ja testattu (kuluttajapuolen toisto); itse OpenCPN:n käyttöliittymää ei aja mikään testi |
| OpenCPN:n natiivi pistemääräpaneelin liitännäinen | integrations/opencpn/plugin/ |
rakennettu, logiikka yksikkötestattu ja ajettu OpenCPN:n versiossa 5.8.4 virtuaalinäytöllä (todisteet hakemistossa integrations/opencpn/evidence/); ei paketoitu liitännäishallintaan; julkaistaan vasta tarkastuksen jälkeen |
| Referenssiversio | deploy/reference-build/ |
osat, käyttöjärjestelmän vaiheet, systemd-yksiköt (kuivaajo tarkistettu), konttivaihtoehto; ei testattu aluksella |
Kaikki lukee yhtä asiaa: komennon kshana receiver-trust live tulostetta (JSON-rivit, lause $PKSHT, gate). Siirtomuodot on kuvattu tiedostossa MARITIME-TRUST.md. Signal K -liitännäinen pitää tietonsa niistä yhdessä tiedostossa integrations/signalk/lib/adapter.js; muodon muutos on yhden tiedoston muokkaus.
Signal K -lisäosa#
Ei npm-riippuvuuksia. Liitännäinen itse toimii Node-versiolla 18 tai uudemmalla; nykyiset julkaisut ohjelmasta signalk-server vaativat Node-version 22 tai uudemman, joten käytännössä käytetään versiota 22. Kopioi tai linkitä integrations/signalk/ palvelimen kansioon node_modules (esimerkiksi ~/.signalk/node_modules/signalk-kshana-trust), käynnistä palvelin uudelleen ja ota käyttöön Kshana GNSS trust kohdassa Server, Plugin Config.
Mistä epookit tulevat (source)#
source |
Mitä liitännäinen tekee |
|---|---|
spawn-signalk-nmea (oletus) |
Ajaa komennon kshana receiver-trust live <sessionFile> ja kirjoittaa sen vakiosyötteeseen jokaisen palvelimen vastaanottaman raa'an lauseen (NMEA 0183; palvelimen tapahtuma nmea0183). Käynnistää sen uudelleen porrastetulla viiveellä, jos se päättyy | Käytä sitä vain palvelimella, jolla on yksi NMEA-lähde: se syöttää jokaisen lauseen jokaiselta toimittajalta lomittain, joten toinen GNSS-vastaanotin tai AIS näyttää yhdeltä vastaanottimelta, jonka sijainti hyppii, ja se voidaan pisteyttää harhautukseksi. Jos lähteitä on useampi, käytetään tilaa spawn-args ja kyseisen vastaanottimen omaa virtaa (--tcp) tai tilaa tcp-pksht gatelta. |
spawn-args |
Ajaa komennon kshana receiver-trust live <sessionFile> <inputArgs...>, esimerkiksi ["--tcp","192.0.2.10:10110"] tai ["--udp","10110"] |
tcp-json |
Yhdistää JSON-rivien syötteeseen, jonka kshana kirjoittaa (esimerkiksi välittäjältä hakemistossa integrations/opencpn/) |
tcp-pksht |
Yhdistää NMEA-virtaan (esimerkiksi palvelun tai kontin gate-tuloste referenssiversiossa, portti 10110) ja lukee vain sen lauseet $PKSHT |
Virralla, jota jo harhautetaan, kun monitori ensimmäisen kerran yhdistää, ei ole puhdasta lähtötasoa (ensimmäisiä calibration_s sekuntia ei koskaan pisteytetä). Käynnistä se ennen matkaa.
Julkaistut polut#
Jokainen epookki päivittää (lähde kshana-trust):
| Polku | Arvo |
|---|---|
navigation.gnss.kshana.band |
calibrating, nominal, degraded tai untrusted |
navigation.gnss.kshana.score |
0 – 100 tai null kalibroinnin aikana |
navigation.gnss.kshana.reasons |
[{monitor, points}], suurin ensin: mitkä tarkistukset laskivat pistemäärää |
navigation.gnss.kshana.alarms |
monitorit, jotka ovat parhaillaan raja-arvonsa yläpuolella |
navigation.gnss.kshana.gate |
off, passed tai withheld (kun gate ajetaan muualla; null kohteesta $PKSHT sen puuttuessa) |
navigation.gnss.kshana.reportedPosition |
{latitude, longitude, altitude}: sijainti, jonka testattava vastaanotin ilmoitti kyseisellä epookilla (JSON-skeema 1,1 tai uudempi; ei julkaista, kun virrassa ei ole sijaintia, esimerkiksi kohteesta $PKSHT tai ohjelman kshana vanhemmasta versiosta). Vain luottamuskonteksti: liitännäinen ei koskaan kirjoita polkua navigation.position, joten aluksen oma sijaintipolku säilyy koskemattomana |
notifications.navigation.gnss.kshana.trust |
annetaan, kun tila muuttuu: {state, method, message} |
Liitännäinen lähettää myös Signal K -metatiedot näille poluille kerran käynnistyksessä. score on Kshanan luottamuspistemäärä 0 – 100, pistemäärä eikä suhdeluku tai todennäköisyys, joten sillä ei ole SI-yksikköä; sen metatiedot antavat alueen, kuvauksen ja vyöhykkeet, jotka seuraavat alla olevia raja-arvoja. reasons[].points ovat pistemääräpisteitä, jotka on vähennetty tästä 0 – 100 pistemäärästä.
Ilmoitus on normal, alert, warn tai alarm. Se poistetaan julkaisemalla tila normal, ei null: kuluttajan, joka pitää vain tilaa null poistettuna, tulee pitää poistettuna myös tilaa normal. Oletuksena heikentynyt kaista antaa warn ja epäluotettu kaista antaa alarm, asetuksella method: ["visual","sound"]. Ilmoitus lasketaan alemmas, kun tila on ollut parempi clearAfterEpochs epookin ajan. Jos epookkia ei tule staleAfterS sekuntiin, se varoittaa, ettei pistemäärää päivitetä. Kalibrointi ei koskaan nosta ilmoitusta. Lähde $PKSHT ei sisällä luetteloa alarms (lause sisältää vain kaistan, pistemäärän ja kaksi suurinta syytä).
Asetukset (jokainen raja-arvo)#
| Avain | Oletus | Merkitys |
|---|---|---|
source |
spawn-signalk-nmea |
katso edellä |
command |
kshana |
suoritettava tiedosto (spawn-tilat). Se ajaa mitä tahansa suoritettavaa tiedostoa palvelimen käyttäjänä: vain Signal K -palvelimen ylläpitäjän pitäisi pystyä muuttamaan liitännäisen asetuksia |
sessionFile |
/etc/kshana/session.toml |
aluksen rajat, raja-arvot ja pistemäärän painot (spawn-tilat) |
inputArgs |
[] |
komentoon kshana receiver-trust live <sessionFile> lisättävät argumentit molemmissa spawn-tiloissa: syöte tilalle spawn-args, lisäliput kuten --replay (tallennettu loki syötettynä reaaliaikaa nopeammin) tilalle spawn-signalk-nmea. Liitännäinen hylkää liput --gate, --listen, --json ja --pksht (se lukee ohjelman kshana JSON-tulosteen vakiotulosteesta), ja tilalle spawn-signalk-nmea myös syöteliput (--stdin, --file, --tcp, --udp, --follow, --from-end) |
host, port |
127.0.0.1, 10111 |
TCP-tilat (gate palvelee portissa 10110: aseta portti asetukselle tcp-pksht) |
thresholdMode |
band |
band: Kshanan ilmoittama kaista, jonka rajat ovat istuntotiedostossa. score: alla olevat kaksi pistemäärää |
warnBelowScore |
90 |
Tila score: tämän alapuolella tila on degradedState (Kshanan oletusraja tilalle nominal) |
alarmBelowScore |
55 |
Tila score: tämän alapuolella tila on alarm (Kshanan oletusraja tilalle degraded) |
degradedState |
warn |
heikentyneen kaistan tila: normal, alert tai warn |
raiseAfterEpochs |
1 |
peräkkäisiä epookkeja huonommassa tilassa ennen kuin ilmoitus annetaan |
clearAfterEpochs |
10 |
peräkkäisiä epookkeja paremmassa tilassa ennen kuin se lasketaan alas |
staleAfterS |
10 |
varoita, jos epookkia ei tule näin pitkään aikaan; 0 kytkee sen pois |
method |
["visual","sound"] |
ilmoitustavat |
Liitännäinen ei toimi gatena: se ei koskaan muuta paikkaratkaisua. Paikkaratkaisun merkitseminen virheelliseksi karttajärjestelmälle on gate, jota käsitellään alla.
Testit#
cd integrations/signalk && npm testnode:test, ei riippuvuuksia, ei verkkoa osoitetta 127.0.0.1 pidemmälle. Testit jäsentävät ja toistavat 66 epookin otteen JSON-riveistä ja lauseista $PKSHT, jotka komento kshana receiver-trust live kirjoitti synteettiseen Itämeren demoon (keksittyä dataa, vain tekstiä), ja tarkistavat kahden muodon yhtäpitävyyden, pito- ja tyhjennyskäyttäytymisen, pistemääräkäyttötilan, vanhentumisen ja kolme syöttöpolkua paikallista syötettä ja korvaavaa lapsiprosessia vasten. Nämä testit eivät käynnistä oikeaa Signal K -palvelinta; erillinen skriptattu ajo tekee niin, katso alla.
Ajo oikeassa Signal K -palvelimessa#
integrations/signalk/evidence/ sisältää skriptin, joka lataa liitännäisen kiinnitettyyn pakettiin signalk-server 2.33.0 (yksityisessä, vain loopbackia käyttävässä verkkonimiavaruudessa) ja tallentaa, mitä palvelimen omat REST- ja WebSocket-rajapinnat näyttävät. Luottamuspolut ilmestyvät, ilmoitus kulkee tiloissa warn, alarm, normal (pidon jälkeen) ja taas warn, kun data loppuu, ja kun oikea kshana sai syötteensä palvelimen omasta NMEA-syötteestä, se julkaisi myös reportedPosition, ei koskaan navigation.position. Yksi palvelinversio, yksi ajo, ei oikeaa alusta; rajoitukset ja toisto ovat todisteiden README-tiedostossa.
OpenCPN#
OpenCPN lukee NMEA:ta verkosta, ja kshana receiver-trust live --gate voi itse palvella gate-käsitellyn virran TCP-portissa.
Suositus: suora yhteys.
some-nmea-source | kshana receiver-trust live session.toml --gate --listen tcp:10110(some-nmea-source on vastaanottimen sarjaportti luettuna komennoilla stty ja cat, multiplekseri tai ohjelman kshana omat syötteet --tcp/--udp; referenssiversion kshana-gate.service tekee tämän systemd:n alla.) --listen tcp:<port> sitoutuu loopback-osoitteeseen; mikä tahansa määrä vain lukevia asiakkaita voi yhdistää, ja asiakas, joka ei pysy mukana, pudotetaan muita viivyttämättä.
Vaihtoehto: välittäjä. integrations/opencpn/nmea-tcp-relay.mjs on riippuvuudeton Node-jakelija, joka tekee saman ohjelmalle kshana ilman asetusta --listen, tai palvelee mitä tahansa muuta rivivirtaa (konttivaihtoehto käyttää sitä JSON-epookeille):
some-nmea-source | kshana receiver-trust live session.toml --gate --json trust.jsonl \
| node integrations/opencpn/nmea-tcp-relay.mjs --listen 10110Se välittää tavut muuttumattomina, vain kokonaisia rivejä, ja pudottaa asiakkaan, joka ei lue. Suosi suoraa yhteyttä: yksi prosessi vähemmän ketjussa.
OpenCPN:ssä: Options, Connections, Add Connection, Network, protokolla TCP, osoite 127.0.0.1, portti 10110, suunta Input. Kun luottamus ei ole romahtanut, virta on vastaanottimen oma, ja lisäksi yksi lause $PKSHT jaksoa kohti. Kun se on romahtanut, välitetyn GGA:n laatu on 0, RMC:n tila V, ja tilaindikaattorit kertovat, ettei paikkaratkaisua ole, tarkistussummat laskettuna uudelleen: laite näkee vastaanottimen itse julistavan paikkaratkaisun virheelliseksi ja antaa oman hälytyksensä. Lauseet $PKSHT näkyvät OpenCPN:n NMEA-debug-ikkunassa (Options, Connections, ”NMEA debug window”). Sijaintikentät jätetään sellaisiksi kuin ne vastaanotettiin.
Lue ”Gate mode” tiedostosta MARITIME-TRUST.md ennen kuin tähän luotetaan: se on valinnainen, lisää viivettä (jaksoa pidetään, kunnes sen epookki on pisteytetty), on ketjun yksittäinen kohta ja voi pidättää hyvän paikkaratkaisun sekä päästää läpi väärennetyn.
Testit#
cd integrations/opencpn && npm testtest/relay.test.mjs toistaa tallennetun otteen synteettisestä gate-käsitellystä virrasta (186 lausetta luottamuksen romahtamishetken ympärillä, kirjoittanut kshana receiver-trust live --gate) välittäjän läpi oikean TCP-pistokkeen yli ja tarkistaa, mitä kuluttaja vastaanottaa: virta tavu tavulta mielivaltaisessa pilkkomisessa; kelvolliset tarkistussummat jokaisessa lauseessa, uudelleenkirjoitetut mukaan lukien; GGA ja RMC yhtäpitävinä, kelvollisia ja sitten virheellisiä ilman välkyntää; yksi lause $PKSHT jaksoa kohti, jonka gate-kenttä on W täsmälleen siellä, missä paikkaratkaisu on virheellinen; kaksi kuluttajaa identtisinä; osittaista riviä ei koskaan välitetä. Tämä tarkistaa OpenCPN:lle annetun virran, ei OpenCPN:n omaa näyttöä.
Päästä päähän -tarkistus oikealla binäärillä, ei osa oletustestejä (se vaatii rakennetun ohjelman 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 consumerMolemmat ajavat yhden tunnin synteettisen demon ja tarkistavat, että paikkaratkaisu muuttuu ensin kelvolliseksi ja sitten virheelliseksi ja että jokaiselle epookille on lause $PKSHT.
Natiivi liitännäinen#
integrations/opencpn/plugin/ on OpenCPN:n pistemääräpaneeli (pistemäärä, kaista, gate, tärkeimmät syyt, hälytys kun luottamus muuttuu epäluotetuksi), joka lukee lauseet $PKSHT OpenCPN:n omasta NMEA-virrasta, joten se ei tarvitse muuta yhteyttä kuin yllä olevan. Se rakennetaan CMakella OpenCPN:n liitännäisrajapinnan otsaketta (mukana toimitettu, lähdekomitteineen) ja wxWidgetsiä vasten; ctest ajaa wx-vapaat logiikkatestit ja tarkistaa, että kirjasto vie ne sisääntulokohdat, joita OpenCPN hakee. Se on ajettu OpenCPN:n versiossa 5.8.4 virtuaalinäytöllä synteettisellä gate-käsitellyllä virralla (OpenCPN välitti liitännäiselle lauseen $PKSHT, paneeli muuttui punaiseksi ja OpenCPN:n oma sijainti jäätyi, kun gate kytkeytyi; kuvakaappaukset, loki ja skripti hakemistossa integrations/opencpn/evidence/), mutta ei oikealla työpöydällä, muilla versioilla tai alustoilla, eikä sitä ole paketoitu OpenCPN:n liitännäishallintaan. Katso liitännäisen README.md. Se on lisensoitu GPL-3.0-or-later, toisin kuin muu repositorio (LICENSING.md).
Kuvakaappaukset tuolta ajolta hakemistossa integrations/opencpn/evidence/ (yksi ajo, OpenCPN 5.8.4 virtuaalinäytöllä, synteettinen data; README.md kertoo rajoitukset):
Nämä näyttävät putkiston ja gate-käsitellyn paikkaratkaisun saapumisen OpenCPN:ään, eivät sitä, että mikään hälytys olisi oikea-aikainen tai oikea todellisella aluksella. Ohjeellinen ohjelmisto, ei tyyppihyväksytty laite.
Referenssiversio#
deploy/reference-build/: yleinen osaluettelo, käyttöjärjestelmän asetukset, kaksi systemd-yksikköä (ohjeellinen monitori ja valinnainen gate), konttivaihtoehto ja Signal K -kytkentä. deploy/reference-build/check-units.sh ajaa komennon systemd-analyze verify yksiköille käynnistämättä mitään.
Rajoitukset#
- Pistemäärä on vain yhtä hyvä kuin sen takana olevat tarkistukset, jotka katsovat aluksen fysiikkaa ja sen muita antureita; itsensä kanssa yhdenmukainen väärennös, jonka kello täsmää, jää pelkkiin NMEA-tietoihin perustuvilta monitoreilta huomaamatta (
MARITIME-TRUST.md). Hälytyksen puuttuminen ei ole todiste hyvästä paikkaratkaisusta. - Mikään tämän sivun luku ei ole mitattu havaitsemis- tai väärän hälytyksen osuus. Yllä olevat testit tarkistavat putkiston synteettisellä tekstillä; ne eivät kerro mitään siitä, miten mikään monitori pärjää todellisessa häiriössä.
- Ei tyyppihyväksytty; käyttäjä vastaa edelleen.