Cloud API

Některé z našich hodin s digitrony lze programově ovládat přes REST API. Tato funkce Vám umožňuje zobrazovat na hodinách vlastní čísla nebo ovládat jejich jas podle Vašich představ. Jednotlivá volání API se odesílají na náš cloudový server, který s hodinami komunikuje. Aby volání API fungovala správně, musí být hodiny připojeny k internetu.

Autentizace

Pro komunikaci s našimi hodinami budete potřebovat znát nebo získat následující proměnné:

• EMAIL, PASSWORD – použijte stejné přihlašovací údaje jako pro naši webovou nebo mobilní aplikaci
• ACCESS_TOKEN – získáte jej po úspěšném přihlášení. Každé další volání API musí být autorizováno tímto tokenem. Platnost tokenu relace je 1 rok.
• CLOCK_ID – viz tabulka níže v sekci ID hodin.
• API URL – https://api.daliborfarny.com/

ID hodin

Každý model hodin má určité ID produktu, hodiny Zen 2, čtyřdigitronové Puri 6 atd. Nejde o sériové číslo, které je u každých hodin jedinečné.

Získání ACCESS_TOKEN

K získání ACCESS_TOKEN použijte svůj EMAIL a PASSWORD. Nahraďte EMAIL a PASSWORD skutečnými přihlašovacími údaji, které používáte na https://user.daliborfarny.com/ nebo v mobilní aplikaci.

Specifikace volání API:

• Typ požadavku – POST
• URL endpointu – /oauth/token
• Tělo požadavku – client_id=3rdparty&client_secret=ws7TQHXp5W6444t4&grant_type=password&username=EMAIL&password=PASSWORD

Příklad volání API pomocí curl:

$ curl -X POST https://api.daliborfarny.com/oauth/token -d "client_id=3rdparty&client_secret=ws7TQHXp5W6444t4&grant_type=password&username=EMAIL&password=PASSWORD"

Server odpoví JSONem, který obsahuje access_token:

{
"ok":true,
"status":200,
"data":{
        "access_token":"62dd89362a635ff8692a590456e8a8118e61d9902",
        "expires_in":31536000,
        "token_type":"Bearer",
        "scope":null,
        "refresh_token":"ef687d958f83ad13dff915d89f54ab2d8322193a"
        }
}

Tento krok si můžete ručně vyzkoušet z příkazového řádku:

Získání seznamu Vašich hodin

Dalším krokem je získání seznamu hodin, které jsou spárovány s Vaším účtem. Párování proběhne automaticky během připojování hodin k internetu. Nahraďte ACCESS_TOKEN přístupovým tokenem, který jste získali v předchozím kroku.

Specifikace volání API:

• Typ požadavku – GET
• URL endpointu – /v1/devices?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Příklad volání API pomocí curl:

$ curl -X GET "https://api.daliborfarny.com/v1/devices?client_id=3rdparty&access_token=62dd89362a635ff8692a590456e8a8118e61d9902&client_secret=ws7TQHXp5W6444t4"

JSON odpověď vrácená cloudovým serverem:

{
   "ok":true,
   "status":200,
   "data":[
      {
         "id":"2d001c110c47363463353230",
         "name":"Puri Nixie Clock #51",
         "product_name":"Puri-4 Nixie Clock",
         "img_url":"https:\/\/www.daliborfarny.com\/wp-content\/uploads\/2018\/09\/LKJ4467_1024.jpg",
         "id_product":"6"
      },
      {
         "id":"320029000147373336323320",
         "name":"Puri-4 Nixie Clock #95",
         "product_name":"Puri-4 Nixie Clock",
         "img_url":"https:\/\/www.daliborfarny.com\/wp-content\/uploads\/2018\/09\/LKJ4467_1024.jpg",
         "id_product":"6"
      }
   ]
}

Ověření online připojení hodin ke cloudu

Nyní potřebujeme ověřit, zda jsou hodiny připojeny ke cloudu a zda s nimi můžeme „mluvit“.

Specifikace volání API:

• Typ požadavku – GET
• URL endpointu – /v1/devices/CLOCK_ID/online?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Příklad volání API pomocí curl:

$ curl -X GET "https://api.daliborfarny.com/v1/devices/320029000147373336323320/online?client_id=3rdparty&access_token=62dd89362a635ff8692a590456e8a8118e61d9902&client_secret=ws7TQHXp5W6444t4"

JSON odpověď vrácená cloudovým serverem:

{
   "ok":true,
   "status":200,
   "data":{
      "value":true
   }
}

Čtení konfiguračních parametrů

Všechny konfigurační parametry jsou uloženy přímo v hodinách a můžeme je číst odesíláním volání API podle níže uvedené specifikace. Místo PARAMETER doplňte skutečný název parametru, který chceme z hodin přečíst.

