.clang

-flags = -DBOARD_CARD10=1 -D_FILE_OFFSET_BITS=64 -DTARGET=32665 -DTARGET_REV=0x4131 -target thumbv7m-none-eabi -Ibuild/epicardium -Ibuild/epicardium/366573f@@api-caller@sta -Ibuild/epicardium/366573f@@api-dispatcher@sta -Ibuild/epicardium/366573f@@epicardium.elf@exe -Ibuild/epicardium/366573f@@freertos@sta -Ibuild/lib/card10 -Ibuild/lib/card10/7eaaaa5@@card10@sta -Ibuild/lib/ff13 -Ibuild/lib/ff13/a277df3@@ff13@sta -Ibuild/lib/gfx -Ibuild/lib/gfx/2308dff@@gfx@sta -Ibuild/lib/micropython -Ibuild/lib/micropython/a57cd11@@mpy-cross-wrapper@exe -Ibuild/lib/mx25lba -Ibuild/lib/mx25lba/c7b864b@@mx25lba@sta -Ibuild/lib/sdk/Libraries/Boards/card10 -Ibuild/lib/sdk/Libraries/Boards/card10/9eeeac4@@board-card10@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665 -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup-core0@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup-core1@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup@sta -Ibuild/lib/sdk/Libraries/MAX32665PeriphDriver -Ibuild/lib/sdk/Libraries/MAX32665PeriphDriver/0d96707@@PeriphDriver@sta -Ibuild/lib/sdk/Libraries/MAXUSB -Ibuild/lib/sdk/Libraries/MAXUSB/9a51a91@@maxusb@sta -Ibuild/lib/vendor/Bosch/BHy1 -Ibuild/lib/vendor/Bosch/BHy1/6298ab9@@bhy1@sta -Ibuild/lib/vendor/Bosch/BMA400 -Ibuild/lib/vendor/Bosch/BMA400/b6b0216@@bma400@sta -Ibuild/lib/vendor/Bosch/BME680 -Ibuild/lib/vendor/Bosch/BME680/ef6f079@@bme680@sta -Ibuild/lib/vendor/Maxim/MAX77650 -Ibuild/lib/vendor/Maxim/MAX77650/cc369b8@@max77650@sta -Ibuild/lib/vendor/Maxim/MAX86150 -Ibuild/lib/vendor/Maxim/MAX86150/21e3a66@@max86150@sta -Ibuild/pycardium -Ibuild/pycardium/1f90fd2@@micropython@sta -Ibuild/pycardium/1f90fd2@@pycardium.elf@exe -Iepicardium -Ilib/card10 -Ilib/ff13 -Ilib/ff13/Source -Ilib/ff13/util -Ilib/FreeRTOS/Source/include -Ilib/FreeRTOS/Source/portable/GCC/ARM_CM4F -Ilib/gfx -Ilib/gfx/Fonts -Ilib/gfx/GUI_DEV -Ilib/gfx/LCD -Ilib/micropython -Ilib/micropython/micropython -Ilib/micropython/micropython/extmod -Ilib/micropython/micropython/lib/utils -Ilib/mx25lba -Ilib/sdk/Libraries/Boards/card10 -Ilib/sdk/Libraries/Boards/card10/Include -Ilib/sdk/Libraries/Boards/Include -Ilib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665 -Ilib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/Include -Ilib/sdk/Libraries/CMSIS/Include -Ilib/sdk/Libraries/MAX32665PeriphDriver -Ilib/sdk/Libraries/MAX32665PeriphDriver/Include -Ilib/sdk/Libraries/MAXUSB -Ilib/sdk/Libraries/MAXUSB/include/core -Ilib/sdk/Libraries/MAXUSB/include/core/musbhsfc -Ilib/sdk/Libraries/MAXUSB/include/dbg_log -Ilib/sdk/Libraries/MAXUSB/include/devclass -Ilib/sdk/Libraries/MAXUSB/include/enumerate -Ilib/sdk/Libraries/MAXUSB/include/util -Ilib/vendor/Bosch/BHy1 -Ilib/vendor/Bosch/BHy1/driver/inc -Ilib/vendor/Bosch/BHy1/examples/firmware -Ilib/vendor/Bosch/BMA400 -Ilib/vendor/Bosch/BME680 -Ilib/vendor/Maxim/MAX77650 -Ilib/vendor/Maxim/MAX86150 -Ipycardium
+flags = -DBOARD_CARD10=1 -D_FILE_OFFSET_BITS=64 -DTARGET=32665 -DTARGET_REV=0x4131 -target thumbv7m-none-eabi -Ibuild/epicardium -Ibuild/epicardium/366573f@@api-caller@sta -Ibuild/epicardium/366573f@@api-dispatcher@sta -Ibuild/epicardium/366573f@@epicardium.elf@exe -Ibuild/epicardium/366573f@@freertos@sta -Ibuild/lib/card10 -Ibuild/lib/card10/7eaaaa5@@card10@sta -Ibuild/lib/ff13 -Ibuild/lib/ff13/a277df3@@ff13@sta -Ibuild/lib/gfx -Ibuild/lib/gfx/2308dff@@gfx@sta -Ibuild/lib/micropython -Ibuild/lib/micropython/a57cd11@@mpy-cross-wrapper@exe -Ibuild/lib/mx25lba -Ibuild/lib/mx25lba/c7b864b@@mx25lba@sta -Ibuild/lib/sdk/Libraries/Boards/card10 -Ibuild/lib/sdk/Libraries/Boards/card10/9eeeac4@@board-card10@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665 -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup-core0@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup-core1@sta -Ibuild/lib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/a500f70@@max32665-startup@sta -Ibuild/lib/sdk/Libraries/MAX32665PeriphDriver -Ibuild/lib/sdk/Libraries/MAX32665PeriphDriver/0d96707@@PeriphDriver@sta -Ibuild/lib/sdk/Libraries/MAXUSB -Ibuild/lib/sdk/Libraries/MAXUSB/9a51a91@@maxusb@sta -Ibuild/lib/vendor/Bosch/BHy1 -Ibuild/lib/vendor/Bosch/BHy1/6298ab9@@bhy1@sta -Ibuild/lib/vendor/Bosch/BMA400 -Ibuild/lib/vendor/Bosch/BMA400/b6b0216@@bma400@sta -Ibuild/lib/vendor/Bosch/BME680 -Ibuild/lib/vendor/Bosch/BME680/ef6f079@@bme680@sta -Ibuild/lib/vendor/Maxim/MAX77650 -Ibuild/lib/vendor/Maxim/MAX77650/cc369b8@@max77650@sta -Ibuild/lib/vendor/Maxim/MAX86150 -Ibuild/lib/vendor/Maxim/MAX86150/21e3a66@@max86150@sta -Ibuild/pycardium -Ibuild/pycardium/1f90fd2@@micropython@sta -Ibuild/pycardium/1f90fd2@@pycardium.elf@exe -Iepicardium -Ilib/card10 -Ilib/ff13 -Ilib/ff13/Source -Ilib/ff13/util -Ilib/FreeRTOS/Source/include -Ilib/FreeRTOS/Source/portable/GCC/ARM_CM4F -Ilib/gfx -Ilib/gfx/Fonts -Ilib/gfx/GUI_DEV -Ilib/gfx/LCD -Ilib/micropython -Ilib/micropython/micropython -Ilib/micropython/micropython/extmod -Ilib/micropython/micropython/lib/utils -Ilib/mx25lba -Ilib/sdk/Libraries/Boards/card10 -Ilib/sdk/Libraries/Boards/card10/Include -Ilib/sdk/Libraries/Boards/Include -Ilib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665 -Ilib/sdk/Libraries/CMSIS/Device/Maxim/MAX32665/Include -Ilib/sdk/Libraries/CMSIS/Include -Ilib/sdk/Libraries/MAX32665PeriphDriver -Ilib/sdk/Libraries/MAX32665PeriphDriver/Include -Ilib/sdk/Libraries/MAXUSB -Ilib/sdk/Libraries/MAXUSB/include/core -Ilib/sdk/Libraries/MAXUSB/include/core/musbhsfc -Ilib/sdk/Libraries/MAXUSB/include/dbg_log -Ilib/sdk/Libraries/MAXUSB/include/devclass -Ilib/sdk/Libraries/MAXUSB/include/enumerate -Ilib/sdk/Libraries/MAXUSB/include/util -Ilib/vendor/Bosch/BHy1 -Ilib/vendor/Bosch/BHy1/driver/inc -Ilib/vendor/Bosch/BHy1/examples/firmware -Ilib/vendor/Bosch/BMA400 -Ilib/vendor/Bosch/BME680 -Ilib/vendor/Maxim/MAX77650 -Ilib/vendor/Maxim/MAX86150 -Ipycardium -Ilib/ctx

