Cloud API

Einige unserer Nixie-Uhren lassen sich programmgesteuert über eine REST API steuern. Diese Funktion bietet Ihnen die Möglichkeit, eigene Zahlen anzuzeigen oder die Helligkeit der Uhr nach Ihren Wünschen zu steuern. Die einzelnen API-Aufrufe werden an unseren Cloud-Server gesendet, der mit der Uhr kommuniziert. Die Uhr muss mit dem Internet verbunden sein, damit die API-Aufrufe ordnungsgemäß funktionieren.

Authentifizierung

Für die Kommunikation mit unseren Uhren müssen Sie die folgenden Variablen kennen bzw. beschaffen:

• EMAIL, PASSWORD – verwenden Sie dieselben Zugangsdaten wie für unsere Web- oder Mobile-App
• ACCESS_TOKEN – diesen erhalten Sie nach erfolgreicher Anmeldung. Jeder weitere API-Aufruf muss mit diesem Token autorisiert werden. Das Sitzungstoken ist 1 Jahr gültig.
• CLOCK_ID – siehe die Tabelle unten im Abschnitt Uhren-IDs.
• API URL – https://api.daliborfarny.com/

Uhren-IDs

Jedes Uhrenmodell hat eine bestimmte Produkt-ID, Zen-Uhren die 2, die 4-Röhren-Puri die 6 usw. Es handelt sich nicht um eine Seriennummer, die für jede Uhr eindeutig ist.

Abrufen des ACCESS_TOKEN

Verwenden Sie Ihre EMAIL und Ihr PASSWORD, um das ACCESS_TOKEN zu erhalten. Ersetzen Sie EMAIL und PASSWORD durch die tatsächlichen Zugangsdaten, die Sie auf https://user.daliborfarny.com/ oder in der mobilen App verwenden.

Spezifikation des API-Aufrufs:

• Anfragetyp – POST
• Endpunkt-URL – /oauth/token
• Anfrage-Body – client_id=3rdparty&client_secret=ws7TQHXp5W6444t4&grant_type=password&username=EMAIL&password=PASSWORD

Beispiel für einen API-Aufruf mit curl:

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

Der Server antwortet mit einem JSON, das das access_token enthält:

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

Sie können diesen Schritt manuell über die Befehlszeile testen:

Abrufen einer Liste Ihrer Uhren

Der nächste Schritt besteht darin, eine Liste der Uhren abzurufen, die mit Ihrem Konto gekoppelt sind. Die Kopplung erfolgt automatisch, während die Uhr mit dem Internet verbunden wird. Ersetzen Sie ACCESS_TOKEN durch das Zugriffstoken, das Sie im vorherigen Schritt erhalten haben.

Spezifikation des API-Aufrufs:

• Anfragetyp – GET
• Endpunkt-URL – /v1/devices?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Beispiel für einen API-Aufruf mit curl:

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

Die vom Cloud-Server zurückgegebene JSON-Antwort:

{
   "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"
      }
   ]
}

Überprüfen der Online-Verbindung der Uhr mit der Cloud

Nun müssen wir prüfen, ob die Uhr mit der Cloud verbunden ist und wir mit ihr „sprechen“ können.

Spezifikation des API-Aufrufs:

• Anfragetyp – GET
• Endpunkt-URL – /v1/devices/CLOCK_ID/online?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Beispiel für einen API-Aufruf mit curl:

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

Die vom Cloud-Server zurückgegebene JSON-Antwort:

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

Auslesen der Konfigurationsparameter

Alle Konfigurationsparameter sind in der Uhr selbst gespeichert. Wir können sie auslesen, indem wir API-Aufrufe gemäß der folgenden Spezifikation senden. PARAMETER ist durch den tatsächlichen Namen des Parameters zu ersetzen, den wir aus der Uhr auslesen möchten.

Spezifikation des API-Aufrufs:

• Anfragetyp – GET
• Endpunkt-URL – /v1/devices/CLOCK_ID/PARAMETER?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Beispiel für einen API-Aufruf mit curl, um den Wert des Parameters „transition“ abzurufen:

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

Die vom Cloud-Server zurückgegebene JSON-Antwort, der Parameterwert ist in diesem Beispiel „2“.

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

Senden der Konfigurationsparameter

