Digital Clock with CircuitPython

Adafruit 1.2" 4-Digit 7-Segment Display w/I2C Backpack - Red

Huge red 7-segment clock display soldered to backpack with all segments lit

What's better than a single LED? Lots of LEDs! A fun way to make a numeric display is to use a 4-digit 7-segment display. LED...

guides with product

Out of Stock

Adafruit DS3231 Precision RTC - STEMMA QT

The datasheet for the DS3231 explains that this part is an "Extremely Accurate I²C-Integrated RTC/TCXO/Crystal". And, hey, it does exactly...

guides with product

$13.95

In Stock

Adafruit I2C Stemma QT Rotary Encoder Breakout with NeoPixel

Top view video of a hand turning the rotary encoder knobs on three PCBs. The NeoPixel LEDs on each PCB change color. The OLED display changes its readout data with each twisty-turn.

Rotary encoders are soooo much fun! Twist em this way, then twist them that way. Unlike potentiometers, they go all the way around and often have little detents for tactile feedback....

$5.95

In Stock

3 x STEMMA QT Cable

JST SH 4-pin Cable - 100mm Long

Out of Stock

1 x CR1220 12mm Diameter

3V Lithium Coin Cell Battery - CR1220

1 x USB-C Cable

Pink and Purple Woven USB A to C - 2 meters long

Download the latest version of CircuitPython for this board via circuitpython.org

Hardware

The following hardware is required for the assembly.

6x M2.5 x 6mm long machine screws
4x M2 x 8mm long machine screws
4x M3 x 6mm long machine screws
4x M3 x 10mm long machine screws
4x M2 hex nuts
4x M3 hex nuts

Optional

1 x Light Diffuser Gel Overlays

11.7 by 8.3 Inches colored sheets

Buy Now

Text editor powered by tinymce.

Circuit Diagram

The diagram below provides a general visual reference for wiring of the components once you get to the Assembly page. This diagram was created using the software package Fritzing.

Adafruit Library for Fritzing

Adafruit uses the Adafruit's Fritzing parts library to create circuit diagrams for projects. You can download the library or just grab individual parts. Get the library and parts from GitHub - Adafruit Fritzing Parts.

Wired Connections

Feather connects to 1.2" LED Backpack via STEMMA QT.
The DS3231 breakout connects to 1.2" LED Backpack via STEMMA QT
The Rotary Encoder connects to DS3231 breakout via STEMMA QT

USB Power

The Feather RP2040 is powered with a 5V 1A USB power supply.

Text editor powered by tinymce.

CAD Files

3D Printed Parts

STL files for 3D printing are oriented to print "as-is" on FDM style machines. Parts are designed to 3D print without any support material using PLA filament. Original design source may be downloaded using the links below.

Download STLs.zip

Download CAD source

CAD Assembly

The LED breakout is secured to the LED mount with M2 sized screws.

The LED mount is mounted to the casing using M3 sized screws.

The Feather RP2040 and DS3231 breakouts are secured to the PCB mount using M2.5 sized screws.

The rotary encoder is panel mounted to the left side of the casing.

The base legs are secured to the bottom of the casing with M3 sized screws.

The PCB mount is secured inside the casing using the screws from the base legs.

The back and front covers press fit into the casing.

Build Volume

The parts require a 3D printer with a minimum build volume.

140mm (X) x 66mm (Y) x 80mm (Z)

Design Source Files

The project assembly was designed in Fusion 360. This can be downloaded in different formats like STEP, STL and more.

Electronic components like Adafruit's boards, displays, connectors and more can be downloaded from the Adafruit CAD parts GitHub Repo.

Text editor powered by tinymce.

Install CircuitPython

CircuitPython is a derivative of MicroPython designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the CIRCUITPY drive to iterate.

CircuitPython Quickstart

Follow this step-by-step to quickly get CircuitPython running on your board.

install_circuitpython_on_rp2040_RP2040_UF2_downloaded.jpg

Click the link above to download the latest CircuitPython UF2 file.

Save it wherever is convenient for you.