.gitlab-ci.yml

@@ -4,22 +4,33 @@ image: "derq3k/card10-build-env:20190806-195837Z-f95b541-dirty"
 build:
     stage: build
     script:
+        - git submodule deinit --all -f
         - ./bootstrap.sh --werror
         - ninja -C build/
         - arm-none-eabi-size build/bootloader/bootloader.elf build/epicardium/epicardium.elf build/pycardium/pycardium.elf
+        - cp build/pycardium/pycardium_epicardium.bin card10.bin
     only:
         - merge_requests
         - master
+    artifacts:
+        expose_as: Firmware Binaries
+        expire_in: 1 week
+        paths:
+            - build/epicardium/epicardium.elf
+            - build/pycardium/pycardium.elf
+            - card10.bin
 
 release:
     stage: build
     script:
+        - git submodule deinit --all -f
         - ./bootstrap.sh --werror
         - ninja -C build/
         - arm-none-eabi-size build/bootloader/bootloader.elf build/epicardium/epicardium.elf build/pycardium/pycardium.elf
     only:
         - tag
     artifacts:
+        expire_in: never
         paths:
             - build/bootloader/bootloader.elf
             - build/epicardium/epicardium.elf
@@ -36,7 +47,7 @@ lint:
         # If this starts failing for any reason, just remove this curl ping.
         - curl --fail https://annoyatron-prod.q3k.org/ping/mr?mr=${CI_MERGE_REQUEST_IID}
         - git remote rm card10 || true # old gitlab runners might have this remote.
