296 lines
9.3 KiB
ReStructuredText
296 lines
9.3 KiB
ReStructuredText
.. _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.
|