ClockTHREE can also bw used as a general purpose 12×16 LED display. In the video below, ClockTHREE is accepting 64 byte display messages over the serial port and displaying them. In this case the images come from an animated GIF of Mario, but can be anything you want to display that will fit into 64 bytes. The same interface allows ClockTHREE’s time to be set, alarms to be set and cleared, and trigger button presses on the clock.
Here is a more thorough description of the interface.
This document describes the serial interface between ClockTHREE and a computer.
With this interface commands can be sent to:
get/set the absolute time YYYY MM DD hh:mm:ss
get/set time of day alarm hh:mm on/off.
get/set scrollable message
get/set Annual Event ID YYYY MM DD hh:mm:ss MID
get/set display (think web cam interface here)
Baudrate: 57600 // Max rate for arduino
MAX_MSG_LEN = 100 BYTES
A synchronization message can be passed to re-establish communication if things get wonky,
const uint32_t SYNC_MSG = (0xFE)xMAX_MSG_LEN;
Each message will begin with a message id (MID). The message length will
be determined by the MID and the message header (for variable length MIDs)
No message length will be longer than MAX_MSG_LEN bytes.
Message length will include all header bytes.
MID [msg_len] data
Fixed length messages:
MID length description payload format
0x00 X NOT USED NA
0x01 1 request absolute time NA
0x02 5 set absolote time 4 bytes unsigned int (seconds from 00:00 Jan 1, 1970)
0x03 1 request tod alarm NA
0x04 6 set tod alarm 4 bytes unsigned int (seconds from midnight)
0x05 2 request message 1 byte data ID (DID)
0x06 2 delete message 1 byte data ID (DID)
0x07 2 scroll message DID
0x08 X NOT USED NA
0x09 X NOT USED NA
0x0A 1 get display NA
0x0B 65 set display 64 bytes of display data
0x0C 1 trigger MODE Press NA
0x0D 1 trigger INC Press NA
0x0E 1 trigger DEC Press NA
0x0F 1 trigger AUX Press NA
0x10 1 Get SW Version NA
0x11 1 Get SW About NA
0x12 MAX_MSG_LEN Ping MAX_MSG_LEN – data bytes
0x13 MAX_MSG_LEN clear eeprom 0x13 x MAX_MSG_LEN
0x14 1 EEPROM dump NA
0x15 2 Anniversary Alarm Anniversary DID (see below for this data record)
0xEF MAX_MSG_LEN SYNC 99 data bytes (0xEF)(SYNC)
Variable length messages. Payload length is first byte after MID
MID length description payload format
0x70 3 + msg send data 1 byte- message length (payload len + 3), 1 byte (data id) DID, char* msg
0x71 2 + msg error data 1 byte length error message
The sync message 0xEF:
“0xEF” MAX_MSG_LEN times should be followed by a valid DID in the next byte. If ClockTHREE does not recieve
a valid DID at the end of each message, it will not accept any new data until sync message is passed. The
DBG LED is used to indicate ready for data.
Set time of day alarm message (MID 0x04) 6 bytes:
byte 0: 0x04
bytes 1,2,3,4: time (seconds from Unix epoch Jan 1 1970)
bit 0: beep_set_flag 1 => set, 0 => unset
bits 1-7: DID event data id # 0 for no DID. This implies that DID < 128 (ignored for TOD alarm)
Anniversary Alarm MID:
byte0: MID 0x15
byte1: DID (find the alarm msg under this DID)
byte1: 12 — DID SIZE (this is a fixed length record here to make DID complete)
byte2-5: alarm time, if greater than current time ==> absolute time, else repeat interval from now
byte6: countdown bitfield: blank, blank, blank, day, hour, 5min, min, 10sec,
byte7: Days of the week repeat: can choose more than one DOW
bit0: repeat every year hence (annual event)
bit1: repeat every Sunday hence
bit2: repeat every Monday hence
bit7: repeat every Saturday hence
byte8: scroll message DID
byte9: special effect #(0 => None, 1 => fireworks, 2=> color lines)
byte10: tune DID (0=> no sound, 1 => beeping, >0x3F DID of tune data (Not implimented))
byte11: set this byte to UNALLOCATED_ALARM_ID (0xFE), RESERVED for AlarmID_t
returned from TimeAlarms.h. This byte is used to delete pending
Anniversary Alarm DID:
Anniversary alarms need to be stored in EEPROM (long term memory). This top section described
the serial message format to send an anniversary over to ClockTHREE. To store this in EEPROM,
two extra bytes are prepended to the serial message:
The first 63 DIDs (0x01 – 0x3F) are reserved for anniversary alarms. This should help reduce the
ambiguity of when setting and gettin alarm events.
0x00 — not used. invalid.
0x01 – 0x3F — Anniversary Alarm (first DIDs reservered for anniversary alarms.)
0x40 – 0xFF — Arbitrary: scroll messages for instance.
Several messages reffer to a DID (scroll_data for instance). This is like a small file stored in
EEPROM memory. These tiny files are referenced by a unique Data IDentification or DID number. You
can read, write, and delete and delete DID files using the library described fully in “EDL.h”.
There are four main functions:
bool did_read(uint8_t did, char *dest, uint8_t *len_p),
bool get_did_addr(uint8_t did, int16_t* addr_p, uint8_t *len_p);
bool did_write(char* data), and
bool did_delete(uint8_t did).
Each returns true if when they are successful and false otherwise. Be sure to always check the return value.