Námořní důvěra: může můstek tomuto fixu věřit?

kshana receiver-trust dokáže pro pohybující se plavidlo počítat živou hodnotu důvěry 0-100 pro každý polohový fix z toho, co jakýkoli přijímač již vysílá na sběrnici (nejprve NMEA 0183), a říci, které kontroly ji snížily. Je to softwarová vrstva vedle přijímače. Není to přijímač, nenahrazuje jej a nezpřesňuje fix.

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. Jeho skóre a brána jsou 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.

Tato stránka říká, na co se kontroly dívají, co která z nich dokáže a nedokáže zachytit, jak je spustit živě a co brána dělá. Mapování skóre a každá výchozí hodnota jsou v RECEIVER-TRUST.md.

Co čte#

Plavidlo se deklaruje v souboru relace, s mezemi uvedenými před během:

[platform]
kind = "vessel"
max_speed_kn = 20.0        # includes any current you want to allow for: it limits speed over ground
max_accel_mps2 = 0.2
max_turn_rate_dps = 2.0
antenna_height_m = 18.0    # antenna above the waterline
heading_sensor = true      # the stream carries a gyro or compass heading

Epochy, o nichž přijímač sám říká, že nejsou družicovým fixem (kvalita GGA 0 nebo 6 až 8: odhadnutá, ruční, simulátor; stav RMC V nebo režim E, M, S, N), se pro kontroly polohy nepoužívají a nenesou žádný důkaz pro ani proti: přijímač to již řekl.

Prvních calibration_s sekund tvoří základ a nikdy se nehodnotí. Každý monitor se dívá pouze na aktuální a dřívější epochy, takže rozhodnutí v dané epoše se nemění, když přijdou pozdější data, a živý proud dává stejné skóre jako týž text čtený ze souboru.

Co každá kontrola zachytí a co nedokáže#

Směry mezi fixy (směr trati použitý kontrolou rychlosti otáčení, kurz plynoucí ze dvou poloh) jsou směrem tětivy mezi nimi, což je střední azimut geodetiky mezi fixy, nikoli přímý azimut v prvním fixu; ty se liší asi o polovinu sbíhavosti poledníků mezi fixy (0,001 stupně pro základnu 260 m na zeměpisné šířce 59,5 stupně).

Padělaná poloha musí souhlasit s fyzikou lodi a s dalšími senzory lodi. Každá kontrola porovnává fix s jedním z nich. Kontrola je tak nezávislá, jak je nezávislý její druhý zdroj: směr přídě z kompasu GNSS nebo „rychlost vůči vodě“ odvozená z GNSS není nezávislá na testovaném přijímači a nic nepřidává.

Co monitory pouze s NMEA nedokážou. Spoofer, který reprodukuje celou konstelaci se sebekonzistentní polohou, rychlostí, kurzem slučitelným se směrem přídě, věrohodným výkonem každé družice a souhlasnými hodinami, je neviditelný pro každou z výše uvedených kontrol: nic ve větách jeho fix nerozliší od skutečného. Stejně tak přehrání zaznamenaných skutečných signálů. Tuto mezeru uzavírají autentizace (OSNMA, nebo přijímač s vlastní ochranou proti spoofingu) a nezávislé navigační senzory; tato vrstva může využít pouze jejich nahlášený stav. Proud, který je podvržen již během tvorby základu, nemá čistý základ. Nepřítomnost alarmu není důkazem dobrého fixu.

Skóre důvěryhodnosti#

Každá epocha po kalibraci dostane skóre od 0 do 100 a důvody, proč není 100: které kontroly odečetly body, jejich statistiku vůči prahu a jejich body. Pásma (hranice uvedené v relaci): nominal při 90 nebo více, degraded při 55 nebo více, untrusted pod tím. Mapování, každá váha a její zdůvodnění jsou v RECEIVER-TRUST.md; je deterministické a stanovené před ohodnocením záznamu, bez učení a bez čehokoli přizpůsobeného událostem.

Každý výstup plavidla nese poradní prohlášení: klíč advisory výsledného JSON a každého živého řádku, první komentářový řádek # v CSV (čtečky jej přeskočí pomocí svého přepínače pro komentáře), <desc> a patičku SVG. Výstupy dávkového běhu: session.result.json (s modelem skóre a odečty každé epochy), session.trust.csv (se sloupci score a score_reasons) a session.trust.svg, což je pro plavidlo trať hlášená přijímačem zbarvená podle pásma důvěry nad skóre v čase.

Syntetická ukázka#

