Editing Alpha Clock Serial v2

[[Alpha_Clock_Firmware_v2|Firmware v. 2.0]] 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, as well as sending serial data to multiple Alpha Clock Five units by "daisy chaining" their serial ports. 


== Interfacing to Alpha Clock Five ==

Alpha Clock Five has two onboard hardware serial ports.     The main serial port (Arduino PORT0, J2 on the PCB) is normally used for communication with your PC, while the second serial port (Arduino PORT1, J5 on the PCB) is normally used for connecting to another "daisy chained" Alpha Clock Five.    In general, we will refer to the main serial port, J2, as "the serial port" for purposes of communication.    


The serial port on Alpha Clock Five is a "TTL Serial" type that is connected directly to the microcontroller.  To interface with a computer, it is normally used with an FTDI serial interface such as the [http://shop.evilmadscientist.com/productsmenu/partsmenu/130-usbttl FTDI TTL-232R] or the Adafruit [http://shop.evilmadscientist.com/productsmenu/accessories/210 FTDI Friend].     Note that since the interface supports logic-level signals, it cannot be interfaced directly to a traditional RS232 serial port on a computer.    

The interface is normally configured for 19,200 baud, 8N1.

Alpha Clock Five 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.  Alternatively, if you wish to sync the time to your computer and do not have a Chronodot RTC present, you may wish to physically disconnect the interface cable from J2 after syncing the time, so that the clock does not reset when you open a subsequent connection.


== Daisy-Chained Serial ==

Alpha Clock Five features a second hardware serial port, located at location J5 on the circuit board.   For daisy chaining, you can use a [http://shop.evilmadscientist.com/productsmenu/partsmenu/586 six pin SIL F-F header cable] to connect from J5 directly to the main serial port (J2) on a second Alpha Clock Five unit.    Multiple Alpha Clock Five units can be connected together in this same way, to produce larger-yet alphanumeric displays.  

In revision B of the circuit board, J5 is located just below the middle chip, U2.   Pin 1, where the "black" side of the cable goes is indicated by an arrow.   In revision C of the circuit board,  J5 is located below U3, on the lower right side of the circuit board.    Pin 1, where the "black" side of the cable goes is indicated by an arrow.  Pin 1 is also indicated as the ''square'' pin of header J5.    If your kit did not come with a header at location J5, you will need to add one at that location in order to have a place to attach the cable.


Two commands, A''x'' and B''x'', where ''x'' is a single-character number (either binary or ASCII), can be used to send data to one or more Alpha Clock Five units that are connected together through their serial interfaces.   If ''x'' is equal to zero, the A0 or B0 command will be evaluated by the first Alpha Clock Five unit to receive the command.  If ''x'' is greater than zero (e.g., "A3"), an Alpha Clock Five unit that receives the command on its main serial port will decrement the ''x'' value (e.g., from "A3" to A2"), and issue the modified command through its second serial port, without otherwise processing the command.   For example, suppose that two Alpha Clock Five units are connected together via their serial ports. Then, the command A1, followed by a text/decimal string, will be received by the first Alpha Clock Five and then sent to the next as an A0 (text display) command, so that it will display that text/decimal string only on the second unit.



== Supported commands ==

Firmware version 2.0 supports several serial commands: Set time (ST), Ascii display (A0/A''x''), Set Parameter (B0/B''x'') and Mode Time (MT).

Each command consists of exactly 13 bytes:  A single header byte (0xFF), followed by a two-letter command code and then 10 additional 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.


The Alpha Clock Five library (v. 2.0 and above) includes a set of Processing sketches, including an example program (AlphaClock_SetTime) that can sync the time on your Alpha Clock Five to that on your PC.  (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].)



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

The A0 function is used to display data, for example alphanumeric characters, on the front LEDs of Alpha Clock Five.  It can also be used to blank the display.   


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


The 5 ASCII characters to display should be in the range " " (space, ASCII 32) to "e" (lower-case "e", ASCII 101).    There are defined characters in the default font table for A-Z (upper case), 0-9, space, and symbols such as $, %, &, (, ), [, ], =, -, +, /, |, \, _, ., ", and ^.  ( Please [http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters see here] or [http://web.cs.mun.ca/~michael/c/ascii-table.html here] for a more complete ASCII chart in the appropriate range. )   The last five characters in the font table, "a" though "e", are extra character "slots" that are  available to be overwritten with custom characters.  

The shape of any character in the font table can be edited with a B0 (Set Parameters) command.  Some symbols, such as a comma, exclamation point, or a semicolon, ''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 '1' will light the lower DP, a value '2' will light the upper DP, and a value '3' will light both DPs. Any other character will not cause either of the LEDs to be lit.   Any other character will not cause either of the LEDs to be lit.  The decimal string is ''strictly additive'', in that it can only be used to turn on decimal points that are not already lit. If the ASCII string contains characters that light either DP (for example the period, '.'), the DP string cannot be used to turn off the decimal point..    

Note that the decimal point protocol has been changed from that in firmware v1, for which the display characters were 'U', 'L', and 'B' for upper, lower, or both decimal points. 

  
To blank the display, you can send an string consisting of five spaces ("     ") for both the ASCII and DP strings.


The Alpha Clock Five library (v. 2.0 and above) includes a set of Processing sketches, including an example program (AlphaClockv2_SendText) that can can display text on the Alpha Clock Five LEDs.  (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].)




==== A''x'': Daisy-Chained Ascii Display  ====

The A''x'' function is a "daisy-chained" version of the A0 command.  It is used to display alphanumeric characters on the front LEDs of more than one Alpha Clock Five, connected through their serial interfaces.   

The full command consists of 13 bytes, as follows:
* The header byte, 0xFF
* The command letter 'A', a single ASCII character
* The distance value ''x'', a single byte.  This may be an ASCII value of '0' - '9' or a binary value from 0 to 47. This value indicates how many daisy-chained Alpha Clock Five units should "relay" the command before displaying the characters.
* 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., "_123_")