Specifikace volání API:

• Typ požadavku – GET
• URL endpointu – /v1/devices/CLOCK_ID/PARAMETER?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Příklad volání API pro zjištění hodnoty parametru „transition“ pomocí curl:

$ curl -X GET "https://api.daliborfarny.com/v1/devices/320029000147373336323320/transition?client_id=3rdparty&access_token=62dd89362a635ff8692a590456e8a8118e61d9902&client_secret=ws7TQHXp5W6444t4"

JSON odpověď vrácená cloudovým serverem, hodnota parametru je v tomto příkladu „2“.

{
   "ok":true,
   "status":200,
   "data":{
      "value":2
   }
}

Odesílání konfiguračních parametrů

Všechny konfigurační parametry jsou uloženy přímo v hodinách. Pro změnu konkrétního parametru je potřeba provést volání API podle níže uvedené specifikace. Místo PARAMETER doplňte skutečný název parametru, který chceme v hodinách změnit. VALUE je skutečná hodnota, na kterou chceme PARAMETER nastavit.

Specifikace volání API:

• Typ požadavku – POST
• URL endpointu – /v1/devices/CLOCK_ID/PARAMETER
• Tělo požadavku – access_token=ACCESS_TOKEN&arg=VALUE&client_secret=ws7TQHXp5W6444t4&client_id=3rdparty

Příklad volání API pomocí curl – takto můžeme nastavit parametr „transition“ na hodnotu 3.

$ curl -X POST "https://api.daliborfarny.com/v1/devices/320029000147373336323320/transition" -d "access_token=62dd89362a635ff8692a590456e8a8118e61d9902&arg=3&client_id=3rdparty&client_secret=ws7TQHXp5W6444t4"

JSON odpověď vrácená cloudovým serverem:

{
   "ok":true,
   "status":200,
   "data":{
      "value":2
   }
}

Konfigurační parametry

Parametr	Zen	NixieMachineII	NixieMachineIII	NX2	PURI4	PURI6	Klíčové slovo parametru	Čtení/zápis
ID hodin	2	3	9	4	6	15
	Přípustné hodnoty
Formát času	12, 24						format	RW
Uvozovací nula	1, 2						leadingzero	RW
Letní čas	1, 2, 3						dst	RW
Časová zóna							timezone	RW
Zobrazení data	1, 2, 3, 4, 5						datedisplay	RW
Přechodový efekt číslic	1, 2, 3, 4						transition	RW
Interval čištění katod	1, 10, 30, 98						slotmachineperiod	RW
Režim systémové LED	1, 2, 3						photonled	RW
Režim podsvícení	1,2	–	–	–	–	–	underlightmode	RW
Segmenty podsvícení	1, 2, 4, 6	–	–	–	–	–	underlightsegments	RW
Barva podsvícení	1 – 2^32	–	–	–	–	–	underlightsolidcolor	RW
Jas v denním režimu	1, 6, 71, 126, 201, 256						brightnessday	RW
Jas v nočním režimu	1, 6, 71, 126, 201, 256						brightnessnight	RW
Rozvrh							nmstr	W
Režim dvojtečky	1, 2, 3	–	–	–	1, 2, 3	1, 2, 3	colonmode	RW
Kontrolka napájení	–	1, 2	1, 2	–	–	–	powerlight	RW
Režim připojení	1, 2						connectivitymode	RW
Čas	1, 2						time	RW
Vlastní data	XXXXXXXX						customdata	W
Časový limit vlastních dat	0-255						customdatatimeout	RW
Spuštění odpočtu	1-359999						startcountdown	W
Přepnutí do režimu času	1						switchtotimemode	W
Režim přeblikávání	1,2						slotmachinemode	RW
Restart hodin	1						reset	W
Reset Homekit	1						homekitreset	W
Kalibrace RTC							rtccalibration	RW
Systémový firmware							systemfirmware	R
Verze firmware							firmware	R
Síla signálu Wi-Fi							rssi	R
Restarty watchdogu							watchdogevents	R
ID hodin							productid	R
Sériové číslo hodin	0-99999						serialnumber	RW
Připojení Homekit							hkconnectionsnumber	R
Největší volný blok paměti							largestfreeblockheap	R
Volná paměť							freememory	R
Aktuálně zobrazená hodnota							currentdisplayedvalue	R
Rozdíl při poslední synchronizaci NTP							lastntpsyncmillis	R
Aktualizace OTA							otaenabled	R
MAC adresa							macaddr	R

Vysvětlení jednotlivých konfiguračních parametrů

Formát času

12 = 12hodinový formát, 24 = 24hodinový formát

Uvozovací nula

