developer_guide.rst 4.1 KB

  1. Developer Guide
  2. ===============
  3. This document provides guide to hacking and extending PieTime.
  4. Setup
  5. -----
  6. To develop PieTime or cards, some additional setup is required. First, it's
  7. recommended to use a virtual environment, to separate from OS Python and
  8. extensions. Secondly, use ``requirements-dev.txt`` to install additional
  9. modules and tools used in development.
  10. Custom card example
  11. -------------------
  12. .. sourcecode:: python
  13. from pie_time.card import AbstractCard
  14. import pygame
  15. class ExampleCard(AbstractCard):
  16. def initialize(self):
  17. self.sprite = pygame.surface.Surface((20, 20))
  18. self.sprite.fill((255, 0, 0))
  19. self.orig_sprite_rect = self.sprite.get_rect()
  20. self.orig_speed = [2, 2]
  21. self.sprite_rect = self.orig_sprite_rect
  22. self.speed = self.orig_speed
  23. def show(self):
  24. self.sprite_rect = self.orig_sprite_rect
  25. self.speed = self.orig_speed
  26. def tick(self):
  27. self.sprite_rect = self.sprite_rect.move(self.speed)
  28. if self.sprite_rect.left < 0 or self.sprite_rect.right > self.width:
  29. self.speed[0] = -self.speed[0]
  30. if < 0 or self.sprite_rect.bottom > self.height:
  31. self.speed[1] = -self.speed[1]
  32. self.surface.fill(self.background_color)
  33. self.surface.blit(self.sprite, self.sprite_rect)
  34. This example shows how easy it is to create custom cards for use in PieTime
  35. decks.
  36. Start by creating a custom class that inherits from *AbstractCard*. Then
  37. implement a few methods to make it display the information you need (in this
  38. example, a red square moving on the screen). Having done that, you'll be ready to use your custom card in a deck.
  39. Head on to :py:class:`pie_time.AbstractCard` documentation for more
  40. information about PieTime card API.
  41. Speed considerations
  42. --------------------
  43. Since PieTime targets the Raspberry Pi, it's important to keep speed in mind.
  44. When developing cards, take care to do as little work as possible in the
  45. :py:meth:`pie_time.AbstractCard.tick` method.
  46. For example, WeatherCard redraws its surface only when weather conditions
  47. change. By doing so, the CPU load is reduced because the only thing PieTime has to do is blit the surface to screen.
  48. Always test the behavior of your card in low FPS. Remember, that PieTime
  49. targets small GPIO-connected LCD screens. For many of them, 20 FPS will be the best refresh rate. If your card behaves badly in such conditions, users may refrain from using it.
  50. Threading considerations
  51. ------------------------
  52. Sometimes, it's required to perform background tasks during lifetime of the
  53. card. API exposed by Python's builtin ``threading`` module should come in handy
  54. is such situations.
  55. Take WeatherCard as an example. Once every 10 minutes, it fetches current
  56. conditions from the Internet. If you look into the card's code, there's
  57. ``_refresh_conditions`` method. It uses ``threading.Timer`` class to schedule
  58. fetching of the conditions in a separate thread of control. This way, the
  59. HTTP request (which may take some time depending on the network conditions)
  60. won't cause the PieTime application to freeze.
  61. As always with threads, you should be aware of the standard pitfalls - variable
  62. access synchronization, error handling, the GIL. Also, spawning too many
  63. threads will impact PieTime's performance. If you use threads in your card,
  64. make sure to test it on the device to see how it impacts the load.
  65. Handling events
  66. ---------------
  67. In every iteration of the main loop, PieTime reads list of current events from
  68. PyGame. This list is available for the cards to use through
  69. :py:attr:``.
  70. The application itself handles the following events:
  71. * ``QUIT`` (e.g. SIGTERM) - if this event appears, the application quits.
  72. * ``KEYDOWN`` on the key specified by :py:attr:`pie_time.PieTime.KEY_QUIT` -
  73. quits the application,
  74. * ``MOUSEBUTTONDOWN`` anywhere on the screen when it's blanked -
  75. if click to unblank is enabled,
  76. * ``MOUSEBUTTONDOWN`` in one of the regions used to manually switch bedween
  77. cards.