examples/maritime-trust/ obsahuje vymyšlený záznam NMEA z trajektu na trase Tallinn–Helsinki (50minutový výřez, asi 17 kn, 1 Hz: GGA, RMC, VTG, směr přídě z gyroskopu, log rychlosti, GSV s věrohodnou oblohou), v němž odtažení polohy odtahuje hlášenou polohu od skutečné polohy plavidla od 1500 s. Přijímač po celou dobu dál hlásí platný fix; klesá skóre důvěry, skrz pásmo degraded do pásma untrusted. session.toml uvádí před během každý práh, meze plavidla a každou váhu skóre.

kshana receiver-trust examples/maritime-trust/session.toml
kshana receiver-trust live examples/maritime-trust/session.toml \
  --file examples/maritime-trust/tallinn-helsinki.nmea --gate --json trust.jsonl > gated.nmea

Záznam je text zapsaný do souboru příkazem cargo run --example gen_maritime_trust_demo: nemodeluje žádný rádiový signál a nic nevysílá. Není to měření a trasa je ilustrativní, nikoli mapa. tests/receiver_trust_maritime_demo.rs připíná záznam a očekávaný výstup jako regresní pojistky na syntetických datech; nic nevypovídají o tom, jak si jakýkoli monitor vede na skutečné interferenci.

Obrázek kreslí tools/gen_readme_assets.py ze skutečného běhu této ukázky (kshana receiver-trust examples/maritime-trust/session.toml); skóre je poradní a záznam je vymyšlený.

Specifikace pohledu ve Studiu#

Pro toho, kdo staví pohled Studia pro běh plavidla. Nic v této části ve Studiu zatím není implementováno; strana enginu (data níže) ano.

Vstupy. Buď:

• výsledný JSON dávkového běhu (kshana receiver-trust <session.toml>, nebo totéž přes receiver_trust(toml) v balíčku WebAssembly s inline záznamem): score_model (hranice pásem, rampa, držení důkazů, každá váha), monitors_run, states a epochs[], každá s t_s, state, alarms, score.{score,band,deductions[]}, marine.{position:[lat,lon], stats, ratios} a od 0,36 geometry a class každého odečtu, s geometry_model a geometry_summary na nejvyšší úrovni; nebo
• živé řádky JSON (schéma výše), jeden objekt na epochu, připisované za běhu proudu. Každý řádek nese polohu position hlášenou přijímačem (schéma 1,1).

Ukázková sada je examples/maritime-trust/: session.toml, tallinn-helsinki.nmea (záznam) a tallinn-helsinki.truth.csv (t_s,true_lat_deg,true_lon_deg: kde plavidlo skutečně bylo, což žádný skutečný záznam nemá). Pohled by měl spustit relaci a vedle ní číst soubor pravdy.

Co vykreslit.

1. Trať, sever nahoře, jedno měřítko na obou osách: polohy hlášené přijímačem jako čára zbarvená podle pásma epochy (šedá calibrating, zelená nominal, jantarová degraded, červená untrusted), začátek a konec označené, měřítková úsečka. Pro ukázku skutečná trať jako tenká neutrální čára pod ní, aby se odtažení projevilo jako jejich rozcházení; přepínač skutečné trati a údaj o odchylce v metrech v čase kurzoru.
2. Časová osa skóre: skóre od 0 do 100 v čase, hranice pásem (nominal_min, degraded_min z score_model) jako čárkované čáry, pásmo jako proužek pod tím a počátek jakékoli uvedené události jako značka. Časová osa je sdílena s tratí.
3. Důvody: pro epochu pod kurzorem odečty (monitor, poměr vůči prahu, body) jako vodorovné sloupce, od největšího, s váhou, kterou každý monitor nese z score_model.weights; monitory, které běžely a nic nestály, vykreslené bledě, monitory, které neběžely (nejsou v monitors_run), uvedené jako „nespuštěno“, nikdy jako úspěšné. Monitor geometry nemá položku score_model.weights: jeho strop je geometry_model.cap_in_force.
4. Proužky monitorů: jeden tenký proužek na každý monitor v monitors_run ukazující jeho poměr v čase (alarm při 1), aby čtenář viděl, která kontrola se pohnula první.
5. Stav brány: v živém pohledu gate každé epochy (off, passed, withheld) jako proužek pod proužkem pásma a poslední $PKSHT. V dávkovém pohledu jsou epochy, které by brána zadržela, ty, jejichž pásmo je untrusted, s uplatněným držením před uvolněním.
6. Dráha geometrie (0,36): proužek pod proužkem pásma zbarvený podle geometry.status (zelená dobrá, jantarová degraded, šedá šrafovaná neznámá), v barevné rodině odlišné od drah nekonzistence a prostředí, s legendou „geometry: the sky, not the signal“. Odečty zbarvené podle class (geometrie, prostředí, nekonzistence) v panelu důvodů a v proužcích monitorů a počty epoch podle tříd z geometry_summary vedle počtů pásem. Pro epochu pod kurzorem: geometry.note, n_used, HDOP, PDOP, VDOP, source, age_s a příznak, když je nastaveno reported_derived_mismatch (odečet geometrie je pak nekonzistence). unknown se zobrazuje jako „geometry unknown: no GSV or GSA in the log“, nikdy jako dobrá. Prahy [geometry] a jejich původ z geometry_model jsou vedle nastavení skóre. Poradní poznámka zůstává.
7. Fix hlášený přijímačem: přijímač v ukázce hlásí platný fix po celou dobu (kvalita GGA 1, stav RMC A); uveďte to v legendě, protože právě to je smyslem pohledu.

