Daliborfarny.com

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

Last modified: 14 June 2022