The power packed I2GPS board (photo by Brian Krontz)

Here is a sneak preview into a product we are working on: the I2GPS.  The I2GPS is a slightly modified I2SD.  The only difference is that Anool added an interface to the hacker friendly Fastrax UP501 GPS reciever.  We think we have found a winning combination: for processing an arduino compatible ATMEGA328, a micro SD for massive amounts of storage, the ChronoDot (macetech.com) compatible DS3231 real time clock and finally the UP501 GPS module.  This board also has on board voltage regulators for both 3 and 5 volts and plenty of break out pins for hackablity.

The initial application is a GPS disciplined timing reference that acquires and maintains 1 microsecond timing accuracy.  This even works in the basement of my house!  When the GPS signal is lost, the RTC maintains 1 millisecond / hour accuracy on its own.  I know that for many DIY apps this is overkill, but we are building a race timing system that requires this level of accuracy.

But why stop there?  With GPS in hand, we can determine the timezone!  This sounds like a piece of cake, but turned out to be a pretty tricky problem.  There are literally thousands and thousands of individually defined timezones!  In fact there are 27,732 defined in the generously provided shape file by Eric Muller at http://efele.net/maps/tz/world/.

The good news is that I found a Java library that looks up time zone by GPS fix, the bad news is that they wanted $2000 for it!  With Eric’s shape file in hand, and an open source shape file library written in Python only one more piece of information was missing: the list of GMT offsets which was thankfully provided by Wikipedia.

We had an internal debate here at WyoLum.  Kevin Osborn found an elegant solution based on zip codes that worked for the United States but was not easily extendable to the rest of the world.  While driving to work last week, I realized that we could easily store the timezone for every  single latitude and longitude in a fine grid over the Earth on the SD card.  And why not?  With a measly 1GB SD card, the I2GPS has way more memory than processing power.

Within an hour I had a function (albeit non optimized) that could look up the timezone for any latitude, longitude pair.  I guess that answers the make/buy decision that the propriety code begged me to consider.  Within 5 hours I had a database of latitude, longetude, timezone, daylight time that was about 22 MB in size.  Large for a micro, but fits with ease onto a 1GB card.  I used 1 degree latitude bins and 0.1 degree longitude bins for about 648000 points.

For implementation reasons I broke the large file up into manageable chunks by latitude and put them on the micro SD card.  Finally I wrote a lookup routine for the micro controller that looks up the timezone by latitude and longitude.

Aahhh setting your awesome word clock for daylight savings time is so yesterday…

Code and hardware will be available soon.

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.

The LED sequencing matrix displayed for English_v3.

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.

Volunteer Partnerships:  These partners have not asked for any compensation for supporting ClockTHREEjr.

• Wise Time With Arduino, (FlorinC) http://timewitharduino.blogspot.com/ – The original impetus for bringing the costs down on ClockTHREEjr and project lead
• Brian Krontz, http://www.briankrontz.com/ – Photographer.  Brian indicated in no uncertain terms how much room for improvement we had in the photographic arts!  We challenged him to “show us what we were missing” and that he did.

Please visit their websites and price them on your next project.  We have found them to be reliable and more affordable than all of their competitors.

• Hines Design Labs http://angushines.com – Custom CNC work, and laser cutting.  Angus re-designed our faceplates to be much more manufacturable and flexible.  We have priced other services and have found Angus Hines to be literally half the cost.
• Seeed Studio, http://www.seeedstudio.com/depot/ – PCB, kits, assembly.  We were shocked by the discounts we could receive from Seeed Studio if we could buy in quantities of 100 or more.

In order to sync the 1pps signals to the real time clock square wave, I made some modifications to two libraries: Time, and TinyGPS (by Mikal Hart).  Precision timing is made possible by adding a 1Hz reference to the existing library.  Millisecond accuracy is obtained by keeping track of the last 1 Hz transistion and the 1 Hz duration.  So in addition to the standard year(), month(), day(), hour(), minute(), and second() functions, I added millisecond() which returns an integer between 0 and 999.

Some other functions were added to support the 1Hz reference:

/* TJS: one Hertz interrupt to be called on rising edge of one Hz square wave. 
 *      Used to sync with GPS clock or other 1Hz source to get millisecond time accuracy
 *      trigger is one of LOW, CHANGE, RISING, or FALLING
 */
void set_1Hz_ref(time_t current_time, int interrupt_pin, void(*cb_ptr)(), int trigger);

/*
 * TJS: stop counting ticks.  Used to sync with absolute time.
 */
void pause_1Hz();

/*
 * TJS: start counting ticks.  Used to sync with absolute time.
 */
void unpause_1Hz();

The TinyGPS library also needed to be modified to support precision time synchronization.  The key enabler is a fix notification scheme.  At the heart is a user provided function that gets called when a new fix message arrives.   This function was added to support this:

/*
 * TJS: Add a callback routine to be called when a new fix arrives.
 */
void TinyGPS::add_callback(fix_cb_t fct_ptr);

// Example fix callback signature
void grab_datetime(unsigned long _date,
                   unsigned long _time,
                   long lat,
                   long lon,
                   long alt,
                   unsigned long speed,
                   unsigned long course);

ISSUE #1: ”BYTE” keyword is no longer supported, but it is not required with the new Serial.write command.

FIX: Replace Serial.print(val, BYTE); with Serial.write(val);

ISSUE #2: “wprogram.h” not found.  It has been renamed “Arduino.h”

FIX: The release notes includes a handy pre-compiler directive to check of the arduino flavor you are using.

 #if defined(ARDUINO) && ARDUINO >= 100
 #include "Arduino.h"
 #else
 #include "WProgram.h"
 #endif

ISSUE #3: Wire.send, Wire.recieve renamed to Wire.write and Wire.read resp.

FIX: At first I tried writing a couple of macros like FIX 1, but after it took me a long time to discover my mistake, I decided not to be clever here.  I now I just add a pre-compiler conditional for Arduino 1.0.  So you end up wrapping the old code with the check wherever “Wire.send” and “Wire.receive()” where.  Like this (and so on for read/receive).

// Arduino 1.0 compatibility

#if defined(ARDUINO) && ARDUINO >= 100
Wire.write("DATA", 4)
#else
Wire.send("DATA", 4)
#endif

ISSUE #4: NewSoftSerial renamed to SoftwareSerial

FIX: This fix stinks, I don’t know a good way to solve it (suggestions welcome!) Arduino will scan the PDE file for ANY #includes EVEN when precluded by a pre-processor directive. The fix is to comment/uncomment the code for the correct version of Arduino.

For Arduino 1.0:

#include <SoftwareSerial.h>

SoftwareSerial sws(4, 5);

//#include <SoftwareSerial.h>

//SoftwareSerial sws(4, 5);