Difference between revisions of "Alpha Clock Serial v2"

Revision as of 21:49, 12 October 2012

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 FTDI TTL-232R or the Adafruit 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 2.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 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 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 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 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 '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. 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. 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.

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, " ".

Ax: Daisy-Chained Ascii Display

The Ax function 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_")

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 Alpha Clock Five, to its main serial port.

When Alpha Clock Five receives an Ax 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 Ax 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.

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 at processing.org.

AlphaClock_SetText

Download this file here (2 kB .pde file). --NOT YET UPDATED FOR v2.

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

• 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)