-        - git fetch https://git.card10.badge.events.ccc.de/card10/firmware.git master:card10/master
+        - git -c http.sslVerify=false fetch https://git.card10.badge.events.ccc.de/card10/firmware.git master:card10/master
         - git merge-base card10/master HEAD || ( echo "Your change needs to be rebased against current master."; exit 1; )
         - git diff --name-only --diff-filter=d card10/master...HEAD | xargs tools/code-style.sh
         - git diff --exit-code
@@ -46,7 +57,7 @@ lint:
 pages:
     stage: deploy
     # maintaned by q3k, build using docker/deploy-env
-    image: "derq3k/card10-deploy-env:20190806-200743Z-f95b541-dirty"
+    image: "registry.k0.hswaw.net/q3k/card10-deploy-env:20210403-110003Z-4d929ee0"
     script:
         - export LD_LIBRARY_PATH=$(llvm-config --libdir)
         - echo $LD_LIBRARY_PATH

.gitmodules

@@ -10,3 +10,6 @@
 [submodule "lib/crypto/SHA256"]
 	path = lib/crypto/SHA256
 	url = https://github.com/ilvn/SHA256
+[submodule "lib/lodepng/lodepng"]
+	path = lib/lodepng/lodepng
+	url = https://github.com/lvandeve/lodepng

CHANGELOG.md

@@ -4,22 +4,149 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
+
+
+## [v1.18] - 2021-12-25 - [Queer Quinoa]
+[Queer Quinoa]: https://card10.badge.events.ccc.de/release/card10-v1.18-Queer-Quinoa.zip
+
+### For Users
+- Much improved battery runtime, up to 160% more time without recharging!
+- Integration of the [ctx.graphics] vector graphics renderer!  This
+  means much smoother looking graphics as CTX comes with anti-aliasing!
+  For now, CTX is only integrated as a backend (for the existing graphics API)
+  but in future releases you will also be able to use CTX directly as well.
+- As part of that, we have integrated a new font.  You can also use your own, by
+  replacing `lib/ctx/fira-mono.ttf` with a font of your choice and then
+  rebuilding the firmware.
+- Automatically return from USB storage mode after the host (= your computer)
+  ejects the device.
+- Added ECG streaming over BLE.  The latest version of the Android companion
+  app implements the other side of this.
+
+### For Hackers
+- Disable IRQs on core 1 during all Epicardium API calls.  This means API calls
+  are now always safe to use from ISRs.
+- Added an [`epic_sleep()`] API call which can be used as a hint to Epicardium
+  that it can enter a deep-sleep mode.  [`epic_sleep()`] will only return once
+  either the time is up or an interrupt to core 1 is pending.  Pycardium now
+  uses this call for all delays by default.
+- Update MicroPython to v1.17.
+- With the MicroPython update, pycardium now supports f-strings!
+- Firmware version can now be properly read out over BLE.
+- Legacy app launcher scripts in the filesystem root are deleted on startup of
+  new versions now.  Newer companion app releases also no longer generate this
+  launcher script.
+
+### Internals
+- Restructured `epicardium/modules` into more sensible subdirectories.
+- Switched the UART peripheral to use the HIRC8 clock.
+- Converted the "personal state" implementation to use the workqueue.
+- Switched the SysTick in Pycardium to use the 32kHz clock source.
+- Made display backlight PWM robust against changes to the MCU's PCLK speed.
+- During tickless idle, lower the core-clock (PCLK) to reduce power consumption.
+- Rewrote the LCD driver.
+- Put the display to sleep when the backlight is off to save power.
+- Fixed a 32-bit overflow in Pycardium systick code.
+
+[ctx.graphics]: https://ctx.graphics/
+[`epic_sleep()`]: https://firmware.card10.badge.events.ccc.de/epicardium/api.html#c.epic_sleep
+
+
+## [v1.17] - 2021-04-04 - [R2R Rocket]
+[R2R Rocket]: https://card10.badge.events.ccc.de/release/card10-v1.17-R2R-Rocket.zip
+
+### For Users
+#### Added
+- Added the Bosch BSEC library for the BME680 sensor.  See the [``bme680``
+  module][bme680-docs] documentation for details.
+- Added a [BLE Environmental Sensing Service][ess-docs].
+- Added a [BLE HID Service][ble-hid-docs].
+- Added the ability to use the pulse-oximeter as a proximity sensor (makes it
+  usable as a button).  Additionally a demo-application was added which uses
+  this for a push-to-talk button.
+- Added a [blitting][blit-docs] function to the display module.  This finally
+  allows to efficiently draw pixels!
+- MicroPython BLE support!
+- A PNG library for pycardium: [`png`][png-docs]
+- Two more config options to tweak menu button behavior: `long_press_ms` and ``retrigger_ms``
+- Option to disable low battery checks via `card10.cfg`.  This is meant for
+  devices where the connection between the PMICs ADMUX and the CPU's ADC is broken
+  in some way, leading to the device always reporting a low battery condition.
+
+#### Changed
+- Updated the BME680 demo app with BSEC support.
+- Upgraded to MicroPython 1.14.
+- Open the USB mass-storage when no apps are found.
+- Improved the l0dables runtime; it now handles HardFaults and app-exits
+  properly.
+
+#### Fixed
+- Fixed lockup when trying to load an ELF l0dable while ELFs are disabled.
+- Fixed card10 not waking up from sleep when BLE is disabled (regression from 1.15 to 1.16).
+- Fixed card10 not working with the Harmonic Board disconnected (regression from
+  1.15 to 1.16).
+
+#### Removed
+- Removed the battery BLE service.
+
+### Internals
+#### Added
+- A work-queue API in Epicardium to schedule work that needs to be done
+  asynchronously.
+
+#### Changed
+- Upgraded to newer SDK version.
+- Cleaned up the BHI160 driver a bit.
+- Readjusted the flash layout, to give Epicardium more space.
+- Upgraded the documentation to use Sphinx 3.
+
+[bme680-docs]: https://firmware.card10.badge.events.ccc.de/pycardium/bme680.html
+[ess-docs]: https://firmware.card10.badge.events.ccc.de/bluetooth/ess.html
+[ble-hid-docs]: https://firmware.card10.badge.events.ccc.de/pycardium/ble_hid.html
+[blit-docs]: https://firmware.card10.badge.events.ccc.de/pycardium/display.html#display.Display.blit
+[png-docs]: https://firmware.card10.badge.events.ccc.de/pycardium/png.html
+
+
+## [v1.16] - 2020-12-04 - [Pandemic Potato]
+[Pandemic Potato]: https://card10.badge.events.ccc.de/release/card10-v1.16-Pandemic-Potato.zip
+
 ### Added
