user_guide.rst 9.3 KB

  1. .. _user_guide:
  2. User Guide
  3. ==========
  4. This document provides guide to using PieTime.
  5. The application script
  6. ----------------------
  7. In order to use PieTime, you'll have to write a simple Python script to set
  8. up and (optionally) start the application.
  9. **Short example**
  10. .. sourcecode:: python
  11. #!/usr/bin/env python2.7
  12. from datetime import timedelta
  13. import os
  14. import sys
  15. if os.getcwd() not in sys.path:
  16. sys.path.insert(0, os.getcwd())
  17. from pie_time import PieTime
  18. from import ClockCard, PictureCard, WeatherCard
  19. deck = [
  20. ClockCard,
  21. (
  22. WeatherCard, 20, {
  23. 'api_key': 'Your OpenWeatherMap API KEY',
  24. 'city': 'Wroclaw,PL'
  25. }
  26. ),
  27. (
  28. PictureCard, 10, {
  29. 'urls': [
  30. '',
  31. ''
  32. ]
  33. }
  34. )
  35. ]
  36. blanker_schedule = (
  37. timedelta(hours=23), timedelta(hours=6)
  38. )
  39. app = PieTime(deck, blanker_schedule=blanker_schedule)
  40. if __name__ == '__main__':
  42. This script sets up PieTime application with the following settings:
  43. * Three cards,
  44. * Clock card set up to display for 60 seconds,
  45. * Weather card set up to fetch data for the city of Wrocław in Poland and
  46. display for 20 seconds,
  47. * Picture frame card set to display two separate images (fetched from the Net)
  48. for 10 seconds each.
  49. * Blanker schedule set up to blank the screen between 23:00 (11:00 PM) and
  50. 6:00 AM,
  51. * Click to unblank interval set to 10 seconds.
  52. The deck
  53. --------
  54. The first argument passed to :py:class:`pie_time.PieTime` constructor defines
  55. the deck of cards to be displayed, along with additional information about
  56. each of the cards.
  57. Example deck could look like this:
  58. .. sourcecode:: python
  59. deck = [
  60. ClockCard,
  61. (ClockCard, 30),
  62. (ClockCard, 30, {'text_color': (255, 0, 0)}),
  63. ]
  64. The first item is just a card class. A card defined this way will display
  65. for the duration defined by :py:attr:`pie_time.PieTime.CARD_INTERVAL` and
  66. won't have any additional settings.
  67. The second item is a tuple of card class and number. A card defined this
  68. way will display for the specified number of seconds and won't have any
  69. additional settings.
  70. The third item is a tuple of card class, number and dictionary. A card
  71. defined this way will display for the specified number of seconds and will
  72. have additional settings as specified by the dictionary.
  73. Blanker schedule
  74. ----------------
  75. The *blanker_schedule* keyword argument defines how the screen should be
  76. blanked.
  77. Example blanker schedule could look like this:
  78. .. sourcecode:: python
  79. blanker_schedule = (
  80. datetime.timedelta(hours=23), datetime.timedelta(hours=6)
  81. )
  82. Such a schedule will make the application blank the screen between 23:00
  83. (11:00 PM) and 6:00 AM.
  84. When the blanker is active, the screen is filled with color defined in
  85. :py:attr:`pie_time.PieTime.BLANK_COLOR`.
  86. Blanker also prevents the following actions:
  87. * Transitioning cards,
  88. * Calling the visible card's ``tick()`` method,
  89. * Blitting the visible card's surface to the screen.
  90. When the blanker deactivates it transitions to the first card from the deck.
  91. Click to unblank
  92. ----------------
  93. A PieTime application can be set up to allow temporary overriding of the screen
  94. blanker. In order to do so, set *click_to_unblank_interval* to a non-negative
  95. number. When the screen is blanked, just click anywhere and PieTime will show
  96. for number of seconds defined by *click_to_unblank_interval*. Before
  97. unblanking, PieTime will set the first card from deck as the current card.
  98. Since PieTime uses PyGame, it'll automatically support many input devices. For
  99. example, a properly configured touch screen for PiTFT-like displays should be
  100. supported out of the box.
  101. Click to transition
  102. -------------------
  103. If you wish, you can change the currently visible card manually. In order to do
  104. so, just click (or tap) the bottom-left or bottom-right corner of the screen.
  105. The bottom-left corner will switch to the previous card. The bottom-right
  106. corner will switch to the next card.
  107. This feature is enabled automatically and can be disabled by setting
  108. *click_to_transition* keyword argument to ``False``.
  109. Other settings
  110. --------------
  111. PieTime app allows changing other settings. Have a look at
  112. :py:class:`pie_time.PieTime` class documentation to learn more.
  113. Video drivers and screen size
  114. -----------------------------
  115. Since PieTime is based on PyGame, it supports the same range ouf output
  116. devices. As of time of writing this document, PieTime has been tested with
  117. ``x11``, ``fbcon`` and ``Quartz`` video drivers.
  118. You can configure the outut device using SDL environment variables. See the
  119. `SDL environment variables documentation <>`_ to learn more.
  120. Since PieTime mostly targets LCD shields, the screen size defaults to
  121. 320x240px. Support for other screen sizes is limited.
  122. Testing the script
  123. ------------------
  124. Once you've created the script to set up the application and chosen the video
  125. driver, you can start PieTime manually using the following command:
  126. .. sourcecode:: console
  127. $ python2.7 <path_to_app_script>
  128. In this case, video driver will be chosen automatically. If you get any
  129. errors, try using a different video driver. Note that framebuffer drivers
  130. usually require root privileges.
  131. To exit the application, press *[ESC]*.
  132. **NOTE**: If you installed PieTime from the PyPI package or source code in a
  133. virtual env, make sure it's properly activated before trying to start the
  134. application.
  135. Creating and using the PieTime INI file
  136. ---------------------------------------
  137. After you've tested your application script and are satisfied with it, it's
  138. time to create the INI file. This INI file will be used by the *pie_time*
  139. program to set up and launch your application.
  140. **Short example**
  141. .. sourcecode:: ini
  142. [PieTime]
  143. app_module = examples.customization_example:app
  144. log_path = log.txt
  145. [SDL]
  146. VIDEODRIVER = fbcon
  147. **The PieTime section**
  148. The *PieTime* section should contain the following fields:
  149. * ``app_module`` (string) - app module import path,
  150. * ``log_path`` (string) - optional path to log file (if omitted, standard
  151. output will be used).
  152. **The app module import path**
  153. The *app_module* field defines the app module import path. This import path
  154. will be used to import app script and extract the app object from it. In the
  155. example, the import path translates to *app attribute in customization_example
  156. module in examples package*. Note that the import path is related to the
  157. current working directory.
  158. **The SDL section**
  159. The SDL section allows you to set up SDL environment variables before starting
  160. the PieTime application. You can specify any environment variable supported by
  161. SDL. The field names should be specified without the ``SDL_`` prefix, which
  162. will be added automatically.
  163. Starting PieTime on boot
  164. ------------------------
  165. Since PieTime was designed as a desk clock replacement, it's best to have it
  166. start automatically on boot. In order to do so, please follow instructions in
  167. one of the subsections.
  168. **Setting up PieTime installed from APT repository**
  169. If you installed PieTime from APT repository, follow the guide below to set it
  170. up to start on boot.
  171. #. Edit ``/etc/default/pie-time`` and adjust its contents according to your
  172. needs,
  173. #. Place the INI file in the path specified in the ``/etc/default/pie-time``
  174. file,
  175. #. Place your application script in the path specified in the INI file,
  176. #. Run ``$ sudo dpkg-reconfigure pie-time`` and answer *Yes* when it asks you
  177. about starting on boot,
  178. #. Either reboot the Raspberry Pi or run
  179. ``$ sudo /etc/init.d/pie-time restart`` to start PieTime.
  180. **NOTE**: You can skip the third step, if you replied *Yes* to the question
  181. when installing the PieTime package.
  182. **The /etc/default/pie-time file**
  183. The ``/etc/default/pie-time`` file contains minimum shell environment required
  184. to properly start the *pie_time* program.
  185. Supported environment variables:
  186. * ``WORKDIR`` - path to working directory (which will be used to import the app
  187. module). Defaults to ``/var/lib/pie-time``.
  188. * ``INI_PATH`` - path to the INI file. Defaults to ``/etc/pie-time.ini``.
  189. * ``USER`` - name of the user which will start the app. Defaults to ``root``.
  190. **NOTE**: If you change the ``USER`` field to a non-root user, make sure it can
  191. acess the selected output device and paths (most notably, the log path).
  192. **Setting up PieTime installed from PyPI package or source code**
  193. If you chose to install PieTime from PyPI package or source code and wish to
  194. start it on boot, the recommended method is to use
  195. `supervisor <>`_ to achieve that.
  196. **Example supervisor config for PieTime**
  197. .. sourcecode:: text
  198. [program:pie_time]
  199. command=/usr/bin/python2.7 /home/pi/pie-time/
  200. numprocs=1
  201. directory=/home/pi/pie-time
  202. autostart=true
  203. user=root
  204. stdout_logfile=/home/pi/pie-time/log/stdout.log
  205. stderr_logfile=/home/pi/pie-time/log/stderr.log
  206. Troubleshooting
  207. ---------------
  208. In case of any problems, it's recommend to set the *verbose* keyword to
  209. argument to ``True`` and start the app again. In verbose mode, the app's logger
  210. is set to ``DEBUG`` level (as opposed to ``INFO`` in non-verbose mode) and will
  211. display a lot of useful debugging information.