The PyPortal Countdown is doing a couple of cool things to make your event display:


First, it displays a bitmap graphic named circuitpython_day_countdown_background.bmp as the screen's background. This is a 320 x 240 pixel RGB 16-bit raster graphic in .bmp format.


In order to calculate the countdown, the PyPortal's CircuitPython code determines the local time by checking the internet time via the WiFi connection. It uses your IP address information to determine the local time. The good news is that once you've set up your timezone (or if the IP is fine) you do not have to adjust for daylight savings, leap years, etc.

In some cases, the time may not appear correctly based on your IP address, but don't fear! You can override that by manually setting the timezone in your file. Plus, you can explicitly set your PyPortal to display a different time zone in case you have travel plans or a friend in Tokyo or something!

To do this, you'll add this line to your file:

'timezone' : "America/New_York"

Here's a great list of valid timezones from the IANA Timezone Database. Head there to find the name of the one you want. Simply find the nearest timezone to your desired location, and use that name as displayed in the TZ database name column. 

Event Time

Since this is a one-time event, you'll need to tell the PyPortal when the event is, this is with respect to your local time so if its an event in another country or time zone, convert that to the local time where you are at. You can adjust the following variables to make this work:


For example, here's the countdown setting for CircuitPython Day 2020:

Download: file
# The time of the Event

Note that EVENT_HOUR is in 24-hour time so it will range from 00 to 23


Then, it displays the info with bitmapped fonts to overlay on top of the background. You can learn more about converting type in this guide.

Now, the PyPortal will display the background and countdown until it reaches the event!

When the event time arrives, you'll be treated with the countdown_event.bmp image.


If you like, you can also customize the background for a different event, by making your own 320x240 16-bit RGB color .bmp file. Then, adjust your setting to match the new event's time.


Let's have a look at how the code places the elements on screen. Below, we can see the text items that are displayed.

Text Position

Depending on the design of your background bitmap and the length of the text you're displaying, you may want to reposition the text and caption.

The PyPortal's display is 320 pixels wide and 240 pixels high. In order to refer to those positions on the screen, we use an x/y coordinate system, where x is horizontal and y is vertical.

The origin of this coordinate system is the upper left corner. This means that a pixel placed at the upper left corner would be (0,0) and the lower right corner would be (320, 240).

Text Color

Another way to customize your display is to adjust the color of the text. The line text_color=0xFFFFFF in the constructor shows how. You will need to use the hexadecimal value for any color you want to display.

You can use something like to pick your color and then copy the hex value, in this example it would be 0x0ED9EE

So, in order to customize the position and color of the text, you would adjust the values in these lines of code in

Download: file
days_position = (8, 207)
hours_position = (110, 207)
minutes_position = (220, 207)
text_color = 0xFFFFFF
This guide was first published on Jul 22, 2020. It was last updated on Jul 22, 2020.
This page (How It Works) was last updated on Oct 20, 2020.