ČVUT FEL - Linky

Tokeny

POST /Token/Create - Vytvoř token

Vytvoří uživateli nový token. Tokeny jsou tvořeny ve dvou módech řízených pomocí parametru debug. Tento parametr je defaultně nastaven na true.

V debug režimu se výstup zobrazuje pouze na webu:
  * Tento režim je přístupný všem.
  * Je přístupný po přihlášení na adrese https://linky.fel.cvut.cz/Debugger

V normálním režimu se přístup zobrazuje i na samotných LINKY. Je zde ale více omezení:
  * Účet musí mít povolení k normálnímu režimu
  * Provoz je limitován provozním řádem LINKY (na hlavní stránce dole)
  * Provoz využívá frontu, v případě že je více aktivních tokenů, viz níže.

Tokenová fronta:
  * Každý token má přiděleno 3 minuty času.
  * Pokud neexistuje aktivní token, tak nový token platí od současného času.
  * Pokud již existuje aktivní token, či fronta tokenů tak se nový token vytvoří od konce posledního tokenu.
  * Token lze prodloužit pouze pokud ve frontě nečekají další tokeny.

Tudíž v případě kdy nikdo další nemá aktivní zájem o připojení k LINKY tak lze token prodlužovat do nekonečna.
Pokud je zájem o připojení tak má každý klient pouze 3 minuty vyhraněného času.

Parametry

Pole	Typ	Popis
user_id	string	Uživatelské ID (Zjistíte na dashboardu po přihlášení)
user_secret	string	Uživatelský kód (Zjistíte na dashboardu po přihlášení)
debug	boolean	Debug režim je privátní s výstupem na webu, pokud je nastaveno na false tak bude výstup zobrazován i na LINKY. Defaultní hodnota je `true`
fps	int[10-44]	Počet framů za sekundu pro animaci v rozmezí 10 až 44. (44 je horní limit panelů linky) Defaultní hodnota je `22`

Odpovědi

Popis

Token byl vytvořen

Parametry

Pole	Typ	Popis
access_token	string	Token
refresh_token	string	Refresh token
expires_at	int	Token je validní před daným časem (Unix timestamp)
expires_in	int	Token je validní následujících n sekund
valid_from	int	Token je validní po daném česu (Unix timestamp)

Ukázka json

{
   "access_token": "xrpzjhy4l3s7i4w2ueov",
   "refresh_token": "n97qfk2i6rmad4qn8e5p",
   "valid_from" :1540461600,
   "expires_at": 1540461900,
   "expires_in": 360,
}

Popis

Vraceno pokud user_id či user_secret nesedí k žádnému aktivnímu účtu.

Parametry

Pole	Typ	Popis
code	int	Http code
message	string	Chybová hláška
error_id	string	Interní chybové id

Ukázka json

{
   "code": 401
   "message": "Account with given user_id and user_secret doesn´t exist."
   "error_id": 153256
}

Popis

Vraceno pokud účet nemá opravnění k zobrazování dat na LINKY. Vraceno pouze při debug=false

Parametry

Pole	Typ	Popis
code	int	Http code
message	string	Chybová hláška
error_id	string	Interní chybové id

Ukázka json

{
   "code": 403
   "message": "Account doesn´t have access to LINKY."
   "error_id": 100536
}

Popis

Vraceno pokud služba není dostupná. (Mimo provoz LINKY, atd.) Vraceno pouze při debug=false

Parametry

Pole	Typ	Popis
code	int	Http code
message	string	Chybová hláška
error_id	string	Interní chybové id

Ukázka json

{
   "code": 503
   "message": "LINKY are offline between 21PM and 8 AM"
   "error_id": 956356
}

POST /Token/Refresh - Obnovit token

Prodlouží token pokud není žádný jiný token ve frontě.

Parametry

Pole	Typ	Popis
refresh_token	string	Refresh token. Viz: Vytvoř token

Odpovědi

Popis

Token byl prodloužen.

Popis

Refresh token nebyl nalezen či již není platný.

Popis

Došlo k jedné ze dvou situací. Buď je ve frontě již další token/uživatel čekající na LINKY. Či nelze prodloužit z důvodů ukončení provozu LINKY API (Po 21:00).

Popis

Ochrana před častým prodlužováním tokenů.

GET /Token/Queue - Fronta tokenů

Vrátí informace o aktuální frontě tokenů.

Odpovědi

Parametry

Pole	Typ	Popis
token_count	int	Počet tokenů ve frontě
last_end_at	int	Čas ve který poslední token končí. (Unix timestamp)

Ukázka json

{
   "token_count": 4,
   "last_end_at": 1540461900
}

Play

POST /Play - REST

Play je hlavní částí celé LinkyAPI. Pomocí tohoto endpointu posíláte do LinkyAPI data k zobrazení.


