docs: Wordsmtithing updates after review
Signed-off-by: Daniel Thompson <daniel@redfelineninja.org.uk>
This commit is contained in:
parent
6f0238415f
commit
748e5fe65a
8 changed files with 188 additions and 149 deletions
35
README.rst
35
README.rst
|
@ -4,19 +4,18 @@ Watch Application System in Python
|
|||
Introduction
|
||||
------------
|
||||
|
||||
Although still in its infancy wasp-os provides many example applications
|
||||
including a simple digital clock, a stopwatch, a step counter and a heart rate
|
||||
monitor. All of these, together with access to the MicroPython REPL for
|
||||
interactive tweaking and testing, are running on `PineTime
|
||||
<https://www.pine64.org/pinetime/>`_. It keeps time well and has enough power
|
||||
saving functions implemented that it can survive for well over 72 hours between
|
||||
charges so even at this early stage it is functional as a wearable timepiece.
|
||||
Wasp-os is a firmware for smart watches that are based on the nRF52
|
||||
family of microcontrollers, including hacker friendly watches such
|
||||
as the Pine64 PineTime. Wasp-os includes a digital clock, a stopwatch,
|
||||
a step counter and a heart rate monitor. All of these, together with
|
||||
access to the MicroPython REPL for interactive tweaking, development
|
||||
and testing.
|
||||
|
||||
Wasp-os includes a robust bootloader based on the Adafruit NRF52
|
||||
Bootloader. It has been extended to make it robust for development on
|
||||
form-factor devices without a reset button, power switch, SWD debugger
|
||||
or UART. This allows us to confidently develop on sealed devices relying
|
||||
only on BLE for updates.
|
||||
on Bluetooth Low Energy for over-the-air updates.
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
@ -29,19 +28,19 @@ get started coding for wasp-os as quickly as possible.
|
|||
Getting Started
|
||||
---------------
|
||||
|
||||
Wasp-os can be installed without using any tools onto the following
|
||||
devices:
|
||||
Wasp-os can be installed without using any tools or disassembly onto the
|
||||
following devices:
|
||||
|
||||
* Pine64 PineTime (developer edition)
|
||||
* Pine64 PineTime
|
||||
* Colmi P8
|
||||
* Senbono K9
|
||||
|
||||
The
|
||||
Use the
|
||||
`Installation Guide <https://wasp-os.readthedocs.io/en/latest/install.html>`_
|
||||
contains detailed instructions on how to build and install wasp-os.
|
||||
to learn how to build and install wasp-os on these devices.
|
||||
|
||||
At the end of the install process your watch will show the time (03:00)
|
||||
together with a date and battery meter. When the watch goes into power
|
||||
together with a date and a battery meter. When the watch goes into power
|
||||
saving mode you can use the button to wake it again.
|
||||
|
||||
At this point you will also be able to use the Nordic UART Service to
|
||||
|
@ -56,7 +55,7 @@ To set the time and restart the main application:
|
|||
watch.rtc.set_localtime((yyyy, mm, dd, HH, MM, SS))
|
||||
wasp.system.run()
|
||||
|
||||
Or just use:
|
||||
Or, if you have a suitable GNU/Linux workstation, just use:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
|
@ -103,10 +102,12 @@ Videos
|
|||
Screenshots
|
||||
-----------
|
||||
|
||||
(An older version of) the digital clock application running on a Pine64 PineTime:
|
||||
(An older version of) the digital clock application running on a Pine64
|
||||
PineTime:
|
||||
|
||||
.. image:: res/clock_app.jpg
|
||||
:alt: wasp-os digital clock app running on PineTime
|
||||
:width: 233
|
||||
|
||||
Screenshots of the built in applications running on the wasp-os
|
||||
simulator (the "blank" screen is the torch application):
|
||||
|
@ -163,6 +164,6 @@ using one of the techniques is the Application Writer's guide.
|
|||
:alt: Game of Life running in the wasp-os simulator
|
||||
:width: 179
|
||||
|
||||
.. image:: res/MusicPlayerApp.png
|
||||
.. image:: res/MusicApp.png
|
||||
:alt: Music Player running in the wasp-os simulator
|
||||
:width: 179
|
||||
|
|
4
TODO.rst
4
TODO.rst
|
@ -11,9 +11,7 @@ Roadmap
|
|||
--------------------------------
|
||||
|
||||
For 0.4 we focus on improving the watch/phone integration whilst also taking steps
|
||||
to improve the general fit and finish. In addition the reloader will be extended
|
||||
to ensure we retain the capability to install wasp-os over-the-air on newer
|
||||
PineTime models.
|
||||
to improve the general fit and finish.
|
||||
|
||||
Bootloader
|
||||
~~~~~~~~~~
|
||||
|
|
|
@ -14,7 +14,7 @@ roadmap: make writing applications easy (and fun).
|
|||
Applications that can be loaded, changed, adapted and remixed by the user
|
||||
are what **really** distinguishes a smart watch from a "feature watch"[#]_.
|
||||
In other words if we want a watch built around a tiny microcontroller to be
|
||||
sufficiently "smart" then it has to be all about the applications.
|
||||
"smart" then it has to be all about the applications.
|
||||
|
||||
This guide will help you get started writing applications for wasp-os. Have fun!
|
||||
|
||||
|
@ -22,7 +22,7 @@ This guide will help you get started writing applications for wasp-os. Have fun!
|
|||
took over the industry were retrospectively renamed "feature phones" to
|
||||
distinguish them from newer devices. Many of them were superficially similar
|
||||
to early Android devices but is was the application ecosystem that really
|
||||
made smart phones smart.
|
||||
made smart phones into what they are today.
|
||||
|
||||
Hello World for wasp-os
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
@ -32,16 +32,16 @@ Let's start by examining a simple "Hello, World!" application for wasp-os.
|
|||
.. literalinclude:: hello.py
|
||||
:linenos:
|
||||
|
||||
There are a couple of points of interest:
|
||||
Some of the key points of interest in this example application are:
|
||||
|
||||
1. Applications have a :py:attr:`~.TemplateApp.NAME`, which is shown in the
|
||||
launcher. Most applications also provide an :py:attr:`~.TemplateApp.ICON`
|
||||
but a default is displayed if this is omitted.
|
||||
but a default will be displayed if this is omitted.
|
||||
2. This example uses :py:meth:`~.TemplateApp.__init__` to initialize
|
||||
the state of the application, this ensure the state remains "sticky"
|
||||
when the application is activated and deactivated.
|
||||
the state of the application, these variables are used to remember
|
||||
the state of the application when when it is deactivated.
|
||||
3. :py:meth:`~.TemplateApp.foreground` is the only mandatory application entry
|
||||
point and is responsible for redrawing the screen. This application does
|
||||
point and it is responsible for redrawing the screen. This application does
|
||||
not implement :py:meth:`~.TemplateApp.background` because there is nothing
|
||||
for us to do!
|
||||
4. The use of :py:meth:`~.TemplateApp._draw` is optional. We could just do
|
||||
|
@ -55,10 +55,11 @@ Application life-cycle
|
|||
Applications in wasp-os are triggered by and do all their processing
|
||||
from calls their entry points. The entry points can be coarsely categorized
|
||||
event notifications, timer callbacks (the application tick) and
|
||||
system notifications.
|
||||
system actions.
|
||||
|
||||
System notifications control the application life-cycle and the entry point
|
||||
calls, together with the implicit application states are shown below.
|
||||
System actions control the application life-cycle and that lifecyle is
|
||||
shown below. The system actions are used to tell the application about
|
||||
any change in its lifecycle.
|
||||
|
||||
.. graphviz::
|
||||
|
||||
|
@ -81,35 +82,43 @@ calls, together with the implicit application states are shown below.
|
|||
|
||||
When an application is initialized is enters the ``BACKGROUND`` state. A
|
||||
backgrounded application will not execute but it should nevertheless
|
||||
maintain its user visible state whilst in the background. To conserve
|
||||
maintain its user visible state whilst deactivated. To conserve
|
||||
memory wasp-os does not permit two applications to run simultaneously but
|
||||
because each application preserves its state when in the background it will
|
||||
appear to the user as though all applications are running all the time.
|
||||
because each application remembers its state when it is not running then it
|
||||
will appear to the user as though all applications are running all the time.
|
||||
|
||||
For example, a stopwatch application should record the time that it was started
|
||||
and remember that start time, regardless of it's state, until either the
|
||||
stopwatch is stopped of the application is destroyed.
|
||||
and remember that start time, regardless of whether it is running or not so
|
||||
that when it restarted is can continue to run as the user expects.
|
||||
|
||||
A backgrounded application can enter the ``ACTIVE`` state via a call to
|
||||
A backgrounded application enters the ``ACTIVE`` state via a call to
|
||||
:py:meth:`~.TemplateApp.foreground`. When it is active the application owns the
|
||||
screen and should draw and maintain its UI.
|
||||
screen and must draw and maintain its user interface.
|
||||
|
||||
If the system manager want to put an active application to sleep then it will
|
||||
call :py:meth:`~.TemplateApp.sleep`. If the application returns True then the
|
||||
application will stop running (e.g. receive no events and no application tick)
|
||||
but instead must wait to receive a notification via
|
||||
:py:meth:`~.TemplateApp.wake` telling the application that the device
|
||||
is waking up and that it may update the screen if needed.
|
||||
If the system manager wants to put the watch to sleep then it will tell the
|
||||
active application to :py:meth:`~.TemplateApp.sleep`.
|
||||
If the application returns True then the application will remain active
|
||||
whilst the watch is asleep.
|
||||
It will receive no events nor the application tick whilst the system is
|
||||
asleep and, instead, must wait for a :py:meth:`~.TemplateApp.wake` notification
|
||||
telling the application that the device is waking up and that it may
|
||||
update the screen if needed.
|
||||
|
||||
If an application does not support sleeping then it can simply not implement
|
||||
:py:meth:`~.TemplateApp.sleep` (or :py:meth:`~.TemplateApp.wake`) although it
|
||||
can also return False from :py:meth:`~.TemplateApp.sleep` if this is preferred.
|
||||
:py:meth:`~.TemplateApp.sleep` or :py:meth:`~.TemplateApp.wake`.
|
||||
In this case the system manager will automatically return to the default
|
||||
application, typically the main clock face.
|
||||
|
||||
Some applications may support sleeping only under certain circumstances. For
|
||||
example a stopwatch may choose to remain active when the watch sleeps only if
|
||||
the stopwatch is running.
|
||||
This type of application must implement :py:meth:`~.TemplateApp.sleep` and
|
||||
return False when it does not want to remain active when the system
|
||||
resumes.
|
||||
|
||||
.. note::
|
||||
|
||||
Most applications do not need to support :py:meth:`~.TemplateApp.sleep`
|
||||
Most applications should not implement :py:meth:`~.TemplateApp.sleep`
|
||||
since it is often a better user experience for the watch to return to the
|
||||
default application when they complete an interaction.
|
||||
|
||||
|
@ -117,19 +126,21 @@ API primer
|
|||
----------
|
||||
|
||||
This API primer introduces some of the most important and frequently used
|
||||
interfaces for wasp-os. For more comprehensive coverage see the
|
||||
interfaces in wasp-os. For more comprehensive coverage see the
|
||||
:ref:`Wasp-os Reference Manual` which contains extensive API documentation
|
||||
covering the entire of wasp-os, including its drivers.
|
||||
|
||||
System management
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The system management API does provide a number of low-level calls that
|
||||
The system management API provides a number of low-level calls that
|
||||
can register new applications and navigate between them. However most
|
||||
applications need not use these. Instead most applications use a small
|
||||
set of methods. In particular almost all applictions need to call a couple of
|
||||
methods from :py:meth:`~.TemplateApp.foreground` in order to register
|
||||
for notifications:
|
||||
applications do not need to make these low level calls and will use
|
||||
a much smaller set of methods.
|
||||
|
||||
Applictions must call a couple of functions from their
|
||||
:py:meth:`~.TemplateApp.foreground` in order to register for
|
||||
event notifications and timer callbacks:
|
||||
|
||||
* :py:meth:`~.Manager.request_event` - register for UI events such as button
|
||||
presses and touch screen activity.
|
||||
|
@ -137,8 +148,8 @@ for notifications:
|
|||
and specify the tick frequency.
|
||||
|
||||
Additionally if your application is a game or a similar program that should
|
||||
not allow the watch to go to sleep then it should arrange to call
|
||||
:py:meth:`~.Manager.keep_awake` from the application's
|
||||
not allow the watch to go to sleep when it is running then it should
|
||||
arrange to call :py:meth:`~.Manager.keep_awake` from the application's
|
||||
:py:meth:`~.TemplateApp.tick` method.
|
||||
|
||||
Drawing
|
||||
|
@ -148,8 +159,8 @@ Most applications using the drawing toolbox, :py:data:`wasp.watch.drawable`,
|
|||
in order to handle the display. Applications are permitted to directly access
|
||||
:py:data:`wasp.watch.display` if they require direct pixel access or want to
|
||||
exploit specific features of the display hardware (inverse video, partial
|
||||
display, etc) but for simple applications then the following simple drawing
|
||||
functions are sufficient.
|
||||
display, etc) but for most applications the drawing toolbox provides
|
||||
convenient and optimized drawing functions.
|
||||
|
||||
* :py:meth:`~.Draw565.blit` - blit an image to the display at specified (x, y)
|
||||
coordinates, image type is detected automatically
|
||||
|
@ -186,7 +197,7 @@ MicroPython
|
|||
|
||||
Many of the features of wasp-os are inherited directly from MicroPython_. It is
|
||||
useful to have a basic understanding of MicroPython and, in particular, put
|
||||
in a little time learning the best ways to copy with running
|
||||
a little time into learning the best practices when running
|
||||
`MicroPython on microcontrollers`__.
|
||||
|
||||
.. _MicroPython: https://micropython.org/
|
||||
|
@ -201,10 +212,10 @@ How to run your application
|
|||
Testing on the simulator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
wasp-os provides a simulator that can be used to test applications before
|
||||
wasp-os includes a simulator that can be used to test applications before
|
||||
downloading them to the device. The simulator is useful for ensuring the
|
||||
code is syntactically correct and that there are not major runtime problems
|
||||
(e.g. missing symbols).
|
||||
such as misspelt symbol names.
|
||||
|
||||
.. note::
|
||||
|
||||
|
@ -212,7 +223,7 @@ code is syntactically correct and that there are not major runtime problems
|
|||
device. It may still be necessary to tune the application for minimal
|
||||
footprint after testing on the simulator.
|
||||
|
||||
Firstly launch the simulator:
|
||||
To launch the simulator:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
|
@ -224,7 +235,7 @@ Firstly launch the simulator:
|
|||
Watch is running, use Ctrl-C to stop
|
||||
|
||||
From the simulator console we can register the application with the following
|
||||
code:
|
||||
commands:
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
@ -240,19 +251,25 @@ code:
|
|||
|
||||
When an application is registered it does not start automatically but it will
|
||||
have been added to the launcher and you will be able to select in the simulator
|
||||
by using the Arrow keys to bring up the launcher and then clicking on your
|
||||
application.
|
||||
by swiping or using the Arrow keys to bring up the launcher and then clicking
|
||||
on your application.
|
||||
|
||||
The application can also be registered automatically when you load the
|
||||
simulator if you add it to ``wasp/main.py``. Try adding lines 5 and 6 from
|
||||
the above example into this file (between ``import wasp`` and
|
||||
``wasp.system.run()``).
|
||||
|
||||
The simulator accepts gestures such as up/down and left/right swipes but the
|
||||
simulator also accepts keystrokes for convenience. The arrow keys simulate
|
||||
swipes and the Tab key simulates the physical button, whilst the 's' key
|
||||
can be used to capture screen shots to add to the documentation for your
|
||||
application.
|
||||
|
||||
Testing on the device
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If we have an application under development when we can launch a quick test
|
||||
that does not result in the application being permanently stored on the device.
|
||||
When an application is under development it is best to temporarily load
|
||||
your application without permanently stored on the device.
|
||||
Providing there is enough available RAM then this can lead to a very quick
|
||||
edit-test cycles.
|
||||
|
||||
|
@ -266,9 +283,8 @@ Try:
|
|||
Preparing to run myapp.py:
|
||||
[##################################################] 100%
|
||||
|
||||
Like the simulator, when an application is registered it does not start
|
||||
automatically but it will have been added to the launcher and can be launched
|
||||
using the normal gestures to control the device.
|
||||
Like the simulator, when an application is registered it is added to the
|
||||
launcher and it does not start automatically.
|
||||
|
||||
.. note::
|
||||
|
||||
|
@ -276,19 +292,24 @@ using the normal gestures to control the device.
|
|||
application is too large to be compiled on the target. You may have to
|
||||
adopt the frozen module approach from the next section.
|
||||
|
||||
To remove the application simply reboot the watch by pressing and
|
||||
holding the physical button until the watch enters OTA mode (this
|
||||
takes around five seconds). Once the watch is in OTA mode then
|
||||
press the phyiscal button again to return to normal mode with the
|
||||
application cleared out.
|
||||
|
||||
Making it permanent
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To ensure you application survives a system reset (press the hardware
|
||||
button for around five seconds until the splash screen is seen, wait
|
||||
five seconds and then press again) then we must copy it to the device
|
||||
and ensure it gets launched during system startup.
|
||||
To ensure you application survives a reboot then we must copy it to the
|
||||
device and ensure it gets launched during system startup.
|
||||
|
||||
.. note::
|
||||
|
||||
Applications stored in external FLASH have a greater RAM overhead than
|
||||
applications that are frozen into the wasp-os binary. See next section for
|
||||
additional details.
|
||||
applications that are frozen into the wasp-os binary. If you app does
|
||||
not fix then see next section for additional details on how to embed
|
||||
your app in the wasp-os binary itself..
|
||||
|
||||
To copy your application to the external FLASH try:
|
||||
|
||||
|
@ -334,16 +355,16 @@ Freezing your application into the wasp-os binary
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Freezing your application causes it to consume dramatically less RAM. That is
|
||||
because the code is both pre-compiled (meaning we don't need any RAM budget to
|
||||
run the compiler) **and** it can execute directly from the internal FLASH
|
||||
memory.
|
||||
because they can execute directly from the internal FLASH rather than running
|
||||
from RAM. Additionally the code is pre-compiled, which also means we don't
|
||||
need any RAM budget to run the compiler.
|
||||
|
||||
Freezing your application simply requires you to modify the ``manifest.py``
|
||||
Freezing your application requires you to modify the ``manifest.py``
|
||||
file for your board (e.g. ``wasp/boards/pinetime/manifest.py``) to include
|
||||
your application and then the whole binary must be re-compiled as normal.
|
||||
|
||||
After that you an use the same technique described in the previous
|
||||
section to add an import and register for you application to ``main.py``
|
||||
section to add an import and register for you application from ``main.py``
|
||||
|
||||
.. note::
|
||||
|
||||
|
@ -352,8 +373,10 @@ section to add an import and register for you application to ``main.py``
|
|||
external FLASH then the frozen version will be loaded.
|
||||
|
||||
In many cases it is possible to avoid rebuilding the binary in order to
|
||||
test new features by parsing the code in the global namespace and then
|
||||
patching it into the existing code. For example the following can be used
|
||||
test new features by directly parsing the code in the global
|
||||
namespace (e.g. using ``wasptool --exec`` rather than ``wasptool --upload``
|
||||
combined with ``import``). With the code in the global namespace it can
|
||||
then be patched into the system. For example the following can be used
|
||||
to adopt a new version of the CST816S driver:
|
||||
|
||||
.. code-block::
|
||||
|
|
|
@ -9,8 +9,8 @@ Application Library
|
|||
Built-in
|
||||
--------
|
||||
|
||||
The built-in application are summarised below but since these apps are
|
||||
considers to be examples they are described in detail as part of the
|
||||
The built-in application are summarised below but because these apps are
|
||||
treated as examples they are described in detail as part of the
|
||||
:ref:`Wasp-os Reference Manual`:
|
||||
|
||||
* :py:class:`.ClockApp`
|
||||
|
@ -25,18 +25,20 @@ Watch faces
|
|||
|
||||
.. automodule:: apps.fibonacci_clock
|
||||
|
||||
This is enabled by default in the simulator. The app is bundled in the
|
||||
firmware image but it is disabled by default to keep RAM available for
|
||||
user developed applications. It can be enabled by modifying ``main.py``.
|
||||
This app is enabled by default in the simulator.
|
||||
The app is also frozen into the firmware image but it is disabled by
|
||||
default in order to keep RAM available for user developed applications.
|
||||
It can be enabled by modifying ``main.py``.
|
||||
|
||||
Games
|
||||
-----
|
||||
|
||||
.. automodule:: apps.gameoflife
|
||||
|
||||
This is enabled by default in the simulator. The app is bundled in the
|
||||
firmware image but it is disabled by default to keep RAM available for
|
||||
user developed applications. It can be enabled by modifying ``main.py``.
|
||||
This app is enabled by default in the simulator.
|
||||
The app is also frozen into the firmware image but it is disabled by
|
||||
default in order to keep RAM available for user developed applications.
|
||||
It can be enabled by modifying ``main.py``.
|
||||
|
||||
Integration
|
||||
-----------
|
||||
|
|
|
@ -10,11 +10,12 @@ Introduction
|
|||
|
||||
Anyone can contribute to the wasp-os project. Contributions are typically made
|
||||
via github using the typical fork-and-pull-request approach. Contributors who
|
||||
do not wish to use github are also welcome to share patches using
|
||||
``git format-patch --to wasp-os@redfelineninja.org.uk`` and ``git send-email``.
|
||||
In both cases, the code will be reviewed by a project maintainer, so please
|
||||
anticipate review comments. Typically pull requests will not be merged if there
|
||||
are open questions or requests for changes that have not been acted on.
|
||||
do not wish to use github are welcome to share patches using ``git
|
||||
format-patch --to wasp-os@redfelineninja.org.uk`` and ``git send-email``. In
|
||||
both cases, the code will be reviewed by a project maintainer, so please
|
||||
anticipate review comments and requests for changes. Typically pull
|
||||
requests will not be merged if there are open questions or requests for
|
||||
changes that have not been acted on.
|
||||
|
||||
All contributions must include a ``Signed-off-by`` tag added by the contributor
|
||||
who submits the patch or patches. The ``Signed-off-by`` tag is added at the end
|
||||
|
@ -68,7 +69,7 @@ easily:
|
|||
Additionally, please be aware that github will not send out automatic
|
||||
notifications to let the maintainer know that you have pushed an update to the
|
||||
pull-request. Follow up the above with a comment on the pull request thread
|
||||
saying that your contribution should be ready to go.
|
||||
saying that your contribution has been updated and is ready for another look.
|
||||
|
||||
Code of Conduct
|
||||
---------------
|
||||
|
|
101
docs/install.rst
101
docs/install.rst
|
@ -31,9 +31,8 @@ a complete sphinx toolchain:
|
|||
sudo apt install sphinx graphviz python3-recommonmark
|
||||
|
||||
Alternatively, if your operating system does not package some or any of
|
||||
the aforementioned Python modules that were included in the previous
|
||||
command, you can install all of them with pip instead. Make sure to
|
||||
adapt the following command appropriately:
|
||||
the above mentioned Python modules then you can install all of them
|
||||
with pip instead:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
|
@ -48,37 +47,37 @@ tested using the `GNU-RM toolchain
|
|||
|
||||
There are known problems with toolchains older than gcc-7.3 when
|
||||
link time optimization is enabled during the MicroPython build
|
||||
(and LTO is enabled by default).
|
||||
(LTO is enabled by default).
|
||||
|
||||
Fetch the code from
|
||||
`https://github.com/daniel-thompson/wasp-os <https://github.com/daniel-thompson/wasp-os>`_ :
|
||||
`https://github.com/daniel-thompson/wasp-os <https://github.com/daniel-thompson/wasp-os>`_ and download the prerequisites:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
git clone https://github.com/daniel-thompson/wasp-os
|
||||
cd wasp-os
|
||||
make submodules
|
||||
make softdevice
|
||||
git clone https://github.com/daniel-thompson/wasp-os
|
||||
cd wasp-os
|
||||
make submodules
|
||||
make softdevice
|
||||
|
||||
To build the firmware select the command appropriate for your board from the
|
||||
list below:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
make -j `nproc` BOARD=pinetime all
|
||||
make -j `nproc` BOARD=k9 all
|
||||
make -j `nproc` BOARD=p8 all
|
||||
make -j `nproc` BOARD=pinetime all
|
||||
make -j `nproc` BOARD=k9 all
|
||||
make -j `nproc` BOARD=p8 all
|
||||
|
||||
To rebuild the documentation try:
|
||||
To rebuild the documentation:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
make docs
|
||||
make docs
|
||||
|
||||
Device Support
|
||||
--------------
|
||||
|
||||
wasp-os can run on multiple devices and, in time, will hopefully be ported to
|
||||
Wasp-os can run on multiple devices and, in time, will hopefully be ported to
|
||||
many more.
|
||||
|
||||
In terms of deciding which device to buy we can suggest two criteria to help.
|
||||
|
@ -95,9 +94,9 @@ second criteria is not technical, it is about community. The Pine64 PineTime is
|
|||
unique among the devices supported by wasp-os because it is intended that the
|
||||
watch be used to run a variety of different open source or free software
|
||||
operating systems. By manufacturing a watch with the intention that it be
|
||||
hacked every which way from Sunday then we get a bigger stronger community
|
||||
hacked every which way from Sunday then we get a bigger, stronger community
|
||||
focused on the PineTime. There is a vibrant support forum, multiple different
|
||||
OS developers (who share ideas and knowledge even if hacking on very different
|
||||
OS developers (who share ideas and knowledge even when hacking on very different
|
||||
code bases) combined with a `near complete set of hardware documentation
|
||||
<https://wiki.pine64.org/index.php/PineTime>`_.
|
||||
|
||||
|
@ -110,7 +109,7 @@ only sold for short periods and may experience undocumented technical changes
|
|||
between manufacturing runs that can cause compatibility problems. This makes it
|
||||
hard for a large community to form around these devices.
|
||||
|
||||
Thus the second criteria it to think about your own needs and abilities. If
|
||||
Thus the second criteria it to think about your own needs and abilities. If
|
||||
you want to enjoy the social and community aspects of working together on open
|
||||
source watch development then you should look very closely at the PineTime.
|
||||
|
||||
|
@ -122,7 +121,7 @@ based on an nRF52832 SoC and includes a 240x240 colour display with touch
|
|||
screen, a step counter and a heart rate sensor.
|
||||
|
||||
wasp-os can be installed directly from the factory default operating
|
||||
system using an over-the-air update with no tools or disassembly is
|
||||
system using an over-the-air update with no tools or disassembly
|
||||
required. nRF Connect for Android can be used to install both the
|
||||
:ref:`wasp-bootloader<Bootloader nRF Connect>` and the
|
||||
:ref:`main OS image<Main OS nRF Connect>`.
|
||||
|
@ -132,9 +131,9 @@ required. nRF Connect for Android can be used to install both the
|
|||
The early adopter PineTime Developer Edition came pre-programmed
|
||||
with a proprietary test firmware rather than the current factory
|
||||
default OS. If you have an early adopter unit then it will appear
|
||||
in the device list as *Y7S* and the tools needed for an OTA update
|
||||
are differnt. DaFlasher for Android can be used to install both the
|
||||
:ref:`wasp-bootloader<Bootloader DaFlasher>` and the
|
||||
in the device list as *Y7S*. In this case the process needed for an
|
||||
OTA update is different. Use DaFlasher for Android to install both
|
||||
the :ref:`wasp-bootloader<Bootloader DaFlasher>` and the
|
||||
:ref:`main OS image<Main OS DaFlasher>`.
|
||||
|
||||
The `developer edition <https://store.pine64.org/?product=pinetime-dev-kit>`_
|
||||
|
@ -152,9 +151,10 @@ provides a 240x240 colour display together with a touch screen and a
|
|||
physical button, all of which appears as a window on your host computer.
|
||||
|
||||
The simulator has large quantities of memory and, whilst useful for
|
||||
exploring wasp-os and testing your programs are syntactically correct
|
||||
exploring wasp-os and testing your programs are syntactically correct,
|
||||
it is not a substitute for testing on real hardware. See
|
||||
:ref:`Testing on the simulator` for more details on how to use the simulator.
|
||||
:ref:`Testing on the simulator` for more details on how to use the
|
||||
simulator.
|
||||
|
||||
To launch the simulator try:
|
||||
|
||||
|
@ -162,6 +162,26 @@ To launch the simulator try:
|
|||
|
||||
make sim
|
||||
|
||||
Colmi P8
|
||||
~~~~~~~~
|
||||
|
||||
The `Colmi P8 <https://www.colmi.com/products/p8-smartwatch>`_ is an almost
|
||||
square smart watch based on an nRF52832 SoC and includes a 240x240 colour
|
||||
display with touch screen, a step counter and a heart rate sensor.
|
||||
|
||||
.. warning::
|
||||
|
||||
The P8 has multiple hardware revisions and the newest version (the
|
||||
one that includes a magnetic charger) uses a different and,
|
||||
currently, unsupported step counter module. The new models will
|
||||
boot wasp-os successfully but the step counter application will
|
||||
be disabled and cannot function.
|
||||
|
||||
DaFlasher for Android can be used to install both the
|
||||
:ref:`wasp-bootloader<Bootloader DaFlasher>` and the
|
||||
:ref:`main OS image<Main OS DaFlasher>`. No tools or disassembly is
|
||||
required.
|
||||
|
||||
Senbono K9
|
||||
~~~~~~~~~~
|
||||
|
||||
|
@ -171,7 +191,7 @@ rate sensor.
|
|||
|
||||
The wasp-os port for Senbono K9 does not, at this point, include a driver for
|
||||
the touch screen because the protocol has not yet been reverse engineered. The
|
||||
touch screen enumerates via I2C at address 70d (or 0x46) and the interrupt can
|
||||
touch screen enumerates via I2C at address 70d (0x46) and the interrupt can
|
||||
be used to detect touch screen activity but the touch coordinates cannot be
|
||||
read from the hardware. Currently the touch screen can only act as a
|
||||
multi-function button and can be used to cycle through the quick ring and
|
||||
|
@ -186,22 +206,6 @@ DaFlasher for Android can be used to install both the
|
|||
:ref:`wasp-bootloader<Bootloader DaFlasher>` and the
|
||||
:ref:`main OS image<Main OS DaFlasher>`. No tools or disassembly is required.
|
||||
|
||||
Colmi P8
|
||||
~~~~~~~~
|
||||
|
||||
The `Colmi P8 <https://www.colmi.com/products/p8-smartwatch>`_ is an almost
|
||||
square smart watch based on an nRF52832 SoC and includes a 240x240 colour
|
||||
display with touch screen, a step counter and a heart rate sensor.
|
||||
|
||||
The P8 has multiple hardware revisions and the newest version (the one that
|
||||
includes a magnetic charger) uses a different and, currently, unsupported step
|
||||
counter module. The new models will boot wasp-os successfully but the step
|
||||
counter application will not be included.
|
||||
|
||||
DaFlasher for Android can be used to install both the
|
||||
:ref:`wasp-bootloader<Bootloader DaFlasher>` and the
|
||||
:ref:`main OS image<Main OS DaFlasher>`. No tools or disassembly is required.
|
||||
|
||||
Installing wasp-bootloader
|
||||
--------------------------
|
||||
|
||||
|
@ -213,6 +217,9 @@ nRF Connect for Android
|
|||
For Pine64 PineTime devices running Infinitime then nRF Connect for Android
|
||||
can be used to install wasp-bootloader:
|
||||
|
||||
* Ensure the watch is fully charged before attempting to install the
|
||||
wasp-bootloader. Running out of power during this process can brick
|
||||
sealed devices.
|
||||
* Copy ``reloader-mcuboot.zip`` (see :ref:`Building wasp-os from source`) to
|
||||
your Android device and download
|
||||
`nRF Connect <https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp>`_
|
||||
|
@ -237,9 +244,10 @@ can be used to install wasp-bootloader:
|
|||
|
||||
.. note::
|
||||
|
||||
It you want to restore the PineTime factory firmware then you can
|
||||
use nRF Connect to do this. Use nRF Connect to send
|
||||
``reloader-factory.zip`` to the wasp-bootloader (called *PineDFU*).
|
||||
If you want to restore the PineTime factory firmware then you can
|
||||
use nRF Connect to do this. Perform a long press reset and then
|
||||
use nRF Connect to send ``reloader-factory.zip`` to the *PineDFU*
|
||||
device.
|
||||
|
||||
.. _Bootloader DaFlasher:
|
||||
|
||||
|
@ -248,6 +256,9 @@ DaFlasher for Android
|
|||
|
||||
To install the bootloader using DaFlasher for Android:
|
||||
|
||||
* Ensure the watch is fully charged before attempting to install the
|
||||
wasp-bootloader. Running out of power during this process can brick
|
||||
sealed devices.
|
||||
* Download and install
|
||||
`DaFlasher <https://play.google.com/store/apps/details?id=com.atcnetz.paatc.patc>`_
|
||||
and copy the DaFlasher bootloaders to your Android device. You will need
|
||||
|
@ -377,6 +388,8 @@ To install the main firmware from a GNU/Linux workstation:
|
|||
:ref:`Building wasp-os from source`) to the device. For example:
|
||||
``tools/ota-dfu/dfu.py -z micropython.zip -a A0:B1:C2:D3:E3:F5 --legacy``
|
||||
|
||||
.. _Troubleshooting:
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
|
|
|
@ -18,8 +18,8 @@ the MicroPython distribution, are licensed under under different open
|
|||
source licenses. The licensing for these components is clearly
|
||||
indicated and reinforced by the directory and sub-module structure.
|
||||
|
||||
Additionally binary releases of wasp-os include the Nordic Softdevice
|
||||
which is licensed under the 5-clause Nordic license.
|
||||
Additionally binary releases of wasp-os include a binary copy of the
|
||||
Nordic Softdevice which is licensed under the 5-clause Nordic license.
|
||||
|
||||
.. toctree::
|
||||
gnu-lgpl-v3.0.rst
|
||||
|
|
|
@ -5,6 +5,7 @@ battery = 'Default battery icon'
|
|||
bomb = 'Small bomb icon'
|
||||
app = 'Default application icon'
|
||||
clock = 'Default digital clock icon'
|
||||
headset = 'Default music player icon'
|
||||
settings = 'Default settings icon'
|
||||
torch = 'Default torch or flashlight icon'
|
||||
up_arrow = 'Small (16x9) up arrow'
|
||||
|
|
Loading…
Reference in a new issue