CRA IoT HUB REST API

#PRIPOJME

Logo CRA

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}]},...]}

CRA

 

© 2017 ČESKÉ RADIOKOMUNIKACE A.S.