To enter the bootloader, hold down the BOOT/BOOTSEL button (highlighted in red above), and while continuing to hold it (don't let go!), press and release the reset button (highlighted in red or blue above). Continue to hold the BOOT/BOOTSEL button until the RPI-RP2 drive appears!

If the drive does not appear, release all the buttons, and then repeat the process above.

You can also start with your board unplugged from USB, press and hold the BOOTSEL button (highlighted in red above), continue to hold it while plugging it into USB, and wait for the drive to appear before releasing the button.

A lot of people end up using charge-only USB cables and it is very frustrating! Make sure you have a USB cable you know is good for data sync.

install_circuitpython_on_rp2040_RP2040_bootloader_drive.jpg

You will see a new disk drive appear called RPI-RP2.

Drag the adafruit_circuitpython_etc.uf2 file to RPI-RP2.

The RPI-RP2 drive will disappear and a new disk drive called CIRCUITPY will appear.

That's it, you're done! :)

Safe Mode

You want to edit your code.py or modify the files on your CIRCUITPY drive, but find that you can't. Perhaps your board has gotten into a state where CIRCUITPY is read-only. You may have turned off the CIRCUITPY drive altogether. Whatever the reason, safe mode can help.

Safe mode in CircuitPython does not run any user code on startup, and disables auto-reload. This means a few things. First, safe mode bypasses any code in boot.py (where you can set CIRCUITPY read-only or turn it off completely). Second, it does not run the code in code.py. And finally, it does not automatically soft-reload when data is written to the CIRCUITPY drive.

Therefore, whatever you may have done to put your board in a non-interactive state, safe mode gives you the opportunity to correct it without losing all of the data on the CIRCUITPY drive.

Entering Safe Mode

To enter safe mode when using CircuitPython, plug in your board or hit reset (highlighted in red above). Immediately after the board starts up or resets, it waits 1000ms. On some boards, the onboard status LED (highlighted in green above) will blink yellow during that time. If you press reset during that 1000ms, the board will start up in safe mode. It can be difficult to react to the yellow LED, so you may want to think of it simply as a slow double click of the reset button. (Remember, a fast double click of reset enters the bootloader.)

In Safe Mode

If you successfully enter safe mode on CircuitPython, the LED will intermittently blink yellow three times.

If you connect to the serial console, you'll find the following message.

Copy Text

Auto-reload is off.
Running in safe mode! Not running saved code.

CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode.

Press any key to enter the REPL. Use CTRL-D to reload.

Auto-reload is off.
Running in safe mode! Not running saved code.

CircuitPython is in safe mode because you pressed the reset button during boot. Press again to exit safe mode.

Press any key to enter the REPL. Use CTRL-D to reload.

You can now edit the contents of the CIRCUITPY drive. Remember, your code will not run until you press the reset button, or unplug and plug in your board, to get out of safe mode.

Flash Resetting UF2

If your board ever gets into a really weird state and CIRCUITPY doesn't show up as a disk drive after installing CircuitPython, try loading this 'nuke' UF2 to RPI-RP2. which will do a 'deep clean' on your Flash Memory. You will lose all the files on the board, but at least you'll be able to revive it! After loading this UF2, follow the steps above to re-install CircuitPython.

Download flash erasing "nuke" UF2

Text editor powered by tinymce.

Code the Clock

Once you've finished setting up your Feather RP2040 with CircuitPython, you can access the code and necessary libraries by downloading the Project Bundle.

To do this, click on the Download Project Bundle button in the window below. It will download to your computer as a zipped folder.

Download Project Bundle

# SPDX-FileCopyrightText: 2024 Liz Clark for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import board
import simpleio
import adafruit_ds3231
from adafruit_ticks import ticks_ms, ticks_add, ticks_diff
from adafruit_ht16k33 import segments
from adafruit_debouncer import Button
from adafruit_seesaw import seesaw, rotaryio, digitalio

