diff options
Diffstat (limited to 'docs/install.rst')
| -rw-r--r-- | docs/install.rst | 101 |
1 files changed, 57 insertions, 44 deletions
diff --git a/docs/install.rst b/docs/install.rst index 8d0494d..1048f4a 100644 --- a/docs/install.rst +++ b/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 --------------- |