Cloud API

Some of our nixie clocks can be controlled programmatically over REST API. This feature offers possibilities to display custom numbers or control brightness over the clock as you wish. Individual API calls are sent to our cloud server that communicates with the clock. The clock must be connected to the internet to make the API calls work properly.

Authentication

You will need to know or get the following variables for communication with our clocks:

• EMAIL, PASSWORD – use the same credentials as for our web or mobile app
• ACCESS_TOKEN – you will get one after successful login. Every other API call must be authorized using this token. Session token has an expiration time of 1 year.
• CLOCK_ID – See the table below in section Clock IDs.
• API URL – https://api.daliborfarny.com/
  

Clock IDs

Each clock model has a certain product ID, Zen clocks 2, 4-tube Puri 6, etc. This is not a serial number that is unique for each clock.

Clock Name	Clock ID
Zen Nixie Clock	2
Puri Nixie Clock (4-tube)	6
Puri Nixie Clock (6-tube)	15
Nixie Machine II	3
Nixie Machine III	9
NX.2	4

Obtaining the ACCESS_TOKEN

Use your EMAIL and PASSWORD to obtain ACCESS_TOKEN. Replace EMAIL and PASSWORD with the actual credentials you are using on https://user.daliborfarny.com/ or in the mobile app.

API call specification:

• Request type – POST
• Endpoint URL – /oauth/token
• Request body – client_id=3rdparty&client_secret=ws7TQHXp5W6444t4&grant_type=password&username=EMAIL&password=PASSWORD

Example API call using curl:

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

The server responds with a JSON containing the access_token:

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

You can test this step manually from the command line:

Getting a list of your clocks

The next step is to get a list of clocks that are paired to your account. The pairing is done automatically during the process of connecting the clock to the internet. Replace the ACCESS_TOKEN with the access token you received in the previous step.

API call specification:

• Request type – GET
• Endpoint URL – /v1/devices?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Example API call using curl:

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

The JSON response returned by the cloud server:

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

Checking online connection of the clock to the cloud

Now we need to test whether the clock is connected to the cloud and we can “talk” to it.

API call specification:

• Request type – GET
• Endpoint URL – /v1/devices/CLOCK_ID/online?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Example API call using curl:

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

The JSON response returned by the cloud server:

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

Reading the configuration parameters

All the configuration parameters are stored in the clock itself, we can read them by sending API calls according to the specification below. The PARAMETER is to be replaced by the actual parameter name that we want to read from the clock.

API call specification:

• Request type – GET
• Endpoint URL – /v1/devices/CLOCK_ID/PARAMETER?client_id=3rdparty&access_token=ACCESS_TOKEN&client_secret=ws7TQHXp5W6444t4

Example API call to retrieve the value of “transition” parameter using curl:

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

The JSON response returned by the cloud server, the parameter value in this example is “2”.

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

Sending the configuration parameters

All the configuration parameters are stored in the clock itself, to change the particular parameter, we need to do an API call as below. The PARAMETER is to be replaced by the actual parameter name that we want to read from the clock. The VALUE is the actual value we want to set the PARAMETER to.

API call specification:

• Request type – POST
• Endpoint URL – /v1/devices/CLOCK_ID/PARAMETER
• Request body – access_token=ACCESS_TOKEN&arg=VALUE&client_secret=ws7TQHXp5W6444t4&client_id=3rdparty

Example API call using curl – this way we can set parameter “transition” to value 3.

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

The JSON response returned by the cloud server:

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

Configuration parameters

Parameter	Zen	NixieMachineII	NixieMachineIII	NX2	PURI4	PURI6	Parameter keyword	Read/Write
Clock ID	2	3	9	4	6	15
	Permissible values
