In a more advanced mode, PiClock is able to connect to a server (or multiple redundant servers) which can deliver tally and layout information to the Pi.
When configured to work in this fashion PiClock will connect to all configured tally servers simultaneously, over a TCP session to the configured port (default 6254). Once connected the PiClock must authenticate itself to the tally servers.
Whilst multiple tally servers are supported, messages from multiple servers are all acted upon. The easiest redundancy model to adopt is for the tally servers to negotiate between each other which will communicate information to the PiClock.
Once authenticated messages are basically one-directional, from the tally server to PiClock. PiClock is expected to acknowledge all commands (with an ACK), or pings (with a PONG).
The server must transmit something to the client at least once every 5 seconds. If a client hears nothing from a server for 5 seconds it assumes the connection is dead and disconnects and attempts to reconnect.
All messages are UTF-8, terminated with a carriage return character (13 decimal). They take the format:
CMD:ARG1:ARG2:ARG3:...ARGn<CR>
The number of arguments (if any) vary depending on the command, the PiClock will ignore extra arguments added to the end of the command which it doesn't expect (for example from newer versions of the protocol).
The PiClock display is made up of 1 or more regions, each region can contain all the information normally displayed on the PiClock. By default the PiClock will have 1 region, and lay things out appropriately in that. Within a given region, PiClock will do its best to lay out your requested clocks and tallies. If the region is portrait (taller than wide), then it will display any analogue clock at the top, followed by any date and/or digital time, and any tally boxes. Regions are configured identically, Region 0 will always contain connection information (MAC address, mapped profile, connection/NTP status) along its bottom line).
Each command can take 0 or more arguments, as discussed above extra arguments will be ignore by the PiClock. Arguments can be a number of formats:
| Type | Format |
|---|---|
| string | Inline UTF-8 formatted string |
| int | Decimal representation of integer in UTF-8 (or ASCII) string, precision will vary depending on command |
| bool | An int (as above) holding either 0 (for false) or 1 (for true) |
| float | Decimal representation of a floating-point value in UTF-8 (or ASCII) string, always parsed in double precision |
| colour | Hexadecimal representation of a 32-bit RGB in UTF-8/ASCII (basically the same format as HTML colours without the preceding #) |
| b64 | Base64 Encoded binary data (currently only used to send images) |
Commands may refer to the whole display, or to configure a region of the display
Upon first receiving a connection from a Pi, a tally server must respond with an authentication request.
-
CRYPT
The CRYPT command (from server to client) should take the format:
CRYPT:random_string<CR>where random_string is a random string of characters generated by the server.
The client should reply to this with an AUTH request.
-
AUTH
The AUTH command (from client to server) should take the format:
AUTH:sha512_digest:mac_addr<CR>Where sha512_digest is a SHA512 Digest performed on the UTF-8 string formed from a concatenation of random_string (received from the CRYPT request), and a shared secret (ie password) known by both the client and server. mac_addr is the MAC address of the Pi hosting PiClock (in hex, with no colons), for use by the server for mapping the client to a particular profile.
If the authentication is not succesful the server should disconnect the client, otherwise it should progress to sending normal or ping commands.
-
PING
This should take the format:
PING<CR>it is only sent from Tally Server to Client (PiClock), and the client must respond with a PONG
-
PONG
This should take the format:
PONG<CR>it is only sent from Client (PiClock) to Tally Server. The client must send this if and only if a PING is received from the server.
-
ACK
This should be sent by the client in response to any (non ping/authentication) server command it understands:
ACK<CR> -
NACK
This should be sent by the client in response to any (non ping/authentication) server command it does not understand:
NACK<CR>
Global Commands refer to the whole display area, not individual regions.
-
SETGLOBAL
SETGLOBAL:landscape:screensaver<CR>Sets global flags, defaults if no command is ever sent:
Argument Type Default Description landscape bool true Whether to make the output landscape (true, wider than tall) or portrait (false, taller than wide) screensaver bool true If true, the width and height are shrunk by 5% of the display height, and this shrunken output is slowly moved around the total display area (in an attempt to prevent screen burn). -
SETPROFILE
SETPROFILE:name<CR>Tell the PiClock the name of its current profile (for display next to MAC address at the bottom of the display).
Argument Type Description name string Name to display (cannot contain colon character) -
SETREGIONCOUNT
SETREGIONCOUNT:count<CR>Sets the number of regions that should be handled/displayed
Argument Type Default Description count int 1 Number of regions
All region commands can be prefixed by a number (an int, in decimal format as a UTF-8 string), specifying the (zero-indexed) region number to which the command refers. If no region number is specified, then the command is interpreted as SETREGIONCOUNT:1 followed by the command itself in Region 0.
-
SETSIZE
SETSIZE:rows:cols<CR>Sets the number of rows of indication tallies to display, and the default number of columns of tallies on each of these rows
Argument Type Default Description rows int 0 Number of rows of tally indicators to display cols int 0 Default number of columns on each row, this can be overridden for a particular row with the SETROW command. -
SETROW
SETROW:row:cols<CR>Overrides the number of columns on a particular row
Argument Type Description row int Row number (counting from 0) to set column count on cols int Column count for this row -
SETTALLY
SETTALLY:row:col:fg_colour:bg_colour:text<CR>Set the tally state of a given indicator box. This will destroy any countdown information for the given indicator box, and revert it to a simple text display.
NB text can contain the colon ':' character, and so cannot be followed by any further arguments.
Argument Type Description row int Row number (counting from 0) of indicator box col int Column number (counting from 0) of indicator box fg_colour colour Foreground (text) colour bg_colour colour Background colour text string Text to display on indicator box, this text can contain the colon ':' character, meaning no further arguments can follow -
SETLABEL
SETLABEL:row:col:text<CR>Sets the label text to appear above a tally state. NB this has no affect on an indicator box which is in countdown mode (configured by SETCOUNTDOWN), only tally mode (configured by SETTALLY)
Argument Type Description row int Row number (counting from 0) of indicator box col int Column number (counting from 0) of indicator box text string Text to display on indicator box, this text can contain the colon ':' character, meaning no further arguments can follow -
SETCOUNTDOWN
SETCOUNTDOWN:row:col:fg_colour:bg_colour:target_secs:target_usecs:flash:label<CR>Sets the given indicator box to show a countdown to the time represented by target_secs and target_usecs
NB label can contain the colon ':' character, and so cannot be followed by any further arguments.
Argument Type Description row int Row number (counting from 0) of indicator box col int Column number (counting from 0) of indicator box fg_colour colour Foreground (text) colour bg_colour colour Background colour target_secs int64 Target time (at which countdown will become 0) in number of seconds since 01/01/1970 00:00:00 UTC target_usecs int Any extra fractional seconds to add onto target_secs in microseconds flash int Flash limit. If this field is empty, then no flash limit is specified, otherwise when flash seconds are left before the target time, the indicator will start to flash (by exchanging foreground and background colours) with a frequency of 1Hz label string Text to display inside inidcator box, above the countdown. This text can contain the colon ':' character, so cannot be followed by any extra arguments -
SETLAYOUT
SETLAYOUT:analogue_clock:analogue_clock_local:digital_clock_utc:digital_clock_local:date:date_local:blank:numbers_present:numbers_outside<CR>Argument Type Default Description analogue_clock bool true Display an analogue clock analogue_clock_local bool true Make any analogue clock be displayed in the local timezone digital_clock_utc bool false Display a digital clock showing the time in UTC digital_clock_local bool true Display a digital clock showing the time in the local timezone date bool true Display the date date_local bool true Displayed date is in the local timezone blank string Unused legacy field, left for compatibility with old PiClock devices, can contain anything, will be ignored. numbers_present bool true Show numbers on any analogue clock numbers_outside bool true Show numbers outside any analogue clock (otherwise inside) -
SETLOCATION
SETLOCATION:x:y:width:height<CR>Sets the location and size of this region. All values are a proportion of the display width/height, between 0 and 1. Co-ordinate 0,0 is in the bottom left corner and 1,1 is in the top right.
Argument Type Default Description x float 0 Co-ordinate of left edge of display area y float 0 Co-ordinate of bottom edge of display area width float 1 Width of display area of the region height float 1 Height of display area of the region -
SETFONTSIZEZONES
SETFONTSIZEZONES:row0:row1:...<CR>Sets the font size zone names for each tally indicator on each row.
By default PiClock will find the maximum font size that can still display the text on all indicators in each region, and use that font size for all indicators in each region.
By setting zone names against individual cells, you can create different groups of indicators which are sized separately. All indicators within a given zone are sized as above, finding the max font for those indicators.
Zone names beginning with the letter 'G' are global to all regions, others are local to each region, so a zone with the same name in another region will be calculated separately.
Each row description has a comma-separated list of zone names for the indicators on that row. Any unspecified indicators, or unspecified rows are left in the default (local to a zone) category.
To leave a given indicator in the default category, simply leave its zone empty.
Argument Type Default Description row0 list Comma-separated list of zone names for row 0 row1 list Comma-separated list of zone names for row 1 -
STOREIMAGE
STOREIMAGE:name:image<CR>Stores (or updates) an image to be displayed. Whenever a tally indicator has text that equals 'name' then the image in 'image' is drawn instead of text (scaled to fit the tally box).
When images are scaled to a given size they are first scaled using a quick algorithm which may look rather aliased, they are then scheduled to be re-scaled slowly in the background. Once an image has been scaled to a particular size, PiClock will cache the scaled image until that image is replaced, CLEARIMAGES is sent, or the program quits.
Argument Type Default Description name string Magic string which will be replaced by image image b64 Base64 encoded binary data of an image file. JPEG and PNG formatted data have been tested, but any format supported by ImageMagick should work. -
CLEARIMAGES
CLEARIMAGESClears any and all stored images.
It's possible to do basic testing of the tally protocol with netcat, however by default any tally info will disappear after five seconds of comms loss (such as not sending PINGs):
nc -k -l 6254 -C