When Alpha Clock Five receives an A''x'' command on its main serial port (where ''x'' is not equal to zero), it relays that command out through its second serial port, decrementing it from A''x'' to A''(x-1)''.  For example, suppose that two Alpha Clock Five units are connected together via their serial ports. Then, the command A1, followed by a text/decimal string, will be received by the first Alpha Clock Five and then sent to the next as an A0 command, so that it will display that text/decimal string on the second unit.


The Alpha Clock Five library (v. 2.0 and above) includes a set of Processing sketches, including several example programs that can can display text across multiple daisy-chained Alpha Clock Five units through the serial interface.  (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].)

The relevant example sketches are as follows:
* AlphaClockv2_SendTextDaisy: Demonstrates sending text to the second of two Alpha Clock Five units connected together.
* AlphaClockv2_TextStringDaisy2:  Writes a single text string across two Alpha Clock Five units.
* AlphaClockv2_Test4Daisy: Demonstrates sending text to up to four Alpha Clock Five units.
* AlphaClockv2_ScrollTextDaisy2:  Scrolls a text string across multiple Alpha Clock Five units.



==== B0: Set Parameters ====

The B0 function is used to adjust certain parameters on Alpha Clock Five over the remote interface.  This command can be used to set the brightness of  Alpha Clock Five, the font style of numbers, and to edit individual font characters.  Changes made to settings over the remote interface are impermanent, and will be set forgotten the next time that Alpha Clock Five is reset.


The full command consists of 13 bytes, as follows:
* The header byte, 0xFF
* The command B0
* One more character, either 0, 1, or 2, which indicates which parameter to adjust.
* Nine more characters of data, which depend on the parameter being adjusted.


'''B00''':  Set brightness

The display brightness is specified as a two-character ASCII string indicating the brightness on a scale of 0 to 11.   The string must be exactly two characters long, and leading-zero-filled.  For example, "01" and "10" are acceptable, but "1" and " 1" are not.    The remainder of the data string consists of 7 additional bytes, which will be ignored.

Example:  (0xFF) followed by "B0011*******" will set the brightness to maximum.


'''B01''': Set number character set

Alpha Clock Five features 10 built in number font styles, that you can choose between.   The character set chosen is indicated by a single ASCII character in the range '0' to '9' that follows the "B01".  The remainder of the 10-byte data string consists of 8 additional bytes, which will be ignored.

Example:  (0xFF) followed by "B014********" will select number font style number 4.


'''B02''': Edit font character

The shape of any character in the font table can be redefined by using the B02 command.   Following the "B02" are nine bytes of data that specify the ASCII character to be redefined, and the shape of that character.  The font shape is specified by three sequential values, the "A", "B", and "C" values that indicate which LEDs will be lit when that character is displayed.  Depending on those three values, a font character may include alphanumeric segments, decimal points (upper and/or lower), or both.   This command can be used to put arbitrarily shaped characters or data on the Alpha Clock Five display, for example by overwriting the 'a' through 'e' characters, and then displaying those characters with the A0 command.