1 = VYPNUTO, 2 = ZAPNUTO

Letní čas

1 = VYPNUTO, 2 = ZAPNUTO, 3 = Automaticky

Časová zóna

Zobrazení data

1 = VYPNUTO, 2 = DD, 3 = DDMMYY, 4 = MMDDYY, 5 = YYMMDD

Přechodový efekt číslic

1 = Normální, 2 = Prolínání, 3 = Přeblikávání, 4 = Přeblikávání/prolínání

Režim systémové LED

1 = Vždy zapnuto, 2 = Vypnuto při připojení, 3 = Vždy vypnuto

Interval čištění katod

1 = Každou minutu, 10 = Každých 10 minut, 30 = Každých 30 minut, 98 = Jednou denně ve 3:00

Režim podsvícení

1 = VYPNUTO, 2 = Jedna barva

Segmenty podsvícení

1 = Vše vypnuto, 2 = Pouze spodní, 4 = Pouze horní, 6 = Vše zapnuto

Barva podsvícení

32bitová hodnota, 0b00000000BBBBBBBBGGGGGGGGRRRRRRRR

Režim dvojtečky

1 = VYPNUTO, 2 = Trvale zapnuto, 3 = Pohasínání

Kontrolka napájení

1 = ZAPNUTO, 2 = VYPNUTO

Režim připojení

1 = Online, 2 = Offline

Čas

Unixové časové razítko (UTC+0) v sekundách, funguje pouze v offline režimu (v online režimu se přepisuje).

Vlastní data

8 znaků představujících 6 digitronů a 2 dvojtečkové elektronky (na Puri-4 se dva digitrony a jedna dvojtečka nezobrazují).

Speciální znaky:

• „_“ zhasne danou pozici (funguje pro dvojtečkovou elektronku i pro číselný digitron)
• „:“ rozsvítí obě tečky, pouze pro dvojtečkovou elektronku
• „.“ rozsvítí spodní tečku, pouze pro dvojtečkovou elektronku
• „;“ rozsvítí horní tečku, pouze pro dvojtečkovou elektronku

Příklady řetězců:

• „12_34_56“ zobrazí na digitronech 123456 a dvojtečkové elektronky zhasne
• „_____.25“ zobrazí 25 na pravé dvojici digitronů a spodní tečku na pravé dvojtečkové elektronce
• „;15;“ zhasne všechny digitrony kromě prostřední dvojice, obě dvojtečky zobrazí horní tečku

Časový limit vlastních dat

Tento parametr určuje, po jaké době se hodiny po přijetí vlastních dat musí vrátit do režimu času (zobrazování času). Pro lepší rozlišení se skutečná doba počítá jako druhá mocnina odeslané hodnoty. Pokud odešlete hodnotu „5“, časový limit bude 25 sekund (5 × 5 = 25).

Spuštění odpočtu

Toto volání spustí odpočet, parametrem je požadovaná doba v sekundách. Pokud chcete spustit odpočet na 3 minuty, zavolejte jej s parametrem 180 (3*60).

Přepnutí do režimu času

Zavoláním tohoto parametru přepnete hodiny do režimu času (např. z režimu vlastních dat, z režimu přeblikávání nebo z odpočtu).

Režim přeblikávání

1 = aktivovat, 2 = deaktivovat

Reset Homekit

Zavoláním tohoto parametru smažete aktuální párování Homekit a obnovíte jeho výchozí stav.

Kalibrace RTC

Přípustné hodnoty (v PPM):

-63,-61,-59,-57,-55,-53,-51,-49,-47,-45,-43,-41,-39, -37,-35,-33,-31,-28,-26,-24,-22,-20,-18,-16,-14,-12, -10,-8,-6,-4,-2,0,4,8,12,16,20,24,28,33,37,41,45,49, 53,57,61,65,69,73,77,81,85,90,94,98,102,106,110,114,118,122,126

Sériové číslo hodin

Sériové číslo nastavujeme my po výrobě hodin, proto ho prosím neměňte.

Připojení Homekit

Počet klientů (iPhony, iPady), kteří jsou aktuálně připojeni k hodinám přes Homekit.

Největší volný blok paměti

Největší volný alokovatelný blok paměti na haldě, v bajtech.

Volná paměť

Celková volná paměť na haldě v bajtech.

Aktuálně zobrazená hodnota

Číslo aktuálně zobrazené na digitronech, dvojtečky se nezapočítávají.

Rozdíl při poslední synchronizaci NTP

O kolik milisekund byl systémový čas upraven při poslední synchronizaci NTP?

Aktualizace OTA

Jsou povoleny aktualizace vzduchem (Over The Air)? 1 = povoleno, 0 = zakázáno

MAC adresa

Vrací MAC adresu zařízení