-- `leds.flash_rocket()` API for making rockets flash asynchronously.
-- Basic API for the MAX86150 pulse-oximeter.
+#### For Users
 - A feature to allow setting the main app on-device.
 - Added compatibility to BLE 5.0 capable phones (including iPhones).
-- Added pairing dialog in BLE app. Device is only visible when BLE app is
+- Added a pairing dialog in the BLE app. card10 is only visible when BLE app is
   active.
-- Option to write HCI layer log files for debugging.
-- _Stub_ `ubluetooth` module.  Not yet functional!
+- G-Watch watch face.
+- App for COVID-19 exposure notification statistics.
+- Experimental app using the MAX86150 pulse-oximeter.
 
+#### For Developers
+- `leds.flash_rocket()` API for making rockets flash asynchronously.
+- Basic API for the MAX86150 pulse-oximeter.
+- CSPRNG as a replacement for the hardware TRNG which does not seem to produce
+  good entropy the way we are using it right now.
+- Option to write HCI layer log files for debugging.
+- Feature in `simple_menu` which detects long button presses.
+- _Stub_ `ubluetooth` module. Not yet functional!
 
 ### Changed
-- Internal changes to the way interrupts are triggered.
-- Updated to a newer version of MicryPython (v1.12).
+#### For Users
+- The default watch face is now G-Watch.
 - Improved BLE security by only allowing man-in-the-middle protected
   pairings and specifying minimum key lengths.
+- Read time/date automatically from iOS devices.
+- It is now configurable whether the left/right bottom buttons or the right
+  top/bottom buttons scroll in the menu via the `right_scroll` option in
+  `card10.cfg`.
+
+#### For Developers
+- Updated to a newer version of MicroPython (v1.12).
+- All `u{module}` MicroPython modules are now also available as `{module}` which
+  brings card10 more in line with upstream.
+- Updated to SDK version 0.2.1-12
+- The BLE pairing database was completely overhauled.
+- Use the CSPRNG for all MicroPython randomness.
+- Internal changes to the way interrupts are triggered.
 
 ### Fixed
 - Made the `vibra` vibration motor API more stable.
@@ -27,6 +154,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Fixed bug which made the USB serial connection unresponsive.
 - Fixed bug which wrote the pairings file more periodically.
 - Fixed invalid filesystem locking in BLE startup.
+- Only print a single warning when a sensor stream overflows instead of spamming
+  the console with errors.
+- Fixed issues from reloading the configuration file.
+- Fixed `pycard10.py` not properly resetting the device before loading a script.
+- Allow to reopen BHI160 sensor from python.
+- Fixed pycardium not exiting when triggering certain failure conditions.
+- Made the config parser more robust.
+- Fixed a possible lockup in the handling of the serial console.
 
 
 ## [v1.15] - 2020-02-02 - [Okra]
@@ -413,7 +548,10 @@ fbf7c8c0 fix(menu.py) Refactored menu.py based on !138
 ## [v1.0] - 2019-08-21 00:50
 Initial release.
 
