Uploading Code

Make sure to use Arduino IDE 1.6.4 or higher and follow this tutorial to install the Adafruit boards.

Download the code from github by clicking Download ZIP. Uncompress the file and copy the folder to your Arduino sketchbook folder.

You will also need to install some Adafruit Arduino libraries. Follow this tutorial if you are unfamiliar with how to do this. You need to install the following Adafruit Arduino libraries:

Once that is done, open the sketch and select Tools → Board → Pro Trinket 5V/16MHz (USB). See if the code compiles. If the libraries aren't installed correctly you will see errors.

Put the Pro Trinket into bootloader mode either by unplugging and replugging the Pro Trinket into the computer with your MicroUSB cable or by hitting the reset button. The reset button can be difficult or impossible to access if you've soldered the RTC on top or if you've already installed the circuit into the enclosure! So I find plugging the board into USB to work best.

When the red LED on the Pro Trinket is pulsing, the board is in bootloader mode. Once you're in bootloader mode, upload the code! If everything was done correctly, it should start telling you the time!

Understanding the Code

Startup Sequence

When the clock starts up, all of the individual words will light up sequentially during the startup sequence. This sequence is defined by the flashWords() function in the setup() function.

Setting the Time

The first time the code is run, the time on the RTC module will be set to the time that the code was compiled on your computer.

  if (! RTC.isrunning()) {
    Serial.println("RTC is NOT running!");
    // following line sets the RTC to the date & time this sketch was compiled
    RTC.adjust(DateTime(__DATE__, __TIME__));
    // DST? If we're in it, let's subtract an hour from the RTC time to keep our DST calculation correct. This gives us
    // Standard Time which our DST check will add an hour back to if we're in DST.
    DateTime standardTime = RTC.now();
    if (dst_rtc.checkDST(standardTime) == true) { // check whether we're in DST right now. If we are, subtract an hour.
      standardTime = standardTime.unixtime() - 3600;
    }
    RTC.adjust(standardTime);
  }

If you need to reset the time, this can be done by commenting out the if statement here but leaving in the line:

RTC.adjust(DateTime(__DATE__, __TIME__));

Since this clock only displays the time within five minutes, some find it helpful to add 2.5 minutes (or 150 seconds) to the actual time to give a closer account of the time.

// add 2.5 minutes to get better estimates
    theTime = RTC.now();
    theTime = theTime.unixtime() + 150;
    RTC.adjust(theTime);

The last line adjusts the real time clock. Very important!

Daylight Saving Time

Do you live in a territory that observes daylight saving time (DST)? If you do, you usually have to reprogram your clocks twice a year! This clock includes some code so that the adjustments are made automatically. The code follows the current rules for DST in the USA and Canada. If you live somewhere that follows different DST rules you may be able to modify the code to suit your rules— just look in the DST_RTC library functions. Wikipedia has a great reference on daylight saving time rules.

If you live in a territory that doesn't observe daylight saving time, just alter the following line by changing the 1 to 0.

#define OBSERVE_DST 1

The daylight saving time code works by keeping the real time clock on "standard time" and checking to see if the current date falls within daylight saving time. If the date falls within daylight saving time, an hour is added to the displayed time to convert from standard time to daylight saving time.

Brightness Adjustment

The clock is programmed to change brightness based on the time of day, operating at a lower brightness at nighttime. You can change these settings in the code.

DAYBRIGHTNESS is the brightness level during the day, NIGHTBRIGHTNESS is the brightness level during the night. Any number between 0-255 is acceptable, but at 0 you won't see anything! 255 is maximum brightness.

MORNINGCUTOFF and NIGHTCUTOFF set which hours the clock will operate at DAYBRIGHTNESS and NIGHTBRIGHTNESS. These hours are for a 24 hour clock, so 22 would be 10pm. Between midnight and 1am, the hour is 0.

// brightness based on time of day- could try warmer colors at night?
#define DAYBRIGHTNESS 80
#define NIGHTBRIGHTNESS 40

// cutoff times for day / night brightness. feel free to modify.
#define MORNINGCUTOFF 7  // when does daybrightness begin?   7am
#define NIGHTCUTOFF   22 // when does nightbrightness begin? 10pm

If you don't want the clock to change brightness throughout the day, you can also just comment out the adjustBrightness() function in the main loop().

Color Shifting Speed

The speed at which the colors shift is controlled with a delay in milliseconds defined as SHIFTDELAY. To speed up the color shifting, decrease the number. To slow down the color shifting, increase the number.

#define SHIFTDELAY 100   // controls color shifting speed

Monochrome Mode

Maybe the constant color shifting makes you queasy. You can simply run the clock to light the display in a single color.

First, we define that color- in this case white:

// if you want to just run the clock monochrome
#define WHITE 200, 255, 255

255, 255, 255 would be pure white, but with RGB LEDs this can look a little purple so you can try adjusting the numbers. 

Now in the colorFunctions tab, edit the two lines which set the Pixel color. Comment out the longer line and uncomment out the shorter line.

//matrix.setPixelColor(i, Wheel(((i * 256 / matrix.numPixels()) + j) & 255));
matrix.setPixelColor(i, WHITE);
This guide was first published on Jul 07, 2015. It was last updated on Jul 07, 2015. This page (Uploading Code) was last updated on Nov 13, 2018.