# min and max display brightness range
# value must be 0.0 to 1.0
max_brightness = 1
min_brightness = 0.01
# weekday hours to have clock on max brightness
# (24-hour time)
weekday_wakeup = 8
weekday_sleep = 21
# weekend hours to have clock on max brightness
# (24-hour time)
weekend_wakeup = 9
weekend_sleep = 23

i2c = board.STEMMA_I2C()

rtc = adafruit_ds3231.DS3231(i2c)
seesaw = seesaw.Seesaw(i2c, addr=0x36)
seesaw.pin_mode(24, seesaw.INPUT_PULLUP)
ss_pin = digitalio.DigitalIO(seesaw, 24)
button = Button(ss_pin, long_duration_ms=1000)

encoder = rotaryio.IncrementalEncoder(seesaw)
last_position = 0

# pylint: disable-msg=using-constant-test
if False:  # change to True if you want to set the time!
    #                     year, mon, date, hour, min, sec, wday, yday, isdst
    t = time.struct_time((2024, 1, 25, 15, 7, 0, 3, -1, -1))
    # you must set year, mon, date, hour, min, sec and weekday
    # yearday is not supported, isdst can be set but we don't do anything with it at this time
    print("Setting time to:", t)  # uncomment for debugging
    rtc.datetime = t
    print()
# pylint: enable-msg=using-constant-test

display = segments.BigSeg7x4(i2c)

display.fill(0)
display.brightness = max_brightness

display.colon = True

def clock_conversion(h, m, set_brightness):
    # pylint: disable-msg=simplifiable-if-expression
    am_pm = False if h < 12 else True
    hour_12 = h if h <= 12 else h - 12
    if hour_12 == 0:
        hour_12 = 12
    display.print(f"{(hour_12):02}:{m:02}")
    display.ampm = am_pm
    if set_brightness:
        if awake_hours[0] <= h <= awake_hours[1] - 1:
            display.brightness = max_brightness
        elif h is awake_hours[0] - 1:
            bright = simpleio.map_range(m, 0, 59, min_brightness, max_brightness)
            display.brightness = bright
        elif h is awake_hours[1]:
            bright = simpleio.map_range(m, 0, 59, max_brightness, min_brightness)
            display.brightness = bright
        else:
            display.brightness = min_brightness
    else:
        display.brightness = max_brightness

clock_clock = ticks_ms()
clock_timer = 1 * 1000
clock_mode = True
set_hour = True
power_up = True
hour = 0
minute = 0

while True:

    if clock_mode:
        button.update()
        if ticks_diff(ticks_ms(), clock_clock) >= clock_timer:
            t = rtc.datetime
            if t.tm_wday in range(5, 6):
                awake_hours = [weekend_wakeup, weekend_sleep]
            else:
                awake_hours = [weekday_wakeup, weekday_sleep]
            if t.tm_sec < 1 or power_up:
                power_up = False
                clock_conversion(t.tm_hour, t.tm_min, True)
            clock_clock = ticks_add(clock_clock, clock_timer)
    else:
        button.update()
        position = -encoder.position
        if position != last_position:
            if position > last_position:
                if set_hour:
                    hour = (hour + 1) % 24
                else:
                    minute = (minute + 1) % 60
            else:
                if set_hour:
                    hour = (hour - 1) % 24
                else:
                    minute = (minute - 1) % 60
            clock_conversion(hour, minute, False)
            last_position = position
        if button.short_count:
            set_hour = not set_hour
        # toggling dots with not did not seem to work consistantly
        # so setting manually
        if set_hour:
            display.top_left_dot = True
            display.bottom_left_dot = False
        else:
            display.top_left_dot = False
            display.bottom_left_dot = True
    if button.long_press:
        if not clock_mode:
            t = rtc.datetime
            new_t = time.struct_time((t.tm_year, t.tm_mon, t.tm_mday,
                                      hour, minute, t.tm_sec, t.tm_wday,
                                      t.tm_yday, t.tm_isdst))
            print("Setting time to:", new_t)
            rtc.datetime = new_t
            clock_clock = ticks_add(clock_clock, clock_timer)
            power_up = True
            display.top_left_dot = False
            display.bottom_left_dot = False
        else:
            set_hour = True
            t = rtc.datetime
            hour = t.tm_hour
            minute = t.tm_min
        clock_mode = not clock_mode
        display.blink_rate = not display.blink_rate