-[Unreleased]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.15...master
+[Unreleased]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.18...master
+[v1.18]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.17...v1.18
+[v1.17]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.16...v1.17
+[v1.16]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.15...v1.16
 [v1.15]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.14...v1.15
 [v1.14]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.13...v1.14
 [v1.13]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.12...v1.13

Documentation/bluetooth/card10.rst

+.. _bluetooth_card10_service:
+
 Bluetooth Card10 Service
 ========================
 

Documentation/bluetooth/ecg.rst

+.. _bluetooth_ecg_service:
+
+Bluetooth ECG Service
+========================
+
+.. warning::
+    The service is still work in progress and subject to change
+
+The ECG service provides access to the ECG sensor of the card10
+
+BLE Service
+-----------
+
+The current draft uses following service specification:
+
+- Service:
+
+  UUID: ``42230300-2342-2342-2342-234223422342``
+
+- ECG samples characteristic:
+
+  UUID: ``42230301-2342-2342-2342-234223422342``
+  notify
+
+ECG samples characteristic
+--------------------------
+
+List of 16 bit samples (big endian). Enable notifications to
+receive a stream of samples while the ECG app is open.
+
+The first 16 bit are a sample counter (big endian).

Documentation/bluetooth/ess.rst

+.. _ESS:
+
+Environmental Sensing Service
+=============================
+
+The Environmental Sensing Service (ESS) implements access to
+the BME680 environmental sensor of the card10.
+
+It provides:
+
+- Temperature
+- Relative humidity
+- Pressure
+
+If :ref:`bsec_api` is enabled the following additional estimates are available:
+
+ - Indoor air quality (IAQ estimate
+ - Equivalent CO2 (eCO2) estimate
+
+Please refer to :py:mod:`bme680` for more information about BSEC.
+
+
+If notifcations are enabled a measurement of all values is performed every 3 seconds. For each measurement a notification is sent for the characteristics which have notifications enabled.
+
+
+A measurement can also be triggered by reading from a characteristic. A measurement takes roughly 200 ms. A notifciation will be sent to all characteristics which have notifications enabled except the one which was used to trigger the measurement.
+
+.. note::
+   If :ref:`bsec_api` is enabled, reading a characteristic will not trigger a new measurement.
+
+.. note::
+    This service will be available in version v1.17.
+
+
+BLE Service
+-----------
+
+- Service
+
+  UUID: ``181A``
+
+- Temperature characteristic:
+
+  UUID: ``2A6E``
+  read and notify
+
+- Humidity characteristic:
+
+  UUID: ``2A6F``
+  read and notify
+
+- Pressure characteristic:
+
+  UUID: ``2A6D``
+  read and notify
+
+- Indoor air quality (IAQ) characteristic:
+
+  UUID: ``422302f1-2342-2342-2342-234223422342``
+  read and notify
+
+Temperature characteristic
+--------------------------
+
+- 16 bit little endian value representing the measured temperature.
+
+- Unit: 0.01 deg C
+
+
+Humidity characteristic
+-----------------------
+
+- 16 bit little endian value representing the measured relative humidity.
+
+- Unit: 0.01%
+
+Pressure characteristic
+-----------------------
+
+- 32 bit little endian value representing the measured pressure.
+
+- Unit: 0.1 Pa (0.001 hPa)
+
+Indoor air quality (IAQ) characteristic
+---------------------------------------
+
+Data format:
+
+======== =========================== ===========================
+Byte 0   Bytes 1-2                   Bytes 3-4
+-------- --------------------------- ---------------------------
+Accuracy IAQ (16-bit little endian)  eCO2 (16-bit little endian)
+======== =========================== ===========================
+
+
+Units:
+
+- Accuracy and IAQ units: See :ref:`bsec_api` API description
+- CO2 unit: [ppm]

Documentation/bluetooth/file-transfer.rst

+.. _bluetooth_file_transfer:
+
 Bluetooth File Transfer
 =======================
 

Documentation/bluetooth/overview.rst

+.. _bluetooth_overview:
+
+Overview
+========
+
+UUIDs
+-----
+Bluetooth uses UUIDs to identify almost everything. The Bluetooth SIG specifies
+a number of "short" 16-bit UUIDs for general use. A device is free to define
+other "long" 128-bit UUIDs if it wants to express non-standard functionality.
+
+The card10 defines a few non-standard UUIDs. They are prefixed with ``4232``:
+
+
++--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
+| UUID                                 | Usage                                                 | Comment                                                            |
++======================================+=======================================================+====================================================================+
+| 422301XX-2342-2342-2342-234223422342 | :ref:`File Transfer Service<bluetooth_file_transfer>` | Used by the Companion App to install apps on the card10            |
++--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
+| 422302XX-2342-2342-2342-234223422342 | :ref:`card10 Service<bluetooth_card10_service>`       | Controls general card10 functionality like LEDs and personal state |
++--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
+| 422303XX-2342-2342-2342-234223422342 | :ref:`ECG Service<bluetooth_ecg_service>`             | Allows to stream ECG measurements via BLE                          |
++--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
+| 422380XX-2342-2342-2342-234223422342 | Experimental usage                                    | To be used for development and experiments                         |
++--------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------+
+
+The first byte after the prefix identifies the service (e.g. ``03`` for ECG).
+The next byte is reserved for UUIDs used by the service itself. The service
+uses ``00`` at this position. The first attribute inside the service uses
+``01`` at this position. See the documentation of any service for an example.
+
+You can use the UUID range 422380XX-2342-2342-2342-234223422342 for your own
+experiments / demos/ development. For example the demos under `demos/` in the
+repository use this range of UUIDs.
+
+BLE with MicroPython
+--------------------
+
+MicroPython docs: https://docs.micropython.org/en/latest/library/bluetooth.html
+
+Basic example: https://git.card10.badge.events.ccc.de/card10/firmware/-/blob/master/demos/ble-ws2812-card10.py and https://git.card10.badge.events.ccc.de/card10/firmware/-/blob/master/demos/ble-ws2812-host.py
+
+MicroPython examples: https://github.com/micropython/micropython/tree/7c54b6428058a236b8a48c93c255948ece7e718b/examples/bluetooth

Documentation/build-docs.sh

@@ -4,3 +4,7 @@ set -e
 cd "$(dirname "$0")"
 
 sphinx-build -b html . ./output
+
+if [ "$1" = "--open" ]; then
+   xdg-open ./output/index.html
+fi

Documentation/card10-cfg.rst

@@ -43,5 +43,27 @@ Option name        Type       Description
 ------------------ ---------- -----------
 ``default_app``    String     Full path to the exectutable file of the default application. If this option is not set,``apps/analog_clock/__init__.py`` is used.
 ------------------ ---------- -----------
+``ble_enable``     Boolean    Activate the BLE interface. Turn off for more privacy or to conserve energy.
+------------------ ---------- -----------
+``ble_mac``        Boolean    MAC address used for BLE. Format: ``ca:4d:10:xx:xx:xx``.
+------------------ ---------- -----------
+``ble_hid_enable`` Boolean    Enable the Human Interface Device (HID) characteristics on BLE.
+------------------ ---------- -----------
 ``ble_log_enable`` Boolean    Activate HCI level logging of BLE data. Creates a new btsnoop compatible log file named ``ble.log`` in the ``logs`` folder after each boot if BLE is activated. Keeps the last 10 files.
+------------------ ---------- -----------
+``right_scroll``   Boolean    Use both right buttons to scroll up and down. Lower left button is SELECT.
+------------------ ---------- -----------
+``long_press_ms``  Integer    Defines the timespan for a long key press in milliseconds.
+------------------ ---------- -----------
+``retrigger_ms``   Integer    Defines the timespan for repeating key presses when a key is hold in milliseconds.
+------------------ ---------- -----------
+``bsec_enable``    Boolean    Activate the Bosch :ref:`bsec_api` binary blob to compute an Indoor Air Quality indication.
+------------------ ---------- -----------
+``bsec_debug``     Boolean    Turn on debug output of the BSEC system. Prints each meaurement on the console.
+------------------ ---------- -----------
+``bsec_offset``    Integer    Temperature offset in .1 K. Example: Set to `-14` if temperature reads 1.4 "C" to high. Default: -2.2 K (appropriate for a card10 without a case, connected to USB and with BLE active in vertical orientation).
+------------------ ---------- -----------
+``battery_check``  Boolean    Whether the low battery check should be enabled (default ``true``).  **Warning**: Do not use this unless you know what you're doing.  This option is only meant to be used on devices with a broken PMIC ADMUX connection.
+------------------ ---------- -----------
+``has_flashlight`` Boolean    Whether the flashlight LED was soldered onto the harmonic board.  Can be used by apps to optionally enable flashlight features.
 ================== ========== ===========

Documentation/conf.py

@@ -15,7 +15,6 @@ sys.path.insert(0, os.path.abspath("./"))
 
 logger = sphinx.util.logging.getLogger("card10/conf.py")
 
-
 # -- Project information -----------------------------------------------------
 
 project = "card10-firmware"
@@ -109,12 +108,14 @@ html_context = {
 autodoc_mock_imports = [
     "buttons",
     "interrupt",
+    "sys_ble_hid",
     "sys_bme680",
     "sys_bhi160",
     "sys_display",
     "sys_leds",
     "sys_max30001",
     "sys_max86150",
+    "sys_png",
     "sys_config",
     "ucollections",
     "uerrno",
@@ -148,3 +149,35 @@ except ImportError as e:
 def setup(app):
     app.add_config_value("has_hawkmoth", has_hawkmoth, "")
     app.add_directive("color-example", ColorExample)
+    fix_issue_8945()
+
+
+def fix_issue_8945():
+    c_domain = __import__("sphinx.domains.c").domains.c
+
+    for kw in [
+        "char",
+        "float",
+        "int",
+        "long",
+        "short",
+        "void",
+        "_Bool",
+        "bool",
+        "_Complex",
+        "complex",
+    ]:
+        if kw in c_domain._keywords:
+            c_domain._keywords.remove(kw)
+        if hasattr(c_domain, "_macroKeywords") and kw in c_domain._macroKeywords:
+            c_domain._macroKeywords.remove(kw)
+
+    def parse_xref_object(self):
+        name = self._parse_nested_name()
+        self.skip_ws()
+        self.skip_string("()")
+        # Removing this line as a hacky workaround:
+        # self.assert_end()
+        return name
+
+    c_domain.DefinitionParser.parse_xref_object = parse_xref_object

Documentation/epicardium/internal.rst

+.. _epicardium_internal_apis:
+
+Epicardium Internal APIs
+========================
+
+Core OS APIs
+------------
+.. c:autodoc:: epicardium/os/core.h

Documentation/epicardium/mutex.rst

@@ -23,7 +23,7 @@ look at the :ref:`mutex-design-reasons`.
 
 Definitions
 -----------
-.. c:autodoc:: epicardium/modules/mutex.h
+.. c:autodoc:: epicardium/os/mutex.h
 
 .. _mutex-design-reasons:
 

Documentation/hawkmoth/README.txt → Documentation/hawkmoth/README.rst

@@ -40,9 +40,9 @@ to any symbols.
 Documentation
 -------------
 
-Documentation on how to configure Hawkmoth and write documentation comments,
-with examples, is available in the ``doc`` directory in the source tree,
-obviously in Sphinx format and using the directive extension. Pre-built
+Documentation on how to install and configure Hawkmoth, and write documentation
+comments, with examples, is available in the ``doc`` directory in the source
+tree, obviously in Sphinx format and using the directive extension. Pre-built
 documentation `showcasing what Hawkmoth can do`_ is available at `Read the
 Docs`_.
 
@@ -58,11 +58,8 @@ You can install Hawkmoth from PyPI_ with::
   pip install hawkmoth
 
 You'll additionally need to install Clang and Python 3 bindings for it through
-your distro's package manager; they are not available via PyPI. You may also
-need to set ``LD_LIBRARY_PATH`` so that the Clang library can be found. For
-example::
-
-  export LD_LIBRARY_PATH=$(llvm-config --libdir)
+your distro's package manager; they are not available via PyPI. For further
+details, see the documentation.
 
 Alternatively, installation packages are available for:
 
@@ -93,7 +90,7 @@ Dependencies
 ------------
 
 - Python 3.4
-- Sphinx 1.8
+- Sphinx 3
 - Clang 6.0
 - Python 3 Bindings for Clang 6.0
 - sphinx-testing 1.0.0 (for development)

Documentation/hawkmoth/VERSION

-0.5
+0.7.0

Documentation/hawkmoth/__init__.py

@@ -52,7 +52,10 @@ class CAutoDocDirective(Directive):
         env = self.state.document.settings.env
 
         for (severity, filename, lineno, msg) in errors:
-            toprint = '{}:{}: {}'.format(filename, lineno, msg)
+            if filename:
+                toprint = '{}:{}: {}'.format(filename, lineno, msg)
+            else:
+                toprint = '{}'.format(msg)
 
             if severity.value <= env.app.verbosity:
                 self.logger.log(self._log_lvl[severity], toprint,
@@ -109,7 +112,7 @@ class CAutoDocDirective(Directive):
         return node.children
 
 def setup(app):
-    app.require_sphinx('1.8')
+    app.require_sphinx('3.0')
     app.add_config_value('cautodoc_root', app.confdir, 'env')
     app.add_config_value('cautodoc_compat', None, 'env')
     app.add_config_value('cautodoc_clang', None, 'env')

Documentation/hawkmoth/__main__.py

@@ -39,7 +39,10 @@ def main():
         print(doc)
 
     for (severity, filename, lineno, msg) in errors:
-        print('{}: {}:{}: {}'.format(severity.name,
-                                     filename, lineno, msg), file=sys.stderr)
+        if filename:
+            print('{}: {}:{}: {}'.format(severity.name,
+                                         filename, lineno, msg), file=sys.stderr)
+        else:
+            print('{}: {}'.format(severity.name, msg), file=sys.stderr)
 
 main()

Documentation/hawkmoth/parser.py

 # Copyright (c) 2016-2017 Jani Nikula <jani@nikula.org>
-# Copyright (c) 2018-2019 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
+# Copyright (c) 2018-2020 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
 # Licensed under the terms of BSD 2-Clause, see LICENSE for details.
 """
 Documentation comment extractor
@@ -34,6 +34,7 @@ Otherwise, documentation comments are passed through verbatim.
 """
 
 import enum
+import re
 import sys
 
 from clang.cindex import CursorKind, TypeKind
@@ -166,8 +167,26 @@ def _recursive_parse(comments, cursor, nest, compat):
         return _result(comment, cursor=cursor, fmt=fmt,
                        nest=nest, name=name, args=args, compat=compat)
 
-    elif cursor.kind == CursorKind.VAR_DECL:
-        fmt = docstr.Type.VAR
+    elif cursor.kind in [CursorKind.VAR_DECL, CursorKind.FIELD_DECL]:
+        if cursor.kind == CursorKind.VAR_DECL:
+            fmt = docstr.Type.VAR
+        else:
+            fmt = docstr.Type.MEMBER
+
+        # If this is an array, the dimensions should be applied to the name, not
+        # the type.
+        dims = ttype.rsplit(' ', 1)[-1]
+        if dims.startswith('[') and dims.endswith(']'):
+            ttype = ttype.rsplit(' ', 1)[0]
+            name = name + dims
+
+        # If this is a function pointer, or an array of function pointers, the
+        # name should be within the parenthesis as in (*name) or (*name[N]).
+        fptr_type = re.sub(r'\((\*+)(\[[^]]*\])?\)', r'(\1{}\2)'.format(name),
+                           ttype, count=1)
+        if fptr_type != ttype:
+            name = fptr_type
+            ttype = ''
 
         return _result(comment, cursor=cursor, fmt=fmt,
                        nest=nest, name=name, ttype=ttype, compat=compat)
@@ -193,9 +212,15 @@ def _recursive_parse(comments, cursor, nest, compat):
 
         # FIXME: Handle anonymous enumerators.
 
-        fmt = docstr.Type.TYPE
+        fmts = {CursorKind.STRUCT_DECL: docstr.Type.STRUCT,
+                CursorKind.UNION_DECL: docstr.Type.UNION,
+                CursorKind.ENUM_DECL: docstr.Type.ENUM}
+
+        fmt = fmts[cursor.kind]
+
+        # name may be empty for typedefs
         result = _result(comment, cursor=cursor, fmt=fmt,
-                         nest=nest, name=ttype, compat=compat)
+                         nest=nest, name=name if name else ttype, compat=compat)
 
         nest += 1
         for c in cursor.get_children():
@@ -210,12 +235,6 @@ def _recursive_parse(comments, cursor, nest, compat):
         return _result(comment, cursor=cursor, fmt=fmt,
                        nest=nest, name=name, compat=compat)
 
-    elif cursor.kind == CursorKind.FIELD_DECL:
-        fmt = docstr.Type.MEMBER
-
-        return _result(comment, cursor=cursor, fmt=fmt,
-                       nest=nest, name=name, ttype=ttype, compat=compat)
-
     elif cursor.kind == CursorKind.FUNCTION_DECL:
         # FIXME: check args against comment
         # FIXME: children may contain extra stuff if the return type is a
@@ -266,7 +285,8 @@ def clang_diagnostics(errors, diagnostics):
            4: ErrorLevel.ERROR}
 
     for diag in diagnostics:
-        errors.extend([(sev[diag.severity], diag.location.file.name,
+        filename = diag.location.file.name if diag.location.file else None
+        errors.extend([(sev[diag.severity], filename,
                         diag.location.line, diag.spelling)])
 
 # return a list of (comment, metadata) tuples

Documentation/hawkmoth/util/docstr.py

-# Copyright (c) 2016-2017 Jani Nikula <jani@nikula.org>
-# Copyright (c) 2018-2019 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
+# Copyright (c) 2016-2020 Jani Nikula <jani@nikula.org>
+# Copyright (c) 2018-2020 Bruno Santos <brunomanuelsantos@tecnico.ulisboa.pt>
 # Licensed under the terms of BSD 2-Clause, see LICENSE for details.
 """
 Documentation strings manipulation library
@@ -17,6 +17,9 @@ class Type(Enum):
     TEXT = auto()
     VAR = auto()
     TYPE = auto()
+    STRUCT = auto()
+    UNION = auto()
+    ENUM = auto()
     ENUM_VAL = auto()
     MEMBER = auto()
     MACRO = auto()
@@ -31,10 +34,13 @@ _doc_fmt = {
     Type.TEXT:       (0, '\n{text}\n'),
     Type.VAR:        (1, '\n.. c:var:: {ttype} {name}\n\n{text}\n'),
     Type.TYPE:       (1, '\n.. c:type:: {name}\n\n{text}\n'),
-    Type.ENUM_VAL:   (1, '\n.. c:macro:: {name}\n\n{text}\n'),
+    Type.STRUCT:     (1, '\n.. c:struct:: {name}\n\n{text}\n'),
+    Type.UNION:      (1, '\n.. c:union:: {name}\n\n{text}\n'),
+    Type.ENUM:       (1, '\n.. c:enum:: {name}\n\n{text}\n'),
+    Type.ENUM_VAL:   (1, '\n.. c:enumerator:: {name}\n\n{text}\n'),
     Type.MEMBER:     (1, '\n.. c:member:: {ttype} {name}\n\n{text}\n'),
     Type.MACRO:      (1, '\n.. c:macro:: {name}\n\n{text}\n'),
-    Type.MACRO_FUNC: (1, '\n.. c:function:: {name}({args})\n\n{text}\n'),
+    Type.MACRO_FUNC: (1, '\n.. c:macro:: {name}({args})\n\n{text}\n'),
     Type.FUNC:       (1, '\n.. c:function:: {ttype} {name}({args})\n\n{text}\n')
 }