Time format	12, 24						format	RW
Leading Zero	1, 2						leadingzero	RW
Daylight Saving	1, 2, 3						dst	RW
Time Zone							timezone	RW
Date Display	1, 2, 3, 4, 5						datedisplay	RW
Digits Transition	1, 2, 3, 4						transition	RW
Cathode Cleaning Interval	1, 10, 30						slotmachineperiod	RW
System LED mode	1, 2, 3						photonled	RW
Underlight Mode	1,2	–	–	–	–	–	underlightmode	RW
Underlight Mode	1, 2, 4, 6	–	–	–	–	–	underlightsegments	RW
Underlight Color	1 – 2^32	–	–	–	–	–	underlightsolidcolor	RW
Brightness in day mode	1, 6, 71, 126, 201, 256						brightnessday	RW
Brightness in night mode	1, 6, 71, 126, 201, 256						brightnessnight	RW
Schedule							nmstr	W
Colon Mode	1, 2, 3	–	–	–	1, 2, 3	1, 2, 3	colonmode	RW
Power Light	–	1, 2	1, 2	–	–	–	powerlight	RW
Connectivity Mode	1, 2						connectivitymode	RW
Time	1, 2						time	RW
Custom data	XXXXXXXX						customdata	W
Custom data timeout	0-255						customdatatimeout	RW
Start countdown	1-359999						startcountdown	W
Switch to time mode	1						switchtotimemode	W
Slotmachine mode	1,2						slotmachinemode	RW
Restart the clock	1						reset	W
Homekit reset	1						homekitreset	W
RTC calibration							rtccalibration	RW
System firwmare							systemfirmware	R
Firmware version							firmware	R
Wifi signal strength							rssi	R
Watchdog restarts							watchdogevents	R
Clock ID							productid	R
Serial number of the clock	0-99999						serialnumber	RW
Homekit connections							hkconnectionsnumber	R
Largest free memory block							largestfreeblockheap	R
Free memory							freememory	R
Currently displayed value							currentdisplayedvalue	R
Last NTP sync difference							lastntpsyncmillis	R
OTA updates							otaenabled	R
MAC Address							macaddr	R

Explanation of the individual configuration parameters

Time Format

12 = 12h format, 24 = 24h format

Leading Zero

1 = OFF, 2 = ON

Daylight Saving

1 = OFF, 2 = ON, 3 = Auto

Time Zone