Alle Konfigurationsparameter sind in der Uhr selbst gespeichert. Um einen bestimmten Parameter zu ändern, müssen wir einen API-Aufruf wie unten beschrieben ausführen. PARAMETER ist durch den tatsächlichen Namen des Parameters zu ersetzen, den wir in der Uhr ändern möchten. VALUE ist der tatsächliche Wert, auf den wir PARAMETER setzen möchten.

Spezifikation des API-Aufrufs:

• Anfragetyp – POST
• Endpunkt-URL – /v1/devices/CLOCK_ID/PARAMETER
• Anfrage-Body – access_token=ACCESS_TOKEN&arg=VALUE&client_secret=ws7TQHXp5W6444t4&client_id=3rdparty

Beispiel für einen API-Aufruf mit curl – auf diese Weise können wir den Parameter „transition“ auf den Wert 3 setzen.

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

Die vom Cloud-Server zurückgegebene JSON-Antwort:

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

Konfigurationsparameter

Parameter	Zen	NixieMachineII	NixieMachineIII	NX2	PURI4	PURI6	Parameter-Schlüsselwort	Lesen/Schreiben
Uhren-ID	2	3	9	4	6	15
	Zulässige Werte
Zeitformat	12, 24						format	RW
Führende Null	1, 2						leadingzero	RW
Sommerzeit	1, 2, 3						dst	RW
Zeitzone							timezone	RW
Anzeige des Datums	1, 2, 3, 4, 5						datedisplay	RW
Ziffernübergang	1, 2, 3, 4						transition	RW
Regenerierungsintervall der Kathoden	1, 10, 30, 98						slotmachineperiod	RW
Modus der System-LED	1, 2, 3						photonled	RW
Modus der Unterbeleuchtung	1,2	–	–	–	–	–	underlightmode	RW
Segmente der Unterbeleuchtung	1, 2, 4, 6	–	–	–	–	–	underlightsegments	RW
Farbe der Unterbeleuchtung	1 – 2^32	–	–	–	–	–	underlightsolidcolor	RW
Helligkeit im Tagmodus	1, 6, 71, 126, 201, 256						brightnessday	RW
Helligkeit im Nachtmodus	1, 6, 71, 126, 201, 256						brightnessnight	RW
Zeitplan							nmstr	W
Doppelpunkt-Modus	1, 2, 3	–	–	–	1, 2, 3	1, 2, 3	colonmode	RW
Betriebsleuchte	–	1, 2	1, 2	–	–	–	powerlight	RW
Verbindungsmodus	1, 2						connectivitymode	RW
Zeit	1, 2						time	RW
Benutzerdefinierte Daten	XXXXXXXX						customdata	W
Timeout für benutzerdefinierte Daten	0-255						customdatatimeout	RW
Countdown starten	1-359999						startcountdown	W
In den Zeitmodus wechseln	1						switchtotimemode	W
Slot-Machine-Modus	1,2						slotmachinemode	RW
Neustart der Uhr	1						reset	W
Homekit-Reset	1						homekitreset	W
RTC-Kalibrierung							rtccalibration	RW
System-Firmware							systemfirmware	R
Firmware-Version							firmware	R
WLAN-Signalstärke							rssi	R
Watchdog-Neustarts							watchdogevents	R
Uhren-ID							productid	R
Seriennummer der Uhr	0-99999						serialnumber	RW
Homekit-Verbindungen							hkconnectionsnumber	R
Größter freier Speicherblock							largestfreeblockheap	R
Freier Speicher							freememory	R
Aktuell angezeigter Wert							currentdisplayedvalue	R
Abweichung bei der letzten NTP-Synchronisierung							lastntpsyncmillis	R
OTA-Updates							otaenabled	R
MAC-Adresse							macaddr	R

Erläuterung der einzelnen Konfigurationsparameter

Zeitformat

12 = 12-Stunden-Format, 24 = 24-Stunden-Format

Führende Null

1 = AUS, 2 = EIN

Sommerzeit

1 = AUS, 2 = EIN, 3 = Automatisch

Zeitzone

Anzeige des Datums

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

Ziffernübergang

1 = Normal, 2 = Überblenden, 3 = Spielautomat, 4 = Spielautomat/Überblenden

Modus der System-LED

1 = Immer an, 2 = Aus, wenn online, 3 = Immer aus

Regenerierungsintervall der Kathoden

