Skip to content

panelServer

Jump to bottom
Jan Horacek edited this page Apr 6, 2020 · 18 revisions

Panel server

  • Server → klient v1.1
  • Klient → server v1.1

Panel server je server implementující jednoduchý textový protokol vlastního návrhu.

Panel server je primární komunikační kanál pro připojené klienty, umožňuje připojení panelů, regulátorů, debugovacích nástrojů apod. Panel server umožňuje komunikaci v obou směrech (server → klient, klient → server).

Panel server je zakompilovaný přímo v hJOPserveru, spouští se automaticky při spouštění systémů. Panel server pro většinu příkazů vyžaduje autentizaci.

Technická specifikace

  • Se serverem se komunikuje výhradně v kódování UTF-8.
  • Výchozí port serveru je 5896.
  • Komunikace probíhá ve zprávách. Zpráva je jeden řádek ukončený znakem LF.
  • Každá strana může posílat zprávy kdykoliv uzná za vhodné, žádná strana by neměla předpokládat, že na zprávu, která me ve specifikaci uvedeno, že na ni následuje odpověď, přijde odpověď hned jako další zpráva.

Syntax zprávy

Každá zpráva se skládá z několika řetězců dohromady spojených znakem ; (středník). Řetězec sám může být složený z dalších podřetězců, toto je vždy definováno u konkrétní zprávy níže.

Příklad:

-;MOD-CAS;STOP;

je validní zpráva skládající se z řetězců:

  1. -
  2. MOD-CAS
  3. STOP

Středník na konci zprávy je nepovinný.

Pozor: zpráva může obsahovat prázdný řetězec, např. -;VYL;;AC;, kde prázdný řetězec mezi dvěma středníky musí být korektně naparsován jako prázdné pole a text AC musí být naparsován jako text na indexu 3 (při indexování zleva od nuly).

Pozor: Protokol spoléhá na konkrétní pozice řetězců, je proto nutné příchozivší text správně parsovat!

Nedělitelný text

Text uvedený ve složených závorkách se nedělí!

Příklad:

-;VYL;{ahoj;baba}

je naparsován takto:

  1. -
  2. VYL
  3. ahoj;baba

nikoliv takto:

  1. -
  2. VYL
  3. {ahoj
  4. baba}

Protože protokol obsahuje několik speciálních znaků (zatím víme jen o středníku), ale v budoucnu se objeví další, je nutné escapovat text od uživatele právě pomocí složených závorek. Tím se předejde tomu, co je v terminologii webů nazváno SQL injection.

Váš program by měl všechny vstupy od uživatele zavírat do složených závorek a neumožnit uživateli zadat složené závorky!

Uživateli také zakažte vložit znak nového řádku. Znaky

  1. {
  2. }
  3. newline

jsou jediné tři znaky, které je potřeba uživateli zakázat vložit.

Všimněte si také, že poslední příklad naparsoval text {ahoj;baba} jako ahoj;baba, nikoliv jako {ahoj;baba}. Toto chování je správné a chtěné! Vaše parsovátko by s ním mělo počítat

Je také nutné počítat s vnořenými řetězci. Příklad:

-;SOB;{LOS;KLOKAN;{VEDRO;VUL}};

je naparsován takto:

  1. -
  2. SOB
  3. LOS;KLOKAN;{VEDRO;VUL}

Po zavolání parsovátka na 2. položku je naparsováno:

  1. LOS
  2. KLOKAN
  3. VEDRO;VUL

Řetězec VEDRO;VUL lze opět parsovat dále.

Teď si jistě dovedete představit hezké rekurzivní parsovátko, které vytváří slovníkovou strukturu. Toto ale není dobrý nápad, protože některé zprávy mají jiné oddělovače. Příklad:

-;TEST;{AHOJ|BABA}

Sémantika zprávy

  • Zpráva může obsahovat klíčová slova a čisté stringy: například konkrétní text štítku, výluky, poznámku k soupravě, ...
  • Na velikosti písmen klíčových slov nezáleží! SET-PROPERTY = set-property = SeT-prOPeRtY
  • Jako kořenový oddělovač je vždy použit středník.
  • Nultý řetězec každé zprávy je buď:
    1. unikátní id oblasti řízení (například klb) značící, že zpráva patří určité oblasti řízení, nebo
    2. - (spojovník) značící, že zpráva patří klientu/serveru obecně, nikoliv oblasti řízení (např. příkaz k nastavení modelového času).

Popis specifikace

Níže následuje popis konkrétních zpráv, v tomto popisu budeme používat speciální značky:

  1. [] (hranaté závorky) značí, že na tomto poli může následovat jedna z hodnot uvedených v závorce; hodnoty jsou oddělené čárkou. Například: [OK,ERR] značí, že text může být buď OK nebo ERR.
  2. zprava(libovolný podtržený text) značí, že podtržený text není klíčové slovo, ale konkrétní text významu podtrženého slova. Například poznamka k bloku specifikuje, že na tomto místě má být libovolný text značící poznámku k bloku.
  3. odkaz (text italic) specifikuje, že na tomto místě je další zpráva, která je definovaná v odkazu. Například -;specifikace hnaciho vozidla.
  4. /parametr/ v lomítkách je nepovinný parametr.

Následující stránky obsahují specifikace objektů posílaných v požadavcích a odpovědích.

Workflow protokolu

  1. Klient se připojí k serveru pomocí protokolu TCP.
  2. Klient pošle handshake.
  3. Klient vyčká na odpověď na handshake.
  4. Po úspěšném přijetí odpovědi klientem je navázána komunikace.
  5. Klient pak typicky autentizuje uživatele.
  6. Probíhá komunikace.
  7. Klient se odpojí, nebo je odpojen serverem.

Konkrétní zprávy

Konkrétních zpráv je mnoho, proto jsou rozdělené do více stránek podle typu klienta:

Obecné definice

Changelog server → klient

  • v1.0: první verze protokolu
  • v1.1: změněn formát souprav v trati (doplněna možnost posílat barvy)

Changelog klient → server

  • v1.0: první verze protokolu
  • v1.1: změněn význam kliků panelu
Clone this wiki locally