You are probably already asking yourself what is WyoLum Text Format, or WTF? for short.  Let me answer that for you.  The WyoLum Text Format is a file format that defines the  LED sequencing for ClockTHREEjr.  This makes it easy for anyone to define a new language or dialect for ClockTHREEjr without programming.  Our LINGUIST backers from Kickstarter and others have already used WTF to define 10 languages and variants.  Here, we show how it works through an example: Dutch_v1.  (David Pincus’ and Roel Paes’ clear and simple rendition of the LED sequence that defined his Dutch variant was the spark that led to WTF).

In your favorite spreadsheet program (we use Google Docs), start by defining the characters in the 8×16 LED grid.

  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
0 h e t r i s p v i j f b t i e n
1 k w a r t w i n t i g n v o o r
2 o v e r v h a l f w t w e e n b
3 d r i e v i e r v i j f z e s b
4 z e v e n e g e n a c h t i e n
5 e l f t w a a l f c u u r f ' s
6 o c h t e n d s m i d d a g s a
7 d p a v o n d s n a c h t s j s

The first character “h” (in the upper left hand corner of the grid) goes in cell “C2” so that the character grid covers the range(C2:R9).

Next we define the grid vocabulary (the individual words that the faceplate is capable of displaying) .  A “word” here means a group of horizontally adjacent cells which is identified by three numbers: starting row, starting column, and length.  Words are allowed to overlap if they share common letters.  For instance “twee” and “een” at the end of row number 2 share “ee”.  The word definitions start in cell V1.  The number of words in the vocabulary is arbitrary although there are more efficient ways of stroring the LED sequence if more than 128 words are used.  In practice, we have not required more than 45 words in any variant.  If we include the labels in column U and the translations in rows 3 and 4, the Dutch_v1 words start out like this:

StartRow	0	0	0	0	1	1	1	2	2	...
StartCol	0	4	7	12	0	4	12	0	5	...
length		3	2	4	4	5	7	4	4	4	...
Dutch		het	is	vijf	tien	kwart	twinig	voor	over	half	...
Translation	it	is	five	ten	quarter	twenty	before	after	half	...

Although it is not absolutely essential, the words should appear in the same order as on the faceplate.  This allows Simulate.py (discussed later) to print the words corresponding to each time as well as to display the time on the faceplate.

Next we define when each word should light up.  There are 288 5-minute time increments in 24 hours.  Therefore, the LED sequencing matrix has 288 rows and one column per word.  In Dutch_v1 there are 27 words, so the LED sequencing matrix is 288 rows by 27 columns starting in cell V6.  In Dutch “het is twaalf uur ‘s nachts” means “it is mignight”.  This is indicated in the first row of the LED sequencing matrix by copying each word in the pharse “het is twaalf uur ‘s nachts” to the first row, in the appropriate cell.  Please refer back to the Google doc for clarification.  Even though this is really a binary (on/off) matrix we use the whole word to indicate that it should be lit so that it is easty to read the time phase right off the spreadsheet.

Finally we define the “minutes hack” leds and sequencing.  Some people love the minutes hack, others hate it.  Basically it allows the clock to display more precise time than every five minutes, but not in words.  We call it the “minutes hack” because when Anool and I made our first word clock, the “Worduino” the minute leds were an after thought.  Traces needed to be cut and extra wires needed to be added.  It really was a hack.  Since then we have designed in the “minutes hack” but the name as stuck.

You can have as many “minute” leds as you want.  The Hebrew_v1 variant uses the whole bottom row as minute LEDs, but just four works well too to show how many minutes past the displayed time have elapsed.  A minute LED is a single cell specified by a row and a column of the matrtix.  Also a variant may have any number of minute hack “states”.  The transitions are timed so that the entire sequence is displayed every five minutes.

The number of minute LEDs is specified in cell V294.  Put a zero here if your variant does not use minutes hack LEDs.  The number of minutes hack states is specified in cell X294.  Again, put a zero here if your variant does not use minutes hack LEDs.

Since Dutch_v1 does not used the minutes hack feature, we use Shai Aharonov’s Hebrew_v1 as an example.

n_min_led	16	n_min_state	20

Including the labels the LED locations for this variant look like this (the first 7 is located in cell V295):

minute row	7	7	7	7	7	7	7	...
minute column	0	1	2	3	4	5	6	...

The next n_min_state rows (20 in this case) define when each minute led is lit.  Put an “X”s in the appropriate cells.

Simulating your ClockTHREEjr variant

After you have defined your ClockTHREEjr variant in the above format, save the file as “.csv”.  This stands for “comma separated value.”  Prior to the file definition defined above, we tried several different “.csv” formats. To indicate that the above format is adhered to and to distinguish WTF files from any old .csv file, we use the “.wtf” extension.  Rename your recently saved “.csv” file to YOUR_LANGUAGE_v1.wtf, with “YOUR_LANGUAGE” and “v1” replaced with a name that describes the language and version.  Simulate.py requires the “.wtf” extension.

Install Python

If you don’t have python and numpy installed on your system, do that now.

http://www.python.org/getit/, http://numpy.org/

Start Simulate.py from the command line with your “.wtf” file as the first argument.  On my system this looks like this:

> python Simulate.py Dutch_v1.wtf

On Windows:

start->run “cmd”

DOS> cd  “the directory where your wtf file is located”

DOS> Simulate.py Dutch_v1.wtf

Shortcut keys:

H/h move forward/backward one hour

M/m move forward/backward one minute

F/f  move forward/backward five minutes

U/l change to UPPER or lower case

To create the a header file to run on ClockTHREEjr, select File-> C-Convert from the menu.  Save the  header (“.h”) file in your arduino sketch directory (currently libraries/ClockTHREE/examples/ClockTHREE_04/)

To upload your new ClockTHREEjr variant requires one line change in the sketch file ClockTHREE_04.ino.  On or about line 28 comment out the existing header file and replace it with your new variant header file.

WAS

#include "english_v3.h"

AFTER

//#include "english_v3.h"
#include "YOUR_LANGUAGE_v1.h"

Finally upload your new ClockTHREEjr variant! Congratulations! Send a copy of the “.wtf” file to infor@wyolum.com if would like to make your new variant open source.