diff options
| -rw-r--r-- | docs/wasp.rst | 53 | ||||
| -rw-r--r-- | wasp/apps/clock.py | 8 | ||||
| -rw-r--r-- | wasp/apps/flashlight.py | 11 | ||||
| -rw-r--r-- | wasp/apps/launcher.py | 4 | ||||
| -rw-r--r-- | wasp/apps/pager.py | 21 | ||||
| -rw-r--r-- | wasp/apps/testapp.py | 4 | ||||
| -rw-r--r-- | wasp/wasp.py | 15 | ||||
| -rw-r--r-- | wasp/widgets.py | 28 |
8 files changed, 92 insertions, 52 deletions
diff --git a/docs/wasp.rst b/docs/wasp.rst index 87dd301..36be6d6 100644 --- a/docs/wasp.rst +++ b/docs/wasp.rst @@ -6,35 +6,32 @@ WASP Reference Manual .. contents:: :local: -System management ------------------ +System +------ .. automodule:: wasp :members: - :undoc-members: -Applications ------------- +.. automodule:: draw565 + :members: -.. automodule:: apps.clock +.. automodule:: icons :members: :undoc-members: -.. automodule:: apps.flashlight +.. automodule:: fonts.clock :members: :undoc-members: -.. automodule:: apps.launcher +.. automodule:: fonts.sans24 :members: - :undoc-members: -.. automodule:: apps.pager +.. automodule:: logo :members: :undoc-members: -.. automodule:: apps.testapp +.. automodule:: widgets :members: - :undoc-members: Device drivers -------------- @@ -57,28 +54,26 @@ Device drivers .. automodule:: drivers.vibrator :members: -Libraries ---------- - -.. automodule:: draw565 - :members: +Applications +------------ -.. automodule:: icons +.. automodule:: apps.clock :members: :undoc-members: -.. automodule:: fonts.clock +.. automodule:: apps.flashlight :members: :undoc-members: -.. automodule:: fonts.sans24 +.. automodule:: apps.launcher :members: + :undoc-members: -.. automodule:: logo +.. automodule:: apps.pager :members: :undoc-members: -.. automodule:: widgets +.. automodule:: apps.testapp :members: :undoc-members: @@ -139,8 +134,8 @@ active (during splash screen or early UART recovery mode, during an update). It can be consumed by the application to prevent the current time being lost during an update. -Watchdog --------- +Watchdog protocol +~~~~~~~~~~~~~~~~~ Form-factor devices such as smart watches and fitness trackers do not usually have any hardware mechanism to allow the user to force a failed device into @@ -156,9 +151,6 @@ The software responsibilities to implement this are split between the bootloader and the application, although the application responsibilities are intentionally minimal. -Bootloader -~~~~~~~~~~ - The bootloader implements an over-the-air recovery mode, as well as handling normal boot, where it's role is to display the splash screen. @@ -183,14 +175,9 @@ From this list #1 and #2 are needed to ensure robust WDT handling whilst #3 and # 4 ensure the user can switch back to application from the device itself if they ever accidentally trigger entry to recovery mode. -Application -~~~~~~~~~~~ - The application's role is to carefully pet the watchdog so that it will trigger automatically if the hardware button is held down for five -seconds. - -Key points for robustness: +seconds. Key points for application robustness include: 1. Unlike a normal watchdog we can be fairly reckless about where in the code we pet the dog. For example petting the dog from a timer interrupt diff --git a/wasp/apps/clock.py b/wasp/apps/clock.py index 4236d9a..f09f2d4 100644 --- a/wasp/apps/clock.py +++ b/wasp/apps/clock.py @@ -1,6 +1,12 @@ # SPDX-License-Identifier: LGPL-3.0-or-later # Copyright (C) 2020 Daniel Thompson +"""Digital clock +~~~~~~~~~~~~~~~~ + +Shows a time (as HH:MM) together with a battery meter and the date. +""" + import wasp import icons @@ -23,8 +29,6 @@ MONTH = 'JanFebMarAprMayJunJulAugSepOctNovDec' class ClockApp(): """Simple digital clock application. - - Shows a time (as HH:MM) together with a battery meter and the date. """ NAME = 'Clock' ICON = icons.clock diff --git a/wasp/apps/flashlight.py b/wasp/apps/flashlight.py index c4702a0..5ca9734 100644 --- a/wasp/apps/flashlight.py +++ b/wasp/apps/flashlight.py @@ -1,15 +1,18 @@ # SPDX-License-Identifier: LGPL-3.0-or-later # Copyright (C) 2020 Daniel Thompson +"""Flashlight +~~~~~~~~~~~~~ + +Shows a pure white screen with the backlight set to maximum. +""" + import wasp import icons class FlashlightApp(object): - """Trivial flashlight application. - - Shows a pure white screen with the backlight set to maximum. - """ + """Trivial flashlight application.""" NAME = 'Torch' ICON = icons.torch diff --git a/wasp/apps/launcher.py b/wasp/apps/launcher.py index 305cc2e..6a8bab7 100644 --- a/wasp/apps/launcher.py +++ b/wasp/apps/launcher.py @@ -1,6 +1,10 @@ # SPDX-License-Identifier: LGPL-3.0-or-later # Copyright (C) 2020 Daniel Thompson +"""Application launcher +~~~~~~~~~~~~~~~~~~~~~~~ +""" + import wasp import icons diff --git a/wasp/apps/pager.py b/wasp/apps/pager.py index 7da8f5a..18322d2 100644 --- a/wasp/apps/pager.py +++ b/wasp/apps/pager.py @@ -1,20 +1,22 @@ # SPDX-License-Identifier: LGPL-3.0-or-later # Copyright (C) 2020 Daniel Thompson +"""Pager applications +~~~~~~~~~~~~~~~~~~~~~ + +The pager is used to present text based information to the user. It is +primarily intended for notifications but is also used to provide debugging +information when applications crash. +""" + import wasp import icons import io import sys - class PagerApp(): - """Show long text in a pager. - - This is used to present text based information to the user. It is primarily - intended for notifications but is also used to provide debugging - information when applications crash. - """ + """Show a long text message in a pager.""" NAME = 'Pager' ICON = icons.app @@ -31,10 +33,12 @@ class PagerApp(): self._draw() def background(self): + """De-activate the application.""" del self._chunks del self._numpages def swipe(self, event): + """Swipe to page up/down.""" mute = wasp.watch.display.mute if event[0] == wasp.EventType.UP: @@ -114,6 +118,5 @@ class CrashApp(): wasp.watch.display.invert(True) def swipe(self, event): - """Show the exception message in a pager. - """ + """Show the exception message in a pager.""" wasp.system.switch(PagerApp(self._msg)) diff --git a/wasp/apps/testapp.py b/wasp/apps/testapp.py index 4b64d31..6681aa5 100644 --- a/wasp/apps/testapp.py +++ b/wasp/apps/testapp.py @@ -1,6 +1,10 @@ # SPDX-License-Identifier: LGPL-3.0-or-later # Copyright (C) 2020 Daniel Thompson +"""Self Tests +~~~~~~~~~~~~~ +""" + import machine import wasp import icons diff --git a/wasp/wasp.py b/wasp/wasp.py index a92ceed..f8648e4 100644 --- a/wasp/wasp.py +++ b/wasp/wasp.py @@ -1,11 +1,18 @@ # SPDX-License-Identifier: LGPL-3.0-or-later # Copyright (C) 2020 Daniel Thompson -"""WASP system management (including constants) +"""Wasp-os system manager +~~~~~~~~~~~~~~~~~~~~~~~~~ -.. data:: system = Manager() +.. data:: wasp.system - system is the system-wide instance of the Manager class. Applications - can use this instance to access system services. + wasp.system is the system-wide singleton instance of :py:class:`.Manager`. + Application must use this instance to access the system services provided + by the manager. + +.. data:: wasp.watch + + wasp.watch is an import of :py:mod:`watch` and is simply provided as a + shortcut (and to reduce memory by keeping it out of other namespaces). """ import gc diff --git a/wasp/widgets.py b/wasp/widgets.py index 9aa39a0..9271fe6 100644 --- a/wasp/widgets.py +++ b/wasp/widgets.py @@ -1,18 +1,35 @@ # SPDX-License-Identifier: LGPL-3.0-or-later # Copyright (C) 2020 Daniel Thompson +"""Widget library +~~~~~~~~~~~~~~~~~ + +The widget library allows common fragments of logic and drawing code to be +shared between applications. +""" + import icons import watch class BatteryMeter(object): + """Battery meter widget. + + A simple battery meter with a charging indicator, will draw at the + top-right of the display. + """ def __init__(self): self.level = -2 def draw(self): + """Draw from meter (from scratch).""" self.level = -2 self.update() def update(self): + """Update the meter. + + The update is lazy and won't redraw unless the level has changed. + """ icon = icons.battery draw = watch.drawable @@ -52,15 +69,26 @@ class BatteryMeter(object): self.level = level class ScrollIndicator(): + """Scrolling indicator. + + A simple battery meter with a charging indicator, will draw at the + top-right of the display. + """ def __init__(self, x=240-18, y=240-24): self._pos = (x, y) self.up = True self.down = True def draw(self): + """Draw from scrolling indicator. + + For this simple widget :py:meth:`~.draw` is simply a synonym for + :py:meth:`~.update`. + """ self.update() def update(self): + """Update from scrolling indicator.""" draw = watch.drawable if self.up: draw.rleblit(icons.up_arrow, pos=self._pos, fg=0x7bef) |