1 = Jede Minute, 10 = Alle 10 Minuten, 30 = Alle 30 Minuten, 98 = Einmal täglich um 3:00 Uhr

Modus der Unterbeleuchtung

1 = AUS, 2 = Einfarbig

Segmente der Unterbeleuchtung

1 = Alle aus, 2 = Nur unten, 4 = Nur oben, 6 = Alle an

Farbe der Unterbeleuchtung

32-Bit-Wert, 0b00000000BBBBBBBBGGGGGGGGRRRRRRRR

Doppelpunkt-Modus

1 = AUS, 2 = Dauerhaft an, 3 = Überblenden

Betriebsleuchte

1 = EIN, 2 = AUS

Verbindungsmodus

1 = Online, 2 = Offline

Zeit

Unix-Zeitstempel (UTC+0) in Sekunden, funktioniert nur im Offline-Modus (im Online-Modus wird er überschrieben).

Benutzerdefinierte Daten

8 Zeichen, die 6 Röhren und 2 Doppelpunkt-Röhren darstellen (auf der Puri-4 werden zwei Röhren und ein Doppelpunkt nicht angezeigt).

Sonderzeichen:

• „_“ schaltet die Position dunkel (funktioniert sowohl für Doppelpunkt- als auch für Ziffernröhren)
• „:“ beide Punkte aktiviert, nur für Doppelpunkt-Röhren
• „.“ unterer Punkt aktiviert, nur für Doppelpunkt-Röhren
• „;“ oberer Punkt aktiviert, nur für Doppelpunkt-Röhren

Beispiele für Zeichenketten:

• „12_34_56“ zeigt 123456 auf den Nixie-Röhren an, die Doppelpunkt-Röhren bleiben dunkel
• „_____.25“ zeigt 25 auf dem rechten Röhrenpaar und einen unteren Punkt auf der rechten Doppelpunkt-Röhre an
• „;15;“ schaltet alle Röhren außer dem mittleren Paar dunkel, beide Doppelpunkte zeigen den oberen Punkt

Timeout für benutzerdefinierte Daten

Dieser Parameter teilt der Uhr mit, nach welcher Zeit sie nach dem Empfang benutzerdefinierter Daten wieder in den Zeitmodus (Anzeige der Uhrzeit) wechseln muss. Für eine bessere Auflösung wird die tatsächliche Dauer als Quadrat des gesendeten Wertes berechnet. Wenn Sie den Wert „5“ senden, beträgt das Timeout 25 Sekunden (5 × 5 = 25).

Countdown starten

Dieser Aufruf startet einen Countdown-Timer, der Parameter ist die gewünschte Dauer in Sekunden. Wenn Sie einen Countdown-Timer für 3 Minuten starten möchten, rufen Sie ihn mit dem Parameter 180 (3*60) auf.

In den Zeitmodus wechseln

Rufen Sie diesen Parameter auf, um die Uhr in den Zeitmodus zu schalten (z. B. aus dem Modus für benutzerdefinierte Daten, aus dem Slot-Machine-Modus oder aus dem Countdown-Timer).

Slot-Machine-Modus

1 = aktivieren, 2 = deaktivieren

Homekit-Reset

Rufen Sie diesen Parameter auf, um die aktuelle Homekit-Kopplung zu löschen und auf die Standardeinstellung zurückzusetzen.

RTC-Kalibrierung

Zulässige Werte (in 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

Seriennummer der Uhr

Die Seriennummer wird von uns nach der Herstellung der Uhr festgelegt, bitte ändern Sie sie daher nicht.

Homekit-Verbindungen

Die Anzahl der Clients (iPhones, iPads), die aktuell über Homekit mit der Uhr verbunden sind.

Größter freier Speicherblock

Der größte freie allozierbare Speicherblock auf dem Heap in Bytes.

Freier Speicher

Gesamter freier Speicher auf dem Heap in Bytes.

Aktuell angezeigter Wert

Die aktuell auf der Röhrenanzeige dargestellte Zahl, Doppelpunkte werden nicht berücksichtigt.

Abweichung bei der letzten NTP-Synchronisierung

Um wie viele Millisekunden wurde die Systemzeit bei der letzten NTP-Synchronisierung korrigiert?

OTA-Updates

Sind Over-the-Air-Updates aktiviert? 1 = aktiviert, 0 = deaktiviert

MAC-Adresse

Gibt die MAC-Adresse des Geräts zurück