.. _user_guide: 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** .. sourcecode:: python #!/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 pie_time.cards import ClockCard, PictureCard, WeatherCard deck = [ ClockCard, ( WeatherCard, 20, { 'api_key': 'Your OpenWeatherMap API KEY', 'city': 'Wroclaw,PL' } ), ( PictureCard, 10, { 'urls': [ 'http://lorempixel.com/320/240/city', 'http://lorempixel.com/200/125/technics' ] } ) ] blanker_schedule = ( timedelta(hours=23), timedelta(hours=6) ) app = PieTime(deck, blanker_schedule=blanker_schedule) if __name__ == '__main__': app.run() 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 :py:class:`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: .. sourcecode:: python deck = [ ClockCard, (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 :py:attr:`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: .. sourcecode:: python 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 :py:attr:`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 :py:class:`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: .. sourcecode:: console $ python2.7 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** .. sourcecode:: ini [PieTime] app_module = examples.customization_example:app log_path = log.txt [SDL] VIDEODRIVER = fbcon **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. #. Edit ``/etc/default/pie-time`` and adjust its contents according to your needs, #. Place the INI file in the path specified in the ``/etc/default/pie-time`` file, #. Place your application script in the path specified in the INI file, #. Run ``$ sudo dpkg-reconfigure pie-time`` and answer *Yes* when it asks you about starting on boot, #. 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** .. sourcecode:: text [program:pie_time] command=/usr/bin/python2.7 /home/pi/pie-time/app.py numprocs=1 directory=/home/pi/pie-time autostart=true user=root stdout_logfile=/home/pi/pie-time/log/stdout.log stderr_logfile=/home/pi/pie-time/log/stderr.log Troubleshooting --------------- 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.