Skip to content

ptServer

Jump to bottom
Jan Malina edited this page Jul 12, 2025 · 2 revisions

PT server v3.2

PT server je http server implementující REST API. Jeho účel je

  • umožnit vzdálenou správu hJOPserveru,
  • umožnit komunikaci s hJOP pro externí řízení kolejiště,
  • poskytnout rozhraní k řízení kolejiště pro studenty MENDELU.

S PT serverem se komunikuje ve formátu JSON. Veškerá dokumentace, jména endpointů, atributů a ostatně všeho jsou v češtině.

PT server je zakompilovaný v základní verzi hJOPserveru, avšak automaticky se nespouští. PT server nevyžaduje žádnou autentizaci, což by mělo být, vzhledem k vypnutému serveru by default, únosně bezpečné.

Funkcionalita

PT server umožňuje toto:

  • dotazovat server na data a stav bloků, hv, jc, ...,
  • přestavit výhybky,
  • řídit hnací vozidlo na základě adresy,
  • stavět jízdní cesty.

Technická specifikace

  • Se serverem se komunikuje výhradně v kódování UTF-8.
  • Server na každý požadavek vrací 200 OK.
    • Výjimka: neautentizovaný požadavek (vrací se kód 401).
  • Výchozí port serveru je 5823.
  • Chyby při zpracování požadavků jsou zaneseny do odpovědi jako errors objekt. Viz specifikace
  • Při požadavcích, které obsahují tělo (PUT, POST, ...), je nutné nastavit hlavičku Content-type na hodnotu application/json. Požadavek s jiným Content-type nebude zpracován.
  • Požadavky nesmí obsahovat UTF-8 BOM. Odpovědi serveru neobsahují UTF-8 BOM.

Autentizace (od verze 2)

  • Všechny GET požadavky je možné odesílat bez autentizace, všechny PUT, POST a DELETE požadavky vyžadují autentizaci.
  • Pro autentizaci je využíván http simple auth.
  • Klient má své uživatelské jméno a heslo. Tyto údaje zřetězí pomocí dvojtečky (login:password), zakóduje výsledný řetězec do base64 a pošle v hlavičce Authorization takto: Basic <base64-encoded-string>.

JSON data

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

Obecné poznámky

Kdykoliv je v GET parametru předáván argument typu Boolean, může parametr nabývat hodnot:

  • true/false v jakékoliv velikosti písmen (napr. tRue je také validní), nebo
  • 0/1.

Konfigurace serveru

PTserver má záznam v konfiguračním souboru data/konfigurace.ini:

[PTServer]
port=5823
compact=0

U serveru je možné změnit jeho port a jestli mají být odpovědi serveru kompaktní.

[PTServerStaticTokens]
user1=password1
user2=password2
...

V sekci PTServerStaticTokens se uvádí dvojice uživatelských jmen a hesel, které mají trvalý přístup pro zápis v hJOPserveru (PUT požadavky).

Vhodnější alternativou je provázat klientskou aplikaci s blokem AC v hJOPserveru. Pokud je AC aktivní, uživatel se jménem ID bloku a heslem uvedeným v konfiguraci bloku dostává přístup pro zápis skrze PT server.

Endpointy serveru

Historie revizí

  • v1.0: první verze PT serveru
  • v1.1: sekce mtb nahrazena sekcí rcs
  • v1.2: odstraněno API stanic, přidáno API jízdních cest
  • v2.0: přidána (povinná) autentizace uživatelů
  • v2.1: přidáno API souprav
  • v2.2: přidáno API uživatelů, umožněno PUT, DELETE a POST API souprav
  • v3.0: data všech endpointů převedena do angličtiny, přidán endpoint oblasti řízení.
  • v3.1: přidán endpoint status
  • v3.2: přidány RCS simulační volby, umožněn nastavovat čas

Clone this wiki locally