CRA IoT HUB REST API

CRA IoT HUB REST API je HTTP-based API umožňující programatický přístup k datům ze senzorů v síti LoRa, provozované Českými Radiokomunikacemi (CRA). API umožňuje pouze čtení záznamů.

Struktura API

Pro zájemce jsou k dispozici data ze 3 endpointů:

• /project. Obsahuje data o jednotlivých projektech – lokacích, ve kterých jsou umístěna čidla (např. Žižkovská věž, zahradnictví…).
• /device. Obsahuje data o jednotlivých zařízeních / čidlech, které jsou dostupné v konkrétní lokaci (např. veškerá čidla, která jsou umístěna na Žižkovské věži)
• /message. Obsahuje data z konkrétního čidla (Např. naměřené hodnoty teplot z teplotního čidla umístěného na vyhlídce Žižkovské věže)

Ověření

Ke každému requestu je nutné připojit parametr token, který je unikátní pro každého uživatele. Lze jej získat pouze přihlášením do HUBu. Veškerá aktivita je logována.

Omezení

Celkem lze z jednoho requestu získat maximálně 10 000 záznamů. V případě nutnosti vytěžení většího množství záznamů, použijte parametr offset a rozložte požadavek mezi více requestů.

Formát odpovědi

Odpovědi jsou ve formátu JSON. Samotné záznamy jsou zapouzdřené v obálce, která obsahuje meta data o úspěchu / neúspěchu volání a počtu vrácených záznamů.

Příklad úspěšného volání

{"_meta":{"status":"SUCCESS","count":7},"records":{...}}

Příklad neúspěšného volání

{"_meta":{"status":"ERROR","count":1},"records":{"errorCode":404,"userMessage":"Not Found.","devMessage":"That route was not found on the server.","more":"Check route for misspellings.","applicationCode":"N1000"}}

Tabulka chyb

Kód chyby (Application code)	Popis
T1000	Neautorizovaný požadavek – chybějící nebo neplatný parametr token
N1000	Neexistující / neplatná URL
F1001	Chybná hodnota parametru order – musí být „asc“ nebo „desc“
F1002	Chybná hodnota parametru start – musí být ve formátu 2016-01-01T01:50:50
F1003	Chybná hodnota parametru stop – musí být ve formátu 2016-01-01T01:50:50

/project/get

Slouží k získání informací o jednotlivých projektech – lokacích, ve kterých jsou umístěna čidla.

Parametry

Parametr	Povinný	Výchozí hodnota
token Slouží k autorizaci requestu a je unikátní pro každého uživatele. Pro jeho vygenerování kontaktujte CRA.	Ano
limit Omezení počtu vypsaných záznamů. Hodnota musí být přirozeným číslem (1,2,3…N).	Ne	25
offset Posunutí prvního vypsaného záznamu o N záznamů. Hodnota musí být nezáporné celé číslo (0,1,2,3…N)	Ne	0

Pole odpovědi

Parametr	Datový typ
projectId ID projektu	string
devEUI ID čidla / zařízení. Použijte jako parametr pro /message/get/:devEUI	string
description Popis zařízení / čidla	string
model Model zařízení / čidla	string
vendor Výrobce zařízení / čidla	string

Vzorový request

GET api.pripoj.me/device/get/TEST?token={TOKEN}

Vzorová odpověď

{"_meta":{"status":"SUCCESS","count":1},"records":[{"devEUI":"4786E6ED00350042","projectId":"TEST","description":"Testovací teplotní čidlo","model":"RHF1S001","vendor":"Rising HF"}]}

/message/get/:devEUI

Slouží k výpisu jednotlivých zpráv z konkrétního zařízení.

Parametry

Parametr	Povinný	Výchozí hodnota
token Slouží k autorizaci requestu a je unikátní pro každého uživatele. Pro jeho vygenerování kontaktujte CRA.	Ano
limit Omezení počtu vypsaných záznamů. Hodnota musí být přirozeným číslem (1,2,3…N).	Ne	25
offset Posunutí prvního vypsaného záznamu o N záznamů. Hodnota musí být nezáporné celé číslo (0,1,2,3…N)	Ne	0
order Řazení záznamů dle časového razítka. Povolené hodnoty jsou asc nebo desc	Ne	desc
start Omezení výpisu zpráv od konkrétního data. Formát 2016-01-01T01:50:50. Zprávy jsou ukládány v časovém pásmu Europe/Prague.	Ne
stop Omezení výpisu zpráv do konkrétního data. Formát 2016-01-01T01:50:50. Zprávy jsou ukládány v časovém pásmu Europe/Prague.	Ne

Pole odpovědi

Parametr	Datový typ
createdAt Časové razítko určující, kdy došlo k přijetí zprávy. Řetězec je konstruován dle standardu ISO-8601. Časové pásmo je UTC	string
devEUI ID čidla / zařízení	string
fPort Komunikační port v rámci LoRaWAN protokolu	integer
fCntUp Uplink counter paketu	integer
aDRBit	integer
fCntDn Downlink counter paketu	integer
payloadHex Payload zprávy. Obsah je hexadecimální kód pro jehož parsování použijte dokumentaci k danému zařízení / čidlu. Vzorový příklad parsování najdete v sekci …	string
micHex Message integrity check v HEX kódu	string
lrrRSSI Hodnota přijatého signálu z koncového zařízení na nejbližší GateWay	float
lrrSNR Hodnota odstupu signálu od šumu z koncového zařízení na nejbližší GateWay	float
spFast Hodnota spreading factoru v komunikaci od koncového zařízení	integer
subBand Použitý subband v rámci 868 MHz pásma	string
channel Použitý kanál v rámci 868 MHz pásma	string
devLrrCnt Počet GateWays, které danou zprávu zachytily	integer
lrrid Identifikátor nejbližší GateWay	string
lrrLAT LAT souřadnice nejbližší Gateway, která zprávu zachytila	float
lrrLON LON souřadnice nejbližší Gateway, která zprávu zachytila	float
lrrs Pole s Gateways, které zprávu zachytily. Pole obsahuje maximálně 3 záznamy. Každý záznam obsahuje Lrrid, LrrRSSI, LrrSNR	<Array>

Vzorový request

GET api.pripoj.me/message/get/4786E6ED00350042?token={TOKEN}

Vzorový request s volitelnými parametry

GET api.pripoj.me/message/get/4786E6ED00350042?token={TOKEN}&start=2016-06-10T00:00:00&order=asc&limit=1000

Vzorová odpověď

{"_meta":{"status":"SUCCESS","count":10},"records":[{"time":"2016-06-15T16:17:31.851+02:00","devEUI":"4786E6ED00350042","fPort":8,"fCntUp":9538,"aDRbit":1,"fCntDn":0,"payloadHex":"01906d711e00ffffc9","micHex":"79b30671","lrcid":"00000065","lrrRSSI":-106.000000,"lrrSNR":0.000000,"spFact":12,"subBand":"G1","channel":"LC1","devLrrCnt":1,"lrrid":"29000049","lrrLAT":50.120018,"lrrLON":14.501301,"lrrs":[{"Lrrid":"29000049","LrrRSSI":-106.000000,"LrrSNR":0.000000}]},...]}