Formát snímků
Snímky (Frames) jsou řazeny tak jak jdou za sebou v json poli. Pole má podobu ''hodnota[snímek][sloupec][řádek]''

Snímky jdou přeskakovat pokud má daný snímek hodnotu null. Tudíž pokud je například každý druhý snímek null, tak lze dosáhnout poloviční rychlosti (11fps) na výstupu.

Parametry

Pole	Typ	Popis
access_token	string	Uživatelův token. Viz: Vytvoř token
frames	int[][][][] \| string[][][]	Jednotlivé snímky animace. První prostor značí snímek. Druhý prostor značí sloupec. Třetí prostor značí řádek. Snímek/Sloupec/Řádek lze přeskočit pokud je jeho hodnota null. Formát barvy je [R,G,B],[R,G,B,W],'#RRGGBB', či '#RRGGBBWW'. W je bílá barva.
clear_buffer	boolean	Vyčistí buffer a rovnou začne zobrazovat data z tohoto requestu Defaultní hodnota je `false`

Odpovědi

Popis

Data byla přijata

Parametry

Pole	Typ	Popis
frames	string[]	ID všech framů vytvořených během tohoto requestu.

Popis

Vraceno pokud formát zprávy je nesrozumitelný. Například špatný počet sloupců ve frame, atd.

Parametry

Pole	Typ	Popis
code	int	Http code
message	string	Chybová hláška
error_id	string	Interní chybové id

Ukázka json

{
   "code": 400
   "message": "Malformed 'frames' syntax."
   "error_id": 153256
}

Popis

Vraceno pokud token neexistuje nebo již není platný

Parametry

Pole	Typ	Popis
code	int	Http code
message	string	Chybová hláška
error_id	string	Interní chybové id

Ukázka json

{
   "code": 401
   "message": "Token not found or expired."
   "error_id": 153256
}

Popis

Vraceno pokud služba není dostupná. (Mimo provoz LINKY, atd.) Vraceno pouze při debug=false

Parametry

Pole	Typ	Popis
code	int	Http code
message	string	Chybová hláška
error_id	string	Interní chybové id

Ukázka json

{
   "code": 503
   "message": "LINKY are offline between 21PM and 8 AM"
   "error_id": 956356
}

Informační

GET /DataState/Png - Současná data v png

Vrátí současná data z LINKY v png formátu

Parametry

Pole	Typ	Popis
scale_x	int	Scalování po ose x Defaultní hodnota je `50`
scale_y	int	Scalování po ose y Defaultní hodnota je `3`

Odpovědi

GET /DataState - Současná data v json

Vrátí současná data z LINKY v json formátu

Odpovědi

Parametry

Pole	Typ	Popis
data	int[][][]	Vrací int pole o velikosti [5][204][4] První prostor jsou sloupce Druhý prostor jsou řádky sloupců Třetí prostor je barva: R G B A

GET /State - Současný stav

Vrátí informace o aktuální stavu linek

Odpovědi

Parametry

Pole	Typ	Popis
active	boolean	True pokud LINKY běží
active_from	int	Čas od kolika běží linky (HHMM formát) Defaultní hodnota je `0800`
active_to	int	Čas do kolika běží linky (HHMM formát) Defaultní hodnota je `2100`
disabled_times	int[][]	Časy ve které jsou LINKY vypnuté kvůli akcím, atd. První rozměr pole jsou jednotlivé úseky. Druhý rozměr pole je start_time a end_time (UNIX formát)
columns	int	Počet sloupců Defaultní hodnota je `5`
rows	int	Počet LED v každém sloupci. (Během léta nižší počet viz Pravidla provozu) Defaultní hodnota je `204`
max_intensity	int	Maximální intensita v rozmezí 0-255 Defaultní hodnota je `255`

Tokeny

POST /Token/Create - Vytvoř token

Parametry

Odpovědi

200 OK

Popis

Parametry

Ukázka json

401 Bad credentials

Popis

Parametry

Ukázka json

403 Forbidden

Popis

Parametry

Ukázka json

503 Service Unavailable

Popis

Parametry

Ukázka json

POST /Token/Refresh - Obnovit token

Parametry

Odpovědi

200 OK

Popis

404 Not found

Popis

409 Conflict

Popis

429 Too Many Requests

Popis

GET /Token/Queue - Fronta tokenů

Odpovědi

200 OK

Parametry

Ukázka json

Play

POST /Play - REST

Formát snímků

Parametry

Odpovědi

200 OK

Popis

Parametry

400 Bad Request

Popis

Parametry

Ukázka json

401 Bad credentials

Popis

Parametry

Ukázka json

503 Service Unavailable

Popis

Parametry

Ukázka json

Informační

GET /DataState/Png - Současná data v png

Parametry

Odpovědi

200 OK

GET /DataState - Současná data v json

Odpovědi

200 OK

Parametry

GET /State - Současný stav

Odpovědi

200 OK

Parametry