# SPDX-FileCopyrightText: 2024 Liz Clark for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import board
import simpleio
import adafruit_ds3231
from adafruit_ticks import ticks_ms, ticks_add, ticks_diff
from adafruit_ht16k33 import segments
from adafruit_debouncer import Button
from adafruit_seesaw import seesaw, rotaryio, digitalio

# min and max display brightness range
# value must be 0.0 to 1.0
max_brightness = 1
min_brightness = 0.01
# weekday hours to have clock on max brightness
# (24-hour time)
weekday_wakeup = 8
weekday_sleep = 21
# weekend hours to have clock on max brightness
# (24-hour time)
weekend_wakeup = 9
weekend_sleep = 23

i2c = board.STEMMA_I2C()

rtc = adafruit_ds3231.DS3231(i2c)
seesaw = seesaw.Seesaw(i2c, addr=0x36)
seesaw.pin_mode(24, seesaw.INPUT_PULLUP)
ss_pin = digitalio.DigitalIO(seesaw, 24)
button = Button(ss_pin, long_duration_ms=1000)

encoder = rotaryio.IncrementalEncoder(seesaw)
last_position = 0

# pylint: disable-msg=using-constant-test
if False:  # change to True if you want to set the time!
    #                     year, mon, date, hour, min, sec, wday, yday, isdst
    t = time.struct_time((2024, 1, 25, 15, 7, 0, 3, -1, -1))
    # you must set year, mon, date, hour, min, sec and weekday
    # yearday is not supported, isdst can be set but we don't do anything with it at this time
    print("Setting time to:", t)  # uncomment for debugging
    rtc.datetime = t
    print()
# pylint: enable-msg=using-constant-test

display = segments.BigSeg7x4(i2c)

display.fill(0)
display.brightness = max_brightness

display.colon = True

def clock_conversion(h, m, set_brightness):
    # pylint: disable-msg=simplifiable-if-expression
    am_pm = False if h < 12 else True
    hour_12 = h if h <= 12 else h - 12
    if hour_12 == 0:
        hour_12 = 12
    display.print(f"{(hour_12):02}:{m:02}")
    display.ampm = am_pm
    if set_brightness:
        if awake_hours[0] <= h <= awake_hours[1] - 1:
            display.brightness = max_brightness
        elif h is awake_hours[0] - 1:
            bright = simpleio.map_range(m, 0, 59, min_brightness, max_brightness)
            display.brightness = bright
        elif h is awake_hours[1]:
            bright = simpleio.map_range(m, 0, 59, max_brightness, min_brightness)
            display.brightness = bright
        else:
            display.brightness = min_brightness
    else:
        display.brightness = max_brightness

clock_clock = ticks_ms()
clock_timer = 1 * 1000
clock_mode = True
set_hour = True
power_up = True
hour = 0
minute = 0

while True:

    if clock_mode:
        button.update()
        if ticks_diff(ticks_ms(), clock_clock) >= clock_timer:
            t = rtc.datetime
            if t.tm_wday in range(5, 6):
                awake_hours = [weekend_wakeup, weekend_sleep]
            else:
                awake_hours = [weekday_wakeup, weekday_sleep]
            if t.tm_sec < 1 or power_up:
                power_up = False
                clock_conversion(t.tm_hour, t.tm_min, True)
            clock_clock = ticks_add(clock_clock, clock_timer)
    else:
        button.update()
        position = -encoder.position
        if position != last_position:
            if position > last_position:
                if set_hour:
                    hour = (hour + 1) % 24
                else:
                    minute = (minute + 1) % 60
            else:
                if set_hour:
                    hour = (hour - 1) % 24
                else:
                    minute = (minute - 1) % 60
            clock_conversion(hour, minute, False)
            last_position = position
        if button.short_count:
            set_hour = not set_hour
        # toggling dots with not did not seem to work consistantly
        # so setting manually
        if set_hour:
            display.top_left_dot = True
            display.bottom_left_dot = False
        else:
            display.top_left_dot = False
            display.bottom_left_dot = True
    if button.long_press:
        if not clock_mode:
            t = rtc.datetime
            new_t = time.struct_time((t.tm_year, t.tm_mon, t.tm_mday,
                                      hour, minute, t.tm_sec, t.tm_wday,
                                      t.tm_yday, t.tm_isdst))
            print("Setting time to:", new_t)
            rtc.datetime = new_t
            clock_clock = ticks_add(clock_clock, clock_timer)
            power_up = True
            display.top_left_dot = False
            display.bottom_left_dot = False
        else:
            set_hour = True
            t = rtc.datetime
            hour = t.tm_hour
            minute = t.tm_min
        clock_mode = not clock_mode
        display.blink_rate = not display.blink_rate

