User Guide

This document provides guide to using PieTime.

The application script

In order to use PieTime, you’ll have to write a simple Python script to set up and (optionally) start the application.

Short example

#!/usr/bin/env python2.7

from datetime import timedelta
import os
import sys

if os.getcwd() not in sys.path:
    sys.path.insert(0, os.getcwd())

from pie_time import PieTime
from import ClockCard, PictureCard, WeatherCard

deck = [
        WeatherCard, 20, {
            'api_key': 'Your OpenWeatherMap API KEY',
            'city': 'Wroclaw,PL'
        PictureCard, 10, {
            'urls': [

blanker_schedule = (
    timedelta(hours=23), timedelta(hours=6)

app = PieTime(deck, blanker_schedule=blanker_schedule)

if __name__ == '__main__':

This script sets up PieTime application with the following settings:

  • Three cards,
  • Clock card set up to display for 60 seconds,
  • Weather card set up to fetch data for the city of Wrocław in Poland and display for 20 seconds,
  • Picture frame card set to display two separate images (fetched from the Net) for 10 seconds each.
  • Blanker schedule set up to blank the screen between 23:00 (11:00 PM) and 6:00 AM,
  • Click to unblank interval set to 10 seconds.

The deck

The first argument passed to pie_time.PieTime constructor defines the deck of cards to be displayed, along with additional information about each of the cards.

Example deck could look like this:

deck = [
    (ClockCard, 30),
    (ClockCard, 30, {'text_color': (255, 0, 0)}),

The first item is just a card class. A card defined this way will display for the duration defined by pie_time.PieTime.CARD_INTERVAL and won’t have any additional settings.

The second item is a tuple of card class and number. A card defined this way will display for the specified number of seconds and won’t have any additional settings.

The third item is a tuple of card class, number and dictionary. A card defined this way will display for the specified number of seconds and will have additional settings as specified by the dictionary.

Blanker schedule

The blanker_schedule keyword argument defines how the screen should be blanked.

Example blanker schedule could look like this:

blanker_schedule = (
    datetime.timedelta(hours=23), datetime.timedelta(hours=6)

Such a schedule will make the application blank the screen between 23:00 (11:00 PM) and 6:00 AM.

When the blanker is active, the screen is filled with color defined in pie_time.PieTime.BLANK_COLOR.

Blanker also prevents the following actions:

  • Transitioning cards,
  • Calling the visible card’s tick() method,
  • Blitting the visible card’s surface to the screen.

When the blanker deactivates it transitions to the first card from the deck.

Click to unblank

A PieTime application can be set up to allow temporary overriding of the screen blanker. In order to do so, set click_to_unblank_interval to a non-negative number. When the screen is blanked, just click anywhere and PieTime will show for number of seconds defined by click_to_unblank_interval. Before unblanking, PieTime will set the first card from deck as the current card.

Since PieTime uses PyGame, it’ll automatically support many input devices. For example, a properly configured touch screen for PiTFT-like displays should be supported out of the box.

Click to transition

If you wish, you can change the currently visible card manually. In order to do so, just click (or tap) the bottom-left or bottom-right corner of the screen. The bottom-left corner will switch to the previous card. The bottom-right corner will switch to the next card.

This feature is enabled automatically and can be disabled by setting click_to_transition keyword argument to False.

Other settings

PieTime app allows changing other settings. Have a look at pie_time.PieTime class documentation to learn more.

Video drivers and screen size

Since PieTime is based on PyGame, it supports the same range ouf output devices. As of time of writing this document, PieTime has been tested with x11, fbcon and Quartz video drivers.

You can configure the outut device using SDL environment variables. See the SDL environment variables documentation to learn more.

Since PieTime mostly targets LCD shields, the screen size defaults to 320x240px. Support for other screen sizes is limited.

Testing the script

Once you’ve created the script to set up the application and chosen the video driver, you can start PieTime manually using the following command:

$ python2.7 <path_to_app_script>

In this case, video driver will be chosen automatically. If you get any errors, try using a different video driver. Note that framebuffer drivers usually require root privileges.

To exit the application, press [ESC].

NOTE: If you installed PieTime from the PyPI package or source code in a virtual env, make sure it’s properly activated before trying to start the application.

Creating and using the PieTime INI file

After you’ve tested your application script and are satisfied with it, it’s time to create the INI file. This INI file will be used by the pie_time program to set up and launch your application.

Short example

app_module = examples.customization_example:app
log_path = log.txt


The PieTime section

The PieTime section should contain the following fields:

  • app_module (string) - app module import path,
  • log_path (string) - optional path to log file (if omitted, standard output will be used).

The app module import path

The app_module field defines the app module import path. This import path will be used to import app script and extract the app object from it. In the example, the import path translates to app attribute in customization_example module in examples package. Note that the import path is related to the current working directory.

The SDL section

The SDL section allows you to set up SDL environment variables before starting the PieTime application. You can specify any environment variable supported by SDL. The field names should be specified without the SDL_ prefix, which will be added automatically.

Starting PieTime on boot

Since PieTime was designed as a desk clock replacement, it’s best to have it start automatically on boot. In order to do so, please follow instructions in one of the subsections.

Setting up PieTime installed from APT repository

If you installed PieTime from APT repository, follow the guide below to set it up to start on boot.

  1. Edit /etc/default/pie-time and adjust its contents according to your needs,
  2. Place the INI file in the path specified in the /etc/default/pie-time file,
  3. Place your application script in the path specified in the INI file,
  4. Run $ sudo dpkg-reconfigure pie-time and answer Yes when it asks you about starting on boot,
  5. Either reboot the Raspberry Pi or run $ sudo /etc/init.d/pie-time restart to start PieTime.

NOTE: You can skip the third step, if you replied Yes to the question when installing the PieTime package.

The /etc/default/pie-time file

The /etc/default/pie-time file contains minimum shell environment required to properly start the pie_time program.

Supported environment variables:

  • WORKDIR - path to working directory (which will be used to import the app module). Defaults to /var/lib/pie-time.
  • INI_PATH - path to the INI file. Defaults to /etc/pie-time.ini.
  • USER - name of the user which will start the app. Defaults to root.

NOTE: If you change the USER field to a non-root user, make sure it can acess the selected output device and paths (most notably, the log path).

Setting up PieTime installed from PyPI package or source code

If you chose to install PieTime from PyPI package or source code and wish to start it on boot, the recommended method is to use supervisor to achieve that.

Example supervisor config for PieTime

command=/usr/bin/python2.7 /home/pi/pie-time/


In case of any problems, it’s recommend to set the verbose keyword to argument to True and start the app again. In verbose mode, the app’s logger is set to DEBUG level (as opposed to INFO in non-verbose mode) and will display a lot of useful debugging information.