In detail, the full B02 command is given as follows:

* The header byte, 0xFF
* The command "B02"
* The character that will be edited, indicated by a single ASCII character in the range from " " (space, ASCII 32) to "e" (lower-case "e", ASCII 101).  Example: 'Q'
* The "A" value, which is a value in the range 0 to 255, formatted as exactly three ASCII characters, with leading zero fill.  Example 1: "003". Example 2: "015". Example 3: "251".
* The "B" value, which is a value in the range 0 and 3, formatted as exactly one ASCII characters.  Example 1: "0". Example 2: "2".
* The "C" value, which is a value in the range 0 to 255, formatted as exactly three ASCII characters, with leading zero fill.  Example 1: "003". Example 2: "015". Example 3: "251".
* One extra byte of data, which will be ignored.
 
Example:  (0xFF) followed by "B02Q0160204*" will replace the font definition for the letter 'Q' with the font character defined by A = 16, B = 0, C = 204 (which happens to draw a "K".)  


The individual "A", "B", and "C" values may be calculated by summing the values shown in this chart, for each LED segment or decimal that should be lit:


http://evilmadscience.s3.amazonaws.com/wiki/alphaclock/alphatemplate3.png


A java applet for interactively calculating these values is also [http://wiki.evilmadscience.com/extras/AlphaCharGen/ available here].



The Alpha Clock Five library (v. 2.0 and above) includes a set of Processing sketches, including two example programs that execute the B0 commands.  (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].)

The relevant example sketches are as follows:
* AlphaClockv2_BrightnessNumSet:  Change Alpha Clock Five brightness and number character set. 
* AlphaClockv2_CustomChars: Demonstrates editing and displaying custom characters on Alpha Clock Five through the serial interface.



==== B''x'': Set Parameters (Daisy-Chained)   ====

The B''x'' function is a "daisy-chained" version of the B0 command.  It is used to adjust certain parameters on more than one Alpha Clock Five, connected through their serial interfaces.   

The full command consists of 13 bytes, as follows: 
* The header byte, 0xFF 
* The command letter 'B', a single ASCII character
* The distance value ''x'', a single byte.  This may be an ASCII value of '0' - '9' or a binary value from 0 to 47. This value indicates how many daisy-chained Alpha Clock Five units should "relay" the command before executing the "B0" command.
* One more character, either 0, 1, or 2, which indicates which parameter to adjust.
* Nine more characters of data, which depend on the parameter being adjusted.  See the description of the B0 command above for the specific data format.



When Alpha Clock Five receives an B''x'' command on its main serial port (where ''x'' is not equal to zero), it relays that command out through its second serial port, decrementing it from B''x'' to B''(x-1)''.  For example, suppose that two Alpha Clock Five units are connected together via their serial ports. Then, the command B1, followed by a data string, will be received by the first Alpha Clock Five and then sent to the next as an B0 command, so that it will execute the B0 command on the second unit.



The Alpha Clock Five library (v. 2.0 and above) includes a set of Processing sketches, including several example programs that can can execute B''x'' commands across multiple daisy-chained Alpha Clock Five units through the serial interface.  (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].)


The relevant example sketches are as follows:
* AlphaClockv2_BrightnessNumSetDaisy: Change Alpha Clock Five brightness and number character set on two Alpha Clock Five units connected together.
* AlphaClockv2_CustomCharsDaisy:  Demonstrates editing and displaying custom characters on multiple Alpha Clock Five units through the serial interface.



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

The MT function is used to resume normal display mode-- typically 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).
 
 


== 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:

* SA   (May be used for Set Alarm time 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)
@@ Line 12: / Line 12: @@
 Alpha Clock Five 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.  Alternatively, if you wish to sync the time to your computer and do not have a Chronodot RTC present, you may wish to physically disconnect the interface cable from J2 after syncing the time, so that the clock does not reset when you open a subsequent connection.
-== Setting time alone ==
-If you wish to set the time on your Alpha Clock Five via computer -- and not do any additional interfacing -- there is a Processing sketch called SetArduinoClock, [https://bcdn.evilmadscientist.com/source/SetArduinoClock.zip available here], for just that purpose. Run this sketch with [http://processing.org/ Processing].