Editing Alpha Clock Serial

The standard [[Alpha Clock Firmware]] for [[Alpha Clock Five]] has a built in serial interface protocol that supports several basic functions, including time sync and displaying text on the alphanumeric LED display.


== Interfacing to Alpha Clock Five ==

The serial interface is a "TTL Serial" type, connected directly to the microcontroller, and supports logic-level signals only.   The interface is normally configured for 19,200 baud, 8N1.

For most applications a USB-TTL interface such as the [http://evilmadscience.com/productsmenu/partsmenu/130-usbttl FTDI TTL-232R] or the Adafruit [http://evilmadscience.com/productsmenu/accessories/210 FTDI Friend] is an excellent choice.
The FTDI interface connects to location J2 on the circuit board.

Note that the clock usually resets when the serial connection is opened; this is a side-effect of the auto-reset circuitry used for reprogramming the clock using the bootloader.  If this is problematic and you expect to never update the firmware, you can disable auto-reset by removing capacitor C10 from the circuit board or by clipping the lead at pin RTS* on J2.


== Supported commands ==

Firmware version 1.0 supports three serial commands: Set time, Ascii display, and Mode Time (which turns off Ascii display).  

Each command consists of a header byte (0xFF), followed by a two-letter command and then 10 bytes of data.


==== ST: Set Time ====

The set time function is used to set the time displayed on Alpha Clock Five.


The full command consists of 13 bytes, as follows:
* The header byte, 0xFF
* The command ST
* A 10-digit string giving the number of seconds since Jan 1 1970


The number of seconds since Jan 1 1970 is an implementation of a [http://en.wikipedia.org/wiki/Unix_time unix time] string.  
As an example, the 10-digit string 1324758327 represents the time 20:25:27, Saturday December 24.


Please see the Sample Programs section below for an example program that can set the time.


==== A0: Ascii Display ====

The A0 function is used to display alphanumeric characters on the front LEDs of Alpha Clock Five.


The full command consists of 13 bytes, as follows:
* The header byte, 0xFF
* The command A0
* A 5-character string consisting of the characters to display  (e.g., "HELLO")
* A 5-character string indicating which (if any) decimal points should be lit (e.g., "_ULB_")

The 5 characters to display should be in the range " " (space, ASCII 32) to "`" (grave accent, ASCII 96).  This range includes A-Z (upper case), 0-9, and symbols including $, %, &, (, ), [, ], =, -, +, /, |, \, _, ., ", and ^.  ( Please [http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters see here] for a more complete ASCII chart in the appropriate range. )   Some symbols, such as the exclamation point or a colon, ''simply do not'' display well on an alphanumeric display.   In certain cases, the decimal points can be used to help make good looking characters, as is the case with the colon, aptly displayed by two decimal points (upper and lower) between two characters.   

The decimal point string consists of 5 characters, and describes which decimal points (if any) should be lit for each of the five alphanumeric LED displays.  For each character in this string, a value 'L' will light the lower DP, a value 'U' will light the upper DP, and a value 'B' will light both DPs.   Any other character will not cause either of the LEDs to be lit.  Note that the decimal string is ''strictly additive''; if the string contains characters that light either DP (for example the period, '.'), the DP string cannot be used to turn off that LED. 


Please see the Sample Programs section below for an example program that can display text on the Alpha Clock Five LEDs.

 
Note that the set of characters available (ASCII 32-96) is defined in the firmware.  If you need to display characters not in that set, or would like to change the shape of the displayed characters, that can be made possible by editing and uploading a new version of the firmware. 


To blank the display, you can send an string consisting of spaces, "     ".


==== MT: Mode Time ====

The MT function is used to resume normal display mode-- showing the time --after command A0 has been issued.


The full command consists of 13 bytes, as follows:
* The header byte, 0xFF
* The command MT
* A 10-character string (the contents of this string will be ignored).


Please see the Sample Programs section below for an example program that displays characters with A0, and then uses MT to display the time again.


== Sample programs ==

Sample applications to communicate with Alpha Clock Five are provided as .pde files, for use with the Processing development environment.  Processing is a free, cross-platform programming environment, and you can download your copy [http://processing.org/ at processing.org].


==== AlphaClock_SetText ====

Download this file [http://evilmadscientist.s3.amazonaws.com/source/alphafive/AlphaClock_SetText.pde here] (2 kB .pde file).  

When you run the application, it presents a window.  Click your mouse in the window to alternately display a text string ("ALPHA", plus some added decimal points) and to resume clock display.  This demonstrates the use of the A0 and MT serial functions.

Note that you may need to edit the file to select the correct serial port, defined by the "portIndex" variable, in order to select the serial port where your clock is attached. 


==== AlphaClock_SetTime ====

Download this file [http://evilmadscientist.s3.amazonaws.com/source/alphafive/AlphaClock_SetTime.pde here] (2 kB .pde file).  

When you run the application, it presents a window.  Click your mouse in the window to set the time on the clock to your present computer system time.  This demonstrates the use of the ST function, and also provides an accurate way to set the display time.

Note that you may need to edit the file to select the correct serial port, defined by the "portIndex" variable, in order to select the serial port where your clock is attached.





== Additional Reserved Namespaces ==

The listed function names are reserved for use in future firmware.   If you extend the firmware with additional serial command functions, it is strongly advised that you do not use the following function names:

* A*   (A, followed by any character)
* B*   (B, followed by any character) 
* SA   (May be used for Set Alarm time in future firmware)
* SB   (May be used for Set Brightness in future firmware)   
* M*   Where * is in the range 2-9. (May be used for mode setting in future firmware)
* TP   (May be used for producing sounds in future firmware)