Upload the Code and Libraries to the Feather RP2040

After downloading the Project Bundle, plug your Feather RP2040 into the computer's USB port with a known good USB data+power cable. You should see a new flash drive appear in the computer's File Explorer or Finder (depending on your operating system) called CIRCUITPY. Unzip the folder and copy the following items to the Feather RP2040's CIRCUITPY drive:

lib folder
code.py

Your Feather RP2040 CIRCUITPY drive should look like this after copying the lib folder and the code.py file.

How the CircuitPython Code Works

At the top of the code are user configurable settings for the clock. The first two are for the brightness range. The max_brightness is the setting the clock will have during the day and min_brightness is the setting the clock will have overnight. The next settings are for the hours that trigger the brightness to change during the week and during the weekend. These hours are in 24-hour time.

# min and max display brightness range
# value must be 0.0 to 1.0
max_brightness = 1
min_brightness = 0.01
# weekday hours to have clock on max brightness
# (24-hour time)
weekday_wakeup = 8
weekday_sleep = 21
# weekend hours to have clock on max brightness
# (24-hour time)
weekend_wakeup = 9
weekend_sleep = 23

# min and max display brightness range
# value must be 0.0 to 1.0
max_brightness = 1
min_brightness = 0.01
# weekday hours to have clock on max brightness
# (24-hour time)
weekday_wakeup = 8
weekday_sleep = 21
# weekend hours to have clock on max brightness
# (24-hour time)
weekend_wakeup = 9
weekend_sleep = 23

I2C

Next all of the breakouts are instantiated over I2C. The button on the rotary encoder is passed as a Button object to the adafruit_debouncer library.

i2c = board.STEMMA_I2C()

rtc = adafruit_ds3231.DS3231(i2c)
seesaw = seesaw.Seesaw(i2c, addr=0x36)
seesaw.pin_mode(24, seesaw.INPUT_PULLUP)
ss_pin = digitalio.DigitalIO(seesaw, 24)
button = Button(ss_pin, long_duration_ms=1000)

encoder = rotaryio.IncrementalEncoder(seesaw)
last_position = 0

display = segments.BigSeg7x4(i2c)

i2c = board.STEMMA_I2C()

rtc = adafruit_ds3231.DS3231(i2c)
seesaw = seesaw.Seesaw(i2c, addr=0x36)
seesaw.pin_mode(24, seesaw.INPUT_PULLUP)
ss_pin = digitalio.DigitalIO(seesaw, 24)
button = Button(ss_pin, long_duration_ms=1000)

encoder = rotaryio.IncrementalEncoder(seesaw)
last_position = 0

display = segments.BigSeg7x4(i2c)

Set the RTC

There is a bit of code that lets you initially set the RTC module. If you change the if statement to True, you can edit the struct_time object to match your current time and save the code to program the RTC.

Remember to change it back to False and resave it when done setting the time, otherwise if the board is reset or power cycled the time we be incorrectly set.

