pie-time/docs/user_guide.rst

.. _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 <https://www.libsdl.org/release/SDL-1.2.15/docs/html/sdlenvvars.html>`_ 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 <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**

.. 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 <http://supervisord.org/>`_ 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.