Name	Value
(UTC-12:00) International Date Line West	0
(UTC-11:00) Coordinated Universal Time -11	1
(UTC-10:00) Hawaii	2
(UTC-09:00) Alaska	3
(UTC-08:00) Pacific Time (US and Canada)	4
(UTC-08:00) Baja California	5
(UTC-07:00) Mountain Time (US and Canada)	6
(UTC-07:00) Chihuahua, La Paz, Mazatlan	7
(UTC-07:00) Arizona	8
(UTC-06:00) Saskatchewan	9
(UTC-06:00) Central America	10
(UTC-06:00) Central Time (US and Canada)	11
(UTC-06:00) Guadalajara, Mexico City, Monterrey	12
(UTC-05:00) Eastern Time (US and Canada)	13
(UTC-05:00) Bogota, Lima, Quito	14
(UTC-05:00) Indiana (East)	15
(UTC-04:30) Caracas	16
(UTC-04:00) Atlantic Time (Canada)	17
(UTC-04:00) Cuiaba	18
(UTC-04:00) Santiago	19
(UTC-04:00) Georgetown, La Paz, Manaus, San Juan	20
(UTC-04:00) Asuncion	21
(UTC-03:30) Newfoundland	22
(UTC-03:00) Brasilia	23
(UTC-03:00) Greenland	24
(UTC-03:00) Montevideo	25
(UTC-03:00) Cayenne, Fortaleza	26
(UTC-03:00) Buenos Aires	27
(UTC-02:00) Mid-Atlantic	28
(UTC-02:00) Coordinated Universal Time -02	29
(UTC-01:00) Azores	30
(UTC-01:00) Cabo Verde Is.	31
(UTC) Dublin, Edinburgh, Lisbon, London	32
(UTC) Monrovia, Reykjavik	33
(UTC) Casablanca	34
(UTC) Coordinated Universal Time	35
(UTC+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague	36
(UTC+01:00) Sarajevo, Skopje, Warsaw, Zagreb	37
(UTC+01:00) Brussels, Copenhagen, Madrid, Paris	38
(UTC+01:00) West Central Africa	39
(UTC+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna	40
(UTC+01:00) Windhoek	41
(UTC+02:00) Minsk	42
(UTC+02:00) Cairo	43
(UTC+02:00) Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius	44
(UTC+02:00) Athens, Bucharest	45
(UTC+02:00) Jerusalem	46
(UTC+02:00) Amman	47
(UTC+02:00) Beirut	48
(UTC+02:00) Harare, Pretoria	49
(UTC+02:00) Damascus	50
(UTC+02:00) Istanbul	51
(UTC+03:00) Kuwait, Riyadh	52
(UTC+03:00) Baghdad	53
(UTC+03:00) Nairobi	54
(UTC+03:00) Kaliningrad	55
(UTC+03:00) Moscow, St. Petersburg, Volgograd	56
(UTC+03:30) Tehran	57
(UTC+04:00) Abu Dhabi, Muscat	58
(UTC+04:00) Baku	59
(UTC+04:00) Yerevan	60
(UTC+04:00) Tbilisi	61
(UTC+04:00) Port Louis	62
(UTC+04:30) Kabul	63
(UTC+05:00) Tashkent	64
(UTC+05:00) Islamabad, Karachi	65
(UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi	66
(UTC+05:30) Sri Jayawardenepura	67
(UTC+05:45) Kathmandu	68
(UTC+06:00) Ekaterinburg	69
(UTC+06:00) Astana	70
(UTC+06:00) Dhaka	71
(UTC+06:30) Yangon (Rangoon)	72
(UTC+07:00) Novosibirsk	73
(UTC+07:00) Bangkok, Hanoi, Jakarta	74
(UTC+08:00) Krasnoyarsk	75
(UTC+08:00) Beijing, Chongqing, Hong Kong, Urumqi	76
(UTC+08:00) Kuala Lumpur, Singapore	77
(UTC+08:00) Taipei	78
(UTC+08:00) Perth	79
(UTC+08:00) Ulaanbaatar	80
(UTC+09:00) Irkutsk	81
(UTC+09:00) Seoul	82
(UTC+09:00) Osaka, Sapporo, Tokyo	83
(UTC+09:30) Darwin	84
(UTC+09:30) Adelaide	85
(UTC+10:00) Yakutsk	86
(UTC+10:00) Canberra, Melbourne, Sydney	87
(UTC+10:00) Brisbane	88
(UTC+10:00) Hobart	89
(UTC+10:00) Guam, Port Moresby	90
(UTC+11:00) Vladivostok	91
(UTC+11:00) Solomon Is., New Caledonia	92
(UTC+12:00) Magadan	93
(UTC+12:00) Fiji	94
(UTC+12:00) Auckland, Wellington	95
(UTC+12:00) Coordinated Universal Time +12	96
(UTC+13:00) Nuku’alofa	97
(UTC-11:00) Samoa	98

Date Display

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

Digits Transition

1 = Normal, 2 = Crossfading, 3 = Slot Machine, 4 = Slot-Crossfading

System LED mode

1 = Always On, 2 = Off when online, 3 = Always Off

Cathode Cleaning Interval

1 = Every minute, 10 = Every 10 minutes, 30 = Every 30 minutes

Underlight Mode

1 = OFF, 2 = Solid Color

Underlight Segments

1 = All Off, 2 = Bottom Only, 4 = Top Only, 6 = All On

Underlight Color

32 bit value, 0b00000000BBBBBBBBGGGGGGGGRRRRRRRR

Colon Mode

1 = OFF, 2 = Solid, 3 = Fading

Power Light

1 = ON, 2 = OFF

Connectivity Mode

1 = Online, 2 = Offline

Time

Unix Timestamp (UTC+0) in seconds, works in offline mode only (it is overwritten in online mode).

Custom data

8 characters representing 6 tubes and 2 colon tubes (two tubes and one colon are not displayed on Puri-4).

Special characters:

• “_” blanking the position (works both for colon and numerical tube)
• “:” both dots activated, for colon tube only
• “.” lower dot activated, for colon tube only
• “;” upper dot activated, for colon tube only

String examples:

• “12_34_56” displays 123456 on nixie tubes while blanking colon tubes
• “_____.25” displays 25 on the right pair of tubes and a lower dot on the right colon tube
• “;15;” blanks all tubes except the middle pair, both colons display upper dot

Custom data timeout

This parameter tells the clock after what time it must switch back to time mode (displaying time) after custom data were received. The actual period is calculated as a square of the value you send to give a better resolution. If you send the value “5”, the period of timeout will be 25 seconds (5 × 5 = 25).

Start countdown

This call starts a countdown timer, the parameter is the desired period in seconds. If you want to start a countdown timer for 3 minutes, call it with parameter 180 (3*60).

Switch to time mode

Call this parameter to switch the clock to time mode (e.g. from custom data mode, from slot machine mode, or countdown timer).

Slotmachine mode

1 = activate, 2 = deactivate

Homekit reset

Call this parameter to delete the current Homekit pairing and reset it to default.

RTC calibration

Permissible values (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

Serial number of the clock

The serial number is set at our side once the clock is manufactured, so please don’t change it.

Homekit connections

The number of clients (iPhones, iPads) that are currently connected to the clock via Homekit.

Largest free memory block

The biggest free allocable memory block on the memory heap in bytes.

Free memory

Total free memory on the heap in bytes.

Currently displayed value

Currently displayed number on the tube display, colons are not taken into account.

Last NTP sync difference

How many milliseconds was the system time adjusted at the last NTP synchronization?

OTA updates

Are the Over The Air updates enabled? 1 = enabled, 0 = disabled

MAC address

Returns MAC address of the device

Copyright © 2024 Daliborfarny.com