You've already forked pie-time
Initial public release of PieTime!
\o/
This commit is contained in:
295
docs/user_guide.rst
Normal file
295
docs/user_guide.rst
Normal file
@@ -0,0 +1,295 @@
|
||||
.. _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.
|
||||
Reference in New Issue
Block a user