wasp: Even more docstrings
This commit is contained in:
parent
f07fb6d22a
commit
b8efcd3053
8 changed files with 96 additions and 56 deletions
|
@ -6,35 +6,32 @@ WASP Reference Manual
|
||||||
.. contents::
|
.. contents::
|
||||||
:local:
|
:local:
|
||||||
|
|
||||||
System management
|
System
|
||||||
-----------------
|
------
|
||||||
|
|
||||||
.. automodule:: wasp
|
.. automodule:: wasp
|
||||||
:members:
|
:members:
|
||||||
:undoc-members:
|
|
||||||
|
|
||||||
Applications
|
.. automodule:: draw565
|
||||||
------------
|
:members:
|
||||||
|
|
||||||
.. automodule:: apps.clock
|
.. automodule:: icons
|
||||||
:members:
|
:members:
|
||||||
:undoc-members:
|
:undoc-members:
|
||||||
|
|
||||||
.. automodule:: apps.flashlight
|
.. automodule:: fonts.clock
|
||||||
:members:
|
:members:
|
||||||
:undoc-members:
|
:undoc-members:
|
||||||
|
|
||||||
.. automodule:: apps.launcher
|
.. automodule:: fonts.sans24
|
||||||
|
:members:
|
||||||
|
|
||||||
|
.. automodule:: logo
|
||||||
:members:
|
:members:
|
||||||
:undoc-members:
|
:undoc-members:
|
||||||
|
|
||||||
.. automodule:: apps.pager
|
.. automodule:: widgets
|
||||||
:members:
|
:members:
|
||||||
:undoc-members:
|
|
||||||
|
|
||||||
.. automodule:: apps.testapp
|
|
||||||
:members:
|
|
||||||
:undoc-members:
|
|
||||||
|
|
||||||
Device drivers
|
Device drivers
|
||||||
--------------
|
--------------
|
||||||
|
@ -57,28 +54,26 @@ Device drivers
|
||||||
.. automodule:: drivers.vibrator
|
.. automodule:: drivers.vibrator
|
||||||
:members:
|
:members:
|
||||||
|
|
||||||
Libraries
|
Applications
|
||||||
---------
|
------------
|
||||||
|
|
||||||
.. automodule:: draw565
|
.. automodule:: apps.clock
|
||||||
:members:
|
|
||||||
|
|
||||||
.. automodule:: icons
|
|
||||||
:members:
|
:members:
|
||||||
:undoc-members:
|
:undoc-members:
|
||||||
|
|
||||||
.. automodule:: fonts.clock
|
.. automodule:: apps.flashlight
|
||||||
:members:
|
:members:
|
||||||
:undoc-members:
|
:undoc-members:
|
||||||
|
|
||||||
.. automodule:: fonts.sans24
|
.. automodule:: apps.launcher
|
||||||
:members:
|
|
||||||
|
|
||||||
.. automodule:: logo
|
|
||||||
:members:
|
:members:
|
||||||
:undoc-members:
|
:undoc-members:
|
||||||
|
|
||||||
.. automodule:: widgets
|
.. automodule:: apps.pager
|
||||||
|
:members:
|
||||||
|
:undoc-members:
|
||||||
|
|
||||||
|
.. automodule:: apps.testapp
|
||||||
:members:
|
:members:
|
||||||
:undoc-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
|
update). It can be consumed by the application to prevent the current
|
||||||
time being lost during an update.
|
time being lost during an update.
|
||||||
|
|
||||||
Watchdog
|
Watchdog protocol
|
||||||
--------
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Form-factor devices such as smart watches and fitness trackers do not usually
|
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
|
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
|
bootloader and the application, although the application responsibilities
|
||||||
are intentionally minimal.
|
are intentionally minimal.
|
||||||
|
|
||||||
Bootloader
|
|
||||||
~~~~~~~~~~
|
|
||||||
|
|
||||||
The bootloader implements an over-the-air recovery mode, as well as handling
|
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.
|
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
|
and # 4 ensure the user can switch back to application from the device
|
||||||
itself if they ever accidentally trigger entry to recovery mode.
|
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
|
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
|
trigger automatically if the hardware button is held down for five
|
||||||
seconds.
|
seconds. Key points for application robustness include:
|
||||||
|
|
||||||
Key points for robustness:
|
|
||||||
|
|
||||||
1. Unlike a normal watchdog we can be fairly reckless about where in the
|
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
|
code we pet the dog. For example petting the dog from a timer interrupt
|
||||||
|
|
|
@ -1,6 +1,12 @@
|
||||||
# SPDX-License-Identifier: LGPL-3.0-or-later
|
# SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
# Copyright (C) 2020 Daniel Thompson
|
# Copyright (C) 2020 Daniel Thompson
|
||||||
|
|
||||||
|
"""Digital clock
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Shows a time (as HH:MM) together with a battery meter and the date.
|
||||||
|
"""
|
||||||
|
|
||||||
import wasp
|
import wasp
|
||||||
|
|
||||||
import icons
|
import icons
|
||||||
|
@ -23,8 +29,6 @@ MONTH = 'JanFebMarAprMayJunJulAugSepOctNovDec'
|
||||||
|
|
||||||
class ClockApp():
|
class ClockApp():
|
||||||
"""Simple digital clock application.
|
"""Simple digital clock application.
|
||||||
|
|
||||||
Shows a time (as HH:MM) together with a battery meter and the date.
|
|
||||||
"""
|
"""
|
||||||
NAME = 'Clock'
|
NAME = 'Clock'
|
||||||
ICON = icons.clock
|
ICON = icons.clock
|
||||||
|
|
|
@ -1,15 +1,18 @@
|
||||||
# SPDX-License-Identifier: LGPL-3.0-or-later
|
# SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
# Copyright (C) 2020 Daniel Thompson
|
# Copyright (C) 2020 Daniel Thompson
|
||||||
|
|
||||||
|
"""Flashlight
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Shows a pure white screen with the backlight set to maximum.
|
||||||
|
"""
|
||||||
|
|
||||||
import wasp
|
import wasp
|
||||||
|
|
||||||
import icons
|
import icons
|
||||||
|
|
||||||
class FlashlightApp(object):
|
class FlashlightApp(object):
|
||||||
"""Trivial flashlight application.
|
"""Trivial flashlight application."""
|
||||||
|
|
||||||
Shows a pure white screen with the backlight set to maximum.
|
|
||||||
"""
|
|
||||||
NAME = 'Torch'
|
NAME = 'Torch'
|
||||||
ICON = icons.torch
|
ICON = icons.torch
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,10 @@
|
||||||
# SPDX-License-Identifier: LGPL-3.0-or-later
|
# SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
# Copyright (C) 2020 Daniel Thompson
|
# Copyright (C) 2020 Daniel Thompson
|
||||||
|
|
||||||
|
"""Application launcher
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
"""
|
||||||
|
|
||||||
import wasp
|
import wasp
|
||||||
import icons
|
import icons
|
||||||
|
|
||||||
|
|
|
@ -1,20 +1,22 @@
|
||||||
# SPDX-License-Identifier: LGPL-3.0-or-later
|
# SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
# Copyright (C) 2020 Daniel Thompson
|
# 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 wasp
|
||||||
import icons
|
import icons
|
||||||
|
|
||||||
import io
|
import io
|
||||||
import sys
|
import sys
|
||||||
|
|
||||||
|
|
||||||
class PagerApp():
|
class PagerApp():
|
||||||
"""Show long text in a pager.
|
"""Show a long text message 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.
|
|
||||||
"""
|
|
||||||
NAME = 'Pager'
|
NAME = 'Pager'
|
||||||
ICON = icons.app
|
ICON = icons.app
|
||||||
|
|
||||||
|
@ -31,10 +33,12 @@ class PagerApp():
|
||||||
self._draw()
|
self._draw()
|
||||||
|
|
||||||
def background(self):
|
def background(self):
|
||||||
|
"""De-activate the application."""
|
||||||
del self._chunks
|
del self._chunks
|
||||||
del self._numpages
|
del self._numpages
|
||||||
|
|
||||||
def swipe(self, event):
|
def swipe(self, event):
|
||||||
|
"""Swipe to page up/down."""
|
||||||
mute = wasp.watch.display.mute
|
mute = wasp.watch.display.mute
|
||||||
|
|
||||||
if event[0] == wasp.EventType.UP:
|
if event[0] == wasp.EventType.UP:
|
||||||
|
@ -114,6 +118,5 @@ class CrashApp():
|
||||||
wasp.watch.display.invert(True)
|
wasp.watch.display.invert(True)
|
||||||
|
|
||||||
def swipe(self, event):
|
def swipe(self, event):
|
||||||
"""Show the exception message in a pager.
|
"""Show the exception message in a pager."""
|
||||||
"""
|
|
||||||
wasp.system.switch(PagerApp(self._msg))
|
wasp.system.switch(PagerApp(self._msg))
|
||||||
|
|
|
@ -1,6 +1,10 @@
|
||||||
# SPDX-License-Identifier: LGPL-3.0-or-later
|
# SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
# Copyright (C) 2020 Daniel Thompson
|
# Copyright (C) 2020 Daniel Thompson
|
||||||
|
|
||||||
|
"""Self Tests
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
"""
|
||||||
|
|
||||||
import machine
|
import machine
|
||||||
import wasp
|
import wasp
|
||||||
import icons
|
import icons
|
||||||
|
|
15
wasp/wasp.py
15
wasp/wasp.py
|
@ -1,11 +1,18 @@
|
||||||
# SPDX-License-Identifier: LGPL-3.0-or-later
|
# SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
# Copyright (C) 2020 Daniel Thompson
|
# 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
|
wasp.system is the system-wide singleton instance of :py:class:`.Manager`.
|
||||||
can use this instance to access system services.
|
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
|
import gc
|
||||||
|
|
|
@ -1,18 +1,35 @@
|
||||||
# SPDX-License-Identifier: LGPL-3.0-or-later
|
# SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
# Copyright (C) 2020 Daniel Thompson
|
# 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 icons
|
||||||
import watch
|
import watch
|
||||||
|
|
||||||
class BatteryMeter(object):
|
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):
|
def __init__(self):
|
||||||
self.level = -2
|
self.level = -2
|
||||||
|
|
||||||
def draw(self):
|
def draw(self):
|
||||||
|
"""Draw from meter (from scratch)."""
|
||||||
self.level = -2
|
self.level = -2
|
||||||
self.update()
|
self.update()
|
||||||
|
|
||||||
def update(self):
|
def update(self):
|
||||||
|
"""Update the meter.
|
||||||
|
|
||||||
|
The update is lazy and won't redraw unless the level has changed.
|
||||||
|
"""
|
||||||
icon = icons.battery
|
icon = icons.battery
|
||||||
draw = watch.drawable
|
draw = watch.drawable
|
||||||
|
|
||||||
|
@ -52,15 +69,26 @@ class BatteryMeter(object):
|
||||||
self.level = level
|
self.level = level
|
||||||
|
|
||||||
class ScrollIndicator():
|
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):
|
def __init__(self, x=240-18, y=240-24):
|
||||||
self._pos = (x, y)
|
self._pos = (x, y)
|
||||||
self.up = True
|
self.up = True
|
||||||
self.down = True
|
self.down = True
|
||||||
|
|
||||||
def draw(self):
|
def draw(self):
|
||||||
|
"""Draw from scrolling indicator.
|
||||||
|
|
||||||
|
For this simple widget :py:meth:`~.draw` is simply a synonym for
|
||||||
|
:py:meth:`~.update`.
|
||||||
|
"""
|
||||||
self.update()
|
self.update()
|
||||||
|
|
||||||
def update(self):
|
def update(self):
|
||||||
|
"""Update from scrolling indicator."""
|
||||||
draw = watch.drawable
|
draw = watch.drawable
|
||||||
if self.up:
|
if self.up:
|
||||||
draw.rleblit(icons.up_arrow, pos=self._pos, fg=0x7bef)
|
draw.rleblit(icons.up_arrow, pos=self._pos, fg=0x7bef)
|
||||||
|
|
Loading…
Reference in a new issue