if False:  # change to True if you want to set the time!
    #                     year, mon, date, hour, min, sec, wday, yday, isdst
    t = time.struct_time((2024, 1, 25, 15, 7, 0, 3, -1, -1))
    # you must set year, mon, date, hour, min, sec and weekday
    # yearday is not supported, isdst can be set but we don't do anything with it at this time
    print("Setting time to:", t)  # uncomment for debugging
    rtc.datetime = t
    print()

if False:  # change to True if you want to set the time!
    #                     year, mon, date, hour, min, sec, wday, yday, isdst
    t = time.struct_time((2024, 1, 25, 15, 7, 0, 3, -1, -1))
    # you must set year, mon, date, hour, min, sec and weekday
    # yearday is not supported, isdst can be set but we don't do anything with it at this time
    print("Setting time to:", t)  # uncomment for debugging
    rtc.datetime = t
    print()

Clock Conversion

There is a function called clock_conversion that takes care of converting the time from the RTC to 12-hour time for displaying on the 7-segment display. It also adjusts the display brightness.

def clock_conversion(h, m, set_brightness):
    am_pm = False if h < 12 else True
    hour_12 = h if h <= 12 else h - 12
    if hour_12 == 0:
        hour_12 = 12
    display.print(f"{(hour_12):02}:{m:02}")
    display.ampm = am_pm
    if set_brightness:
        if awake_hours[0] <= h <= awake_hours[1] - 1:
            display.brightness = max_brightness
        elif h is awake_hours[0] - 1:
            bright = simpleio.map_range(m, 0, 59, min_brightness, max_brightness)
            display.brightness = bright
        elif h is awake_hours[1]:
            bright = simpleio.map_range(m, 0, 59, max_brightness, min_brightness)
            display.brightness = bright
        else:
            display.brightness = min_brightness
    else:
        display.brightness = max_brightness

def clock_conversion(h, m, set_brightness):
    am_pm = False if h < 12 else True
    hour_12 = h if h <= 12 else h - 12
    if hour_12 == 0:
        hour_12 = 12
    display.print(f"{(hour_12):02}:{m:02}")
    display.ampm = am_pm
    if set_brightness:
        if awake_hours[0] <= h <= awake_hours[1] - 1:
            display.brightness = max_brightness
        elif h is awake_hours[0] - 1:
            bright = simpleio.map_range(m, 0, 59, min_brightness, max_brightness)
            display.brightness = bright
        elif h is awake_hours[1]:
            bright = simpleio.map_range(m, 0, 59, max_brightness, min_brightness)
            display.brightness = bright
        else:
            display.brightness = min_brightness
    else:
        display.brightness = max_brightness

The Loop

In the loop, ticks is used to check the RTC every second. When the minute advances, the clock_conversion function is called to update the display. The awake_hours (full brightness hours on the weekend versus weekdays) are also adjusted depending on the reading from the RTC.

if clock_mode:
        button.update()
        if ticks_diff(ticks_ms(), clock_clock) >= clock_timer:
            t = rtc.datetime
            if t.tm_wday in range(5, 6):
                awake_hours = [weekend_wakeup, weekend_sleep]
            else:
                awake_hours = [weekday_wakeup, weekday_sleep]
            if t.tm_sec < 1 or power_up:
                power_up = False
                clock_conversion(t.tm_hour, t.tm_min, True)
            clock_clock = ticks_add(clock_clock, clock_timer)

if clock_mode:
        button.update()
        if ticks_diff(ticks_ms(), clock_clock) >= clock_timer:
            t = rtc.datetime
            if t.tm_wday in range(5, 6):
                awake_hours = [weekend_wakeup, weekend_sleep]
            else:
                awake_hours = [weekday_wakeup, weekday_sleep]
            if t.tm_sec < 1 or power_up:
                power_up = False
                clock_conversion(t.tm_hour, t.tm_min, True)
            clock_clock = ticks_add(clock_clock, clock_timer)

Set the Time

If a long press is read from the button on the encoder while in clock_mode, clock_mode is set to False and you are able to use the encoder to adjust the hour and minute settings. While in this mode, the display blinks. When you long press the button again, it updates the RTC with the hour and minute settings you've just entered with the encoder and goes back to clock_mode.