.. _Wasp-os Reference Manual: Wasp-os Reference Manual ======================== .. contents:: :local: System ------ .. automodule:: wasp :members: .. automodule:: watch .. automodule:: draw565 :members: .. automodule:: icons :members: :undoc-members: .. automodule:: fonts.clock :members: :undoc-members: .. automodule:: fonts.sans24 :members: .. automodule:: fonts.sans28 :members: .. automodule:: fonts.sans36 :members: .. automodule:: logo :members: :undoc-members: .. automodule:: steplogger :members: :undoc-members: .. automodule:: widgets :members: Device drivers -------------- .. automodule:: drivers.battery :members: .. automodule:: drivers.cst816s :members: .. automodule:: drivers.nrf_rtc :members: .. automodule:: drivers.signal :members: .. automodule:: drivers.st7789 :members: .. automodule:: drivers.vibrator :members: Bootloader ---------- The bootloader implements a couple of protocols that allow the bootloader and payload to communicate during a reset or on handover from bootloader to application. GPREGRET protocol ~~~~~~~~~~~~~~~~~ ``GPREGRET`` is a general purpose 8-bit retention register that is preserved in all power states of the nRF52 (including System OFF mode when SRAM content is destroyed). It can be used by the application to request specific bootloader behaviours during a reset: ================= ===== ====================================================== Name Value Description ----------------- ----- ------------------------------------------------------ OTA_APPJUM 0xb1 Bootloader entered (without reset) from application. OTA_RESET 0xa8 Enter OTA (Bluetooth) recovery mode SERIAL_ONLY_RESET 0x4e Enter UART recovery mode (if applicable) UF2_RESET 0x57 Enter USB recovery mode (if applicable) FORCE_APP_BOOT 0x65 Force direct application boot (no splash screen) ================= ===== ====================================================== PNVRAM protocol ~~~~~~~~~~~~~~~ The pseudo non-volatile RAM is a small block of regular static RAM that, once initialized, can be used to share information. The PNVRAM starts at 0x200039c0 and is 32 bytes long. ========== =================================================================== Address Description ---------- ------------------------------------------------------------------- 0x200039c0 Guard value. Must be set to 0x1abe11ed . 0x200039c4 Course grained RTC value (bootloader must preserve but can ignore). 0x200039c8 RTC millisecond counter (bootloader must increment this). 0x200039cc Reserved 0x200039d0 Reserved 0x200039d4 Reserved 0x200039d8 Reserved 0x200039dc Guard value. Must be set to 0x10adab1e . ========== =================================================================== Note: *The PNVRAM protocol allows up to 28 bytes to be transfered (compared to 2 bytes via GPREGRET and GPREGRET2) but it is less versatile. For example FORCE_APP_BOOT cannot be implmented using PNVRAM.* The RTC millisecond counter is incremented whenever the bootloader is 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 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 bootloader mode. This makes them difficult to develop on because opening the case to access a SWD or reset pins may compromise their waterproofing. wasp-os uses a watchdog timer (WDT) combined with a single hardware button in order to provide a robust mechanism to allow the user to force entry into a over-the-air firmware recovery mode that allows the buggy application to be replaced. The software responsibilities to implement this are split between the bootloader and the application, although the application responsibilities are intentionally minimal. 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. Additionally the bootloader implements several watchdog related features necessary for robust reboot handling: 1. The bootloader configures the watchdog prior to booting the main application. This is a simple, single channel reload request, watchdog with a 5 second timeout. 2. The bootloader checks the reset reason prior too booting the main application. If it detects a watchdog reset the bootloader switches automatically to DFU mode. 3. The bootlaoder initialized the pinmux allowing the hardware button state to be observed. 4. The bootloader monitors the hardware button and switches back to the main application when it is pressed. 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. 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 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 is fine because we only need the dog to bark if the hardware button is pressed. 2. The routine to pet the dog is predicated on the hardware button not being pressed. 3. The routine to pet the dog is also predicated on the hardware button still being correctly configured. To avoid mistakes the application should contain no subroutines that unconditionally pet the dog; they should all implement #2 and #3 from the above list. Note: *nRF52 microcontrollers implement a distributed pin-muxing mechanism meaning most peripheral can acidentally "steal" a pin if the pin is requested by the peripheral. This requires a fully robust implementation of #3 to visit the PSEL registers of every peripheral that can control pins. The code currently used in wasp-os does not yet meet this criteria.*