Interakce. Jeden časový kurzor sdílený všemi panely (tažení, šipky a tlačítko přehrávání, které přehrává rychlostí 1x až 60x); najetí na trať nebo na kterýkoli proužek jej posouvá. Kliknutí na odečet zvýrazní epochy, v nichž byl tento monitor nad svým počátkem. Filtr pásem (zobrazit pouze epochy degraded a untrusted) a skok na první odečet a na první epochu untrusted. Text při najetí u každého názvu monitoru s jednořádkovým popisem z této stránky. Prahy a váhy relace se zobrazují, pouze pro čtení, vedle grafu, takže je na obrazovce vidět, co skóre použilo.

Znění, které zachovat. Stránka musí říkat, že jde o software pouze poradního charakteru a nikoli typově schválené navigační zařízení, že ukázka je syntetický text s vymyšleným odtažením a že fix bez alarmu tím ještě není dobrým fixem (viz omezení výše). Žádná hodnota na stránce by neměla vypadat jako měřítko toho, jak si kontroly vedou na skutečné interferenci.

Z kódu#

Pro volající, kteří drží relaci i bajty v paměti (žádné soubory, žádné hodiny, žádné sockety; bezpečné pro WebAssembly), má kshana::receiver_trust::assess:

• assess_vessel_log(session_toml, log_bytes) -> Result<ReceiverTrustResult, String>: celý záznam ohodnocený jako dávkový běh; tentýž výsledek jako kshana receiver-trust <session.toml>, který se serializuje do výsledného JSON (score_model, monitors_run, epochs[] se skóre a odečty).
• assess_stream_excerpt(session_toml, excerpt_bytes) -> Result<ExcerptAssessment, String>: omezený kus proudu (nejvýše 2 MiB a 20 000 epoch a dostatečně dlouhý, aby obsáhl kalibrační okno), ohodnocený tak, jak hodnotí živý režim, a vrácený ve schématu živých řádků JSON (epochs[], poslední $PKSHT, souhrn počtů pásem, nejnižší a konečné skóre, čas první epochy untrusted). Čas přijímače se neporovnává s hodinami hostitele. Dlouho běžící živý režim (sockety, připisovaný soubor, brána) patří binárnímu souboru.

Obojí vyžaduje relaci s [platform] kind = "vessel"; její tabulka [log] je volitelná.

Spuštění naživo#

# stdin: a serial port read by another tool, or a multiplexer's output
some-nmea-source | kshana receiver-trust live session.toml

# a log file that is being appended to (it starts at the beginning; --from-end skips what is there)
kshana receiver-trust live session.toml --file /var/log/nmea.log --follow

# a TCP server (a multiplexer or a terminal server) or UDP datagrams (a bridge network)
kshana receiver-trust live session.toml --tcp 192.0.2.10:10110
kshana receiver-trust live session.toml --udp 10110

Relace je tentýž session.toml jako u dávkového běhu, s tabulkou [platform], která deklaruje kind = "vessel"; její tabulka [log] není potřeba. Sériové porty se zatím neotevírají přímo: port čtěte nástrojem, který už používáte (stty a cat, terminálový server, multiplexor) a data předávejte rourou nebo přeposíláním. Přímý sériový vstup může přijít později.

Každá dokončená epocha zapíše na stdout jeden řádek JSON:

{"seq":941,"t_s":940.0,"time":"2025-06-14T08:15:40.000Z","state":"degraded","score":60.0,
 "deductions":[{"monitor":"heading-course","ratio":1.5,"points":40.0}],
 "alarms":["heading-course"],"gate":"off","note":null,
 "position":{"lat_deg":59.8123456,"lon_deg":24.9012345,"height_m":39.4}}

state je calibrating, nominal, degraded nebo untrusted (pásmo skóre, s hranicemi v tabulce [score] relace); score chybí během kalibrace; deductions uvádějí, které kontroly odebraly body a kolik, od největšího.

Schéma řádků JSON (verze 1,1)#

Jeden objekt JSON na dokončenou epochu, klíče v tomto pořadí:

Názvy monitorů (kebab-case; 17): cn0-drop, agc, jam-ind, loss-of-lock, position-jump, raim, clock, solve-failure, kinematic, heading-course, speed-log, sea-level, cn0-spread, cn0-rise, time-consistency, osnma a od 1,3 geometry. V pozdějších verzích mohou přibýt nové názvy; příjemci by měli neznámý název monitoru považovat za monitor. Rozvržení $PKSHT níže nese verzi formátu ve svém prvním poli; toto schéma JSON je verze 1,3: 1,1 přidala position, 1,2 advisory, 1,3 geometry na konec a class v každém odečtu a mění se pouze přidáním klíčů na konec.

Vstup autentizace#

Monitor osnma přebírá stav autentizace jednotlivých družic od zdroje autentizace přes MarineObs::sat_auth (seznam (satellite, status), stav Authenticated, Failed nebo Unavailable), vedle celkového MarineObs::osnma. Na straně NMEA totéž nese $PKSOS,<A|F|N>[,<sat>:<A|F|N>...], například $PKSOS,A,E11:A,E19:F. Jakékoli selhání, celkové nebo u jedné družice, spustí alarm monitoru a stojí celou jeho váhu (dostane poměr 1,5); úspěch není důkazem. Kshana zde nic neověřuje: za hlášený stav odpovídá zdroj, který ověřuje.

Epocha je dokončena, když přijde další časovaná věta; věty pomalejších nebo nesynchronizovaných přístrojů (gyroskop několik desetin sekundy za přijímačem), které dorazí před tím, k ní patří. Pokud proud po dobu [live] idle_flush_s (výchozí 1,5 s, nastavte nad nejdelší mezeru mezi časovanými větami vašeho přijímače) stojí, epocha se dokončí tak, jak je. Prvních calibration_s sekund proudu tvoří základ a nikdy se nehodnotí, takže proud, který je již podvržen v okamžiku prvního připojení, nemá čistý základ: spusťte vrstvu před plavbou, nebo když je o fixu známo, že je dobrý. Kalibrační okno se uzavře jednou, podle příchodu: epocha, jejíž čas je dřívější než již spatřený čas (přetočení, přehrání začátku proudu), není nikdy kalibrací, ať její čas říká cokoli; hodnotí se s plným odečtem time-consistency, což je untrusted. Živý engine hodnotí každou epochu přes kalibrační epochy a poslední zhruba minutu proudu, takže jeho náklady na epochu rostou s calibration_s krát frekvence epoch; na rychlém přijímači držte okno krátké. Jeho vyrovnávací paměti jsou omezené (záplava řádků bez časované věty se dokončí každých 5 000 řádků, kalibrace a historie jsou omezeny na 20 000 epoch).

Čas přijímače se také porovnává s monotónními hodinami tohoto počítače, což má smysl pouze pro proud přicházející v reálném čase. Uložený záznam přiváděný plnou rychlostí přes stdin, TCP nebo UDP tuto kontrolu už konstrukcí spustí: použijte --replay. (--file bez --follow to již předpokládá.) --file ... --follow se čte jako přehrání, dokud není přečten do konce, a hodiny hostitele se zapojí až od té chvíle, takže nahromaděná data se nečtou jako chyba hodin; kontrola pak vyžaduje, aby kalibrační okno bylo stále otevřené (jinak nemá základ a neběží).

Konce proudu a poruchy: stdin a soubor čtený do konce skončí normálně (kód 0). Spojení TCP uzavřené protistranou není normálním koncem pro proud, který má pokračovat: vrstva po ohodnocení a zapsání všeho přijatého skončí s nenulovým kódem a znovu se nepřipojuje, takže ji spouštějte pod dohledem, který ji restartuje. Datagramy UDP, které větu rozdělí, se spojují; čtečky stdin, souboru a TCP mají za sebou omezenou frontu, která tlačí zpět na odesílatele (nic se neztratí), zatímco UDP, které zpět tlačit nemůže, zahazuje datagramy, které engine nepřijme, a hlásí to na stderr. --udp <port> se naváže na adresu loopback; pro naslouchání jinde zadejte --udp <addr>:<port> (vypíše se varování).

$PKSHT: proprietární věta#

Každá epocha také vytvoří jednu větu NMEA 0183 s platným kontrolním součtem, kterou --pksht <path|-> zapisuje do souboru nebo na stdout a kterou brána vkládá do předávaného proudu:

$PKSHT,1,080140.25,30.0,U,W,heading-course:40.0/cn0-spread:30.0*2F

Adresa je P + výrobní mnemonik KSH + T. Zařízení, které proprietární větu nezná, ji ignoruje. Kshana vlastní $PKSHT na vstupu ignoruje.

Režim brány#

--gate staví Kshana mezi přijímač a zařízení, které jeho fix používá (kartografický systém, systém řízení trati). Proud NMEA vstupuje, vychází na stdout a je:

• předán beze změny, dokud epocha není untrusted (a během kalibrace), s větou $PKSHT po každém cyklu vět; a
• označen za neplatný, dokud je untrusted: kvalita GGA 0; stav RMC V (a jeho indikátor režimu N a navigační stav V, kde jsou přítomny); režim GNS N v každé poloze; stav GLL V a režim N; režim VTG N, kde jej má. Pole polohy zůstávají tak, jak byla: smyslem je, že zařízení vidí, jak přijímač sám prohlašuje fix za neplatný, a spustí vlastní alarm. U každé přepsané věty se kontrolní součet přepočítá.

Jakmile je fix zadržen, uvolní se až poté, co epochy byly mimo pásmo untrusted po dobu [live] gate_release_s (výchozí 30 s), takže skóre na hranici pásma nemůže způsobit blikání fixu. Řádky JSON jdou pouze tam, kam říká --json <path> (ve výchozím nastavení nikam, protože stdout má proud).

receiver-nmea-source | kshana receiver-trust live session.toml --gate --json trust.jsonl | downstream-equipment

Aby se mohl kartografický plotter připojit přímo, nabídněte filtrovaný proud přes TCP místo stdout:

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

--listen tcp:<port> naslouchá na adrese loopback; tcp:<addr>:<port> naslouchá jinde (vypíše se varování, protože kdo se k adrese dostane, může proud číst). Může se připojit libovolný počet klientů; každý dostává týž proud od okamžiku připojení a klienti pouze čtou. Každý klient má vlastní omezenou frontu a zapisovač, takže klient, který nestíhá, je odpojen (spojení uzavřeno, řádek na stderr) a nikdy nezdržuje ostatní ani vstup. --listen vyžaduje --gate; stdout pak z proudu nenese nic, takže --json - je volné.

Co brána nedělá a co vědět, než ji použijete:

• Je volitelná. Nic neoznačí fix za neplatný, pokud není zadáno --gate.
• Přidává latenci: cyklus se drží, dokud není ohodnocena jeho epocha, což je doba do další časované věty (asi jeden cyklus: sekunda u přijímače 1 Hz), nebo idle_flush_s po poslední větě, když proud stojí. Zařízení, které potřebuje větu do několika desítek milisekund od výstupu přijímače, za ní nesmí stát.
• Je jediným bodem v řetězci: když se zastaví, zastaví se proud. Provozujte ji pod dohledem a předem rozhodněte, co následující zařízení dělá bez proudu.
• Při vlastních poruchách selhává do bezpečného stavu: pokud monitory po kalibraci nedokážou vytvořit skóre (deklarovaný senzor směru přídě, který nic neposílá, příliš málo kalibračních epoch), epocha je untrusted, nese note a je zadržena; držení před uvolněním se měří na hodinách tohoto počítače, nikoli na čase přijímače, což je to, co spoofer ovládá (u přehrání existuje pouze čas přijímače).
• Může zadržet dobrý fix (falešný poplach), stejně jako propustit podvržený (nezachycená událost). Monitory kontrolují fix proti fyzice lodi a jejím dalším senzorům; padělek, který se všemi souhlasí, není vidět (viz omezení níže).
• Očekává čistý textový proud NMEA 0183. Binární rámce smíšené do proudu se předávají beze změny, ale věta $PKSHT pak může přistát mezi bajty rámce.
• Není typově schválená a nic v ní nebylo posuzováno podle IEC 61108 ani IEC 61162. Za navigaci plavidla zůstává odpovědný provozovatel.