# Fastclock Protocol

## Introduction / General Structure
The fastclock protocol is a text message containing one to many lines of UTF-8 encoded text, each separated by an "end of line".
Following rules apply:

 * End of line: Might be \r (CR, 0x08), \n (NL, 0x0A) or a combination of \r and \n in any order.
 * The original definition mentioned a "level 1" protocol, which we do not support anymore.
 * The first line of a message may contain an arbitrary text or content. This has been used previously for a so called "level 1" protocol. This line is ignored and thus may contain some description, naming or even the level 1 protocol, if someone still wants to use it. Nevertheless, for our use cases, we want to have more detailed content and thus do not use this protocol type anymore.
 * The next lines upto the end of the message contain "key=value" pairs, where the keys must be one of:
version, name, text, clock, active, speed, weekday, ip-port, ip-address, clocktype
 * The order of the keys is not predefined, thus the server may decide a preferred order.

## Protocol element keys
The details of each key are:

| Key       | Meaning | Mandatory / Optional | Allowed Values  |
|-----------|---------|----------------------|-----------------|
| clocktype | Type of clock information transmitted | mandatory | fastclock, realclock |
| name      | Name of clock information transmitted. Multiple clocks may be transmitted by the same server or by multiple server. But each clock must have its own unique name. | mandatory | UTF-8 character string, max. length 20 characters |
| version | Protocol version. Currently, we use version 2. | mandatory | integer, actual version is 2 | 
| text | UTF-8 encoded text message, that might be displayed by clock clients as far as they are able to display additional texts. | mandatory, is empty, if no text is to be displayed | UTF-8 encoded text messages without line breaks; maximum length = 255 characters | 
| clock | The current time of the clock. | mandatory | Text string: H:M:S representing hours, minutes and seconds; may use leading zeroes, but does not need to. Thus "12:3:5" is valid as well as "12:03:05" | 
| active | Set to "yes", if the clock is running, to "no", if the clock is stopped. | mandatory | string "yes" or "no" without double quotes | 
| speed | The given clock speed as a floating number. This is the factor, the fastclock is faster than real time. A Value of "4.5" means a clock speed of "1:4.5" for "real time : fastclock" | mandatory | Float value with "." as a decimal point | 
| weekday | Day of week, where 0=no day of week is given, 1=Monday to 7=Sunday | optional | integer value 0-7 |
| ip-address | IP-Address of clock server; needs only to be set, if a clock server control interface exists | optional | String containg ip-Address like 192.168.0.55 or a hostname, that can be resolved by DNS |
| ip-port | Port to be used to control the clock server; needs only to be set, if a clock server control interface exists | optional | positive integer |
| src-protocol | Server remote control protocol, e.g. http for web application, udp for messages, others ... | optional | String containing the protocol name, max. 20 characters |

## Transmission part of the protocol
To transmit the messages, several possibilities exists. Herewith we suggest that servers may choose, which protocols they want to support. It is in their responsibility to keep the different transmission techniques in sync.

| Tranmission Technique | Restrictions | Available clients |
|-|-|-|
| UDP Multicast | Needs a network infrastructure supporting UDP multicasts. The clients must reside in the same network subnet as the server. This is the preferred transmission technique, as it has a very lean bandwidth usage and almost no dependencies between clients and server. | MRClock app [Android](https://play.google.com/store/apps/details?id=com.MRclock), iPhone (iMRclock), [Telechron für iPhone](https://itunes.apple.com/se/app/telechron-fast-clock-client/id907090499?mt=8), [Cafebahn](https://sourceforge.net/p/cafebahn/wiki/Home/), Windows Client |
| Web-Socket | Clients must be able to access the server "as a web server", but this does not need to be in the same network subnet, as long as a route is defined/available. As nothing like a multicast or broadcast exists based on Web-Sockets, the protocol needs to be extended so that clients can register or request current status. | Android watch client (@uwe.lengler) |
| MQTT | Needs an MQTT server, e.g. Apache Mosquitto. | -- none so far -- |


## TN clock integration
FREMO uses a system called RUT to control TN clocks based on a 2-wire connection. For every minute, an impulse is sent with changing polarity. It uses 12V or 24V depending on the types of clocks used.

A client may support such clocks directly or drive a RUT installation. An example for doing so has been published by Dirk Hilberg in Fremo's Hp1 publication 3/2016, pages 4-5.