.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

.gitignore

-build/
+/build/
 /Documentation/output/
 __pycache__/
 *.pyc

.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

@@ -4,3 +4,12 @@
 [submodule "lib/micropython/micropython-lib"]
 	path = lib/micropython/micropython-lib
 	url = https://github.com/micropython/micropython-lib.git
+[submodule "lib/crypto/tiny-AES-c"]
+	path = lib/crypto/tiny-AES-c
+	url = https://github.com/kokke/tiny-AES-c
+[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

@@ -6,6 +6,205 @@ 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
+#### For Users
+- A feature to allow setting the main app on-device.
+- Added compatibility to BLE 5.0 capable phones (including iPhones).
+- Added a pairing dialog in the BLE app. card10 is only visible when BLE app is
+  active.
+- 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
+#### 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.
+- Fixed bug which triggered reboot loops.
+- 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]
+[Okra]: https://card10.badge.events.ccc.de/release/card10-v1.15-Okra.zip
+
+### Added
+- Show a fault screen on the display when epicardium panics
+
+### Fixed
+- Prevent MicroPython garbage collector from delting ISRs
+- Fix race conditoin when reading/writing BLE MAC address at boot.
+- Fix locking of LEDs.
+- Fix bug which only allowed to have a single file open at any time.
+- Put all chips into standby when going to sleep
+- Misc BLE fixes
+
+
+## [v1.14] - 2019-12-29 - [Nettle]
+[Nettle]: https://card10.badge.events.ccc.de/release/card10-v1.14-Nettle.zip
+
+### Added
+- Scripts for profiling card10 (`tools/poor-profiler`)
+- `tools/ecg2wav.py` script for displaying ECG logs in audio programs like
+  Audacity.
+
+### Changed
+- Ported hardware-locks & bhi160 to new mutex API
+- The menu now tries to display apps without a `metadata.json` as well, if
+  possible.
+
+### Fixed
+- Fixed an unguarded i2c bus transaction which caused strange issues all
+  around.
+- Fixed copying large files freezing card10.
+- Fixed BHI160 initialization interrupt behavior.
+- Properly disable BHI160 if an error occurs during init.
+- Fixed bhi160 app overflowing sensor queues.
+- Fixed neopixel driver not properly writing the first pixel the first
+  time.
+- Fixed some l0dables crashing because the SysTick timer interrupt was not
+  disabled.
+
+
 ## [v1.13] - 2019-12-09 - [Mushroom]
 [Mushroom]: https://card10.badge.events.ccc.de/release/card10-v1.13-Mushroom.zip
 
@@ -349,7 +548,12 @@ 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.13...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
 [v1.12]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.11...v1.12
 [v1.11]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.10...v1.11

Documentation/bluetooth/card10.rst

+.. _bluetooth_card10_service:
+
 Bluetooth Card10 Service
 ========================
 
@@ -185,3 +187,61 @@ The light sensor characteristic makes it possible to read the current value of t
 The range of this sensor is between 0 (``0x0``) and 400 (``0x9001``).
 
 - reading of ``0x0e00`` means **14**
+
+Access via btgatt-client
+---------------------------------
+
+Accessing services from a linux system is possible via ``btgatt-client``. The inbuilt gatt client of ``bluetoothctl`` as well as ``libgatt`` were tested, but struggled with the card10's BLE stack.
+
+**Example**:
+
+.. code-block::
+
+    # pairing the card10:
+
+    $ bluetoothctl
+    [bluetooth]# power on
+    [bluetooth]# scan on
+    [bluetooth]# pair CA:4D:10:xx:xx:xx     #replace xx:xx:xx with scan result
+    # if this query doesn't appear, remove and re-pair:
+    [agent] Confirm passkey ###### (yes/no): [CHG] Device CA:4D:10:xx:xx:xx Name: card10
+    [card10-xxxxxx]# disconnect CA:4D:10:xx:xx:xx
+
+    # using a service:
+
+    $ btgatt-client -d CA:4D:10:xx:xx:xx
+    # wait until services have been discovered, may take a minute
+    [GATT client]# write-value 0x0926 31 31 31
+
+    # if this error appears remove and re-pair:
+    [GATT client]# Device disconnected: Software caused connection abort
+
+
+ARM Cordio Sources
+------------------
+
+The BLE stack is based on the ARM Cordio stack. This stack has been developed by a 3rd party and was bought by ARM and open-sourced.
+
+There are many copies of it floating around on the Internet and some are more up to date than others. To keep track here is a list:
+ - mbed
+    - mbed has a reasonably up to date version of the stack in their GitHub repository.
+    - It is scattered below the CORDIO directories in https://github.com/ARMmbed/mbed-os/tree/master/features/FEATURE_BLE/targets
+    - ble-profiles are not included. mbed has written their own adaptation layer to interface with the stack and implements profiles in C++
+ - Ambiq Suite SDK
+    - Can be found here: https://github.com/sparkfun/AmbiqSuiteSDK/tree/master/third_party/exactle
+    - Patches on top might be here: https://support.ambiqmicro.com/hc/en-us/categories/115000239012-Software
+    - Reasonably up to date
+    - Intersting part: has their own FreeRTOS integration (but apparently on older WSF)
+    - BLE 5.1 (?)
+ - Packetcraft
+    - Apparently tasked with maintaining the stack in general
+    - Most up to date version
+    - https://github.com/packetcraft-inc/cordio
+    - Apparently developing (security) fixes, distributing them to customers, but not applying them to master: https://github.com/ARMmbed/mbed-os/commit/c92777311578eb003b4546c4e5e6f2c1f8ba3c84
+    - BLE 5.1
+ - Maxim
+    - Distributed via Maxim Toolchain Installation tool, no repository available
+    - Contains software implementation of the base band
+    - ble-host and ble-profiles might be compatible with the one directly from Packetcraft
+    - Developing their own low-power enhancements
+    - BLE 5.0

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

@@ -34,10 +34,36 @@ Float     A single-precision (32-bit) floating-point number in base 10. Example:
 Supported options
 -----------------
 
-=============== ========== ===========
-Option name     Type       Description
-=============== ========== ===========
-``execute_elf`` Boolean    Allow running of binary :ref:`l0dables`. These files can be nefarious, so this option is off by default.
---------------- ---------- -----------
-``timezone``    String     Timezone for card10; must be of format ``[+-]HHMM``.  Examples: ``+0800``, ``-0200``
-=============== ========== ===========
+================== ========== ===========
+Option name        Type       Description
+================== ========== ===========
+``execute_elf``    Boolean    Allow running of binary :ref:`l0dables`. These files can be nefarious, so this option is off by default.
+------------------ ---------- -----------
+``timezone``       String     Timezone for card10; must be of format ``[+-]HHMM``.  Examples: ``+0800``, ``-0200``
+------------------ ---------- -----------
+``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"
@@ -62,6 +61,8 @@ class ColorExample(rst.Directive):
         color = self.arguments[0]
         html_text = '<div style="width: 30px;height: 30px;background: {};border: black 1px solid;border-radius: 15px;"></div>'
         return [nodes.raw("", html_text.format(color), format="html")]
+
+
 # }}}
 
 # -- Options for HTML output ------------------------------------------------- {{{
@@ -107,12 +108,17 @@ 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",
     "urandom",
     "utime",
 ]
@@ -143,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/debugger.rst

@@ -56,7 +56,7 @@ the following commands:
 .. warning::
     Make sure ``CMSIS-DAP Compliant Debugger`` is set to **yes (auto)** after
     running ``./configure`` (if it is not, you might need to install ``libhidapi-dev``
-    (Ubuntu)). If you get errors making the documentation you can 
+    (Ubuntu)). If you get errors making the documentation you can
     ``touch doc/openocd.info`` to skip it and continue with ``make``.
 
 .. code-block:: shell-session
@@ -118,7 +118,7 @@ command to soft-reset card10.
 .. note::
    You will also find the following self-describing gdb files in the firmware
    root directory, which do not require additional arguments:
-   ``flash-all.gdb,  flash-bootloader.gdb,  
+   ``flash-all.gdb,  flash-bootloader.gdb,
    flash-both.gdb,  flash-epicardium.gdb,  flash-pycardium.gdb``
 
 .. warning::

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.rst

+Hawkmoth - Sphinx Autodoc for C
+===============================
+
+Hawkmoth is a minimalistic Sphinx_ `C Domain`_ autodoc directive extension to
+incorporate formatted C source code comments written in reStructuredText_ into
+Sphinx based documentation. It uses Clang Python Bindings for parsing, and
+generates C Domain directives for C API documentation, and more. In short,
+Hawkmoth is Sphinx Autodoc for C.
+
+Hawkmoth aims to be a compelling alternative for documenting C projects using
+Sphinx, mainly through its simplicity of design, implementation and use.
+
+.. _Sphinx: http://www.sphinx-doc.org
+
+.. _C Domain: http://www.sphinx-doc.org/en/stable/domains.html
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+Example
+-------
+
+Given C source code with rather familiar looking documentation comments::
+
+  /**
+   * Get foo out of bar.
+   */
+  void foobar();
+
+and a directive in the Sphinx project::
+
+  .. c:autodoc:: filename.c
+
+you can incorporate code documentation into Sphinx. It's as simple as that.
+
+You can document functions, their parameters and return values, structs, unions,
+their members, macros, function-like macros, enums, enumeration constants,
+typedefs, variables, as well as have generic documentation comments not attached
+to any symbols.
+
+Documentation
+-------------
+
+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`_.
+
+.. _showcasing what Hawkmoth can do: https://hawkmoth.readthedocs.io/en/latest/examples.html
+
+.. _Read the Docs: https://hawkmoth.readthedocs.io/
+
+Installation
+------------
+
+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. For further
+details, see the documentation.
+
+Alternatively, installation packages are available for:
+
+* `Arch Linux`_
+
+In Sphinx ``conf.py``, add ``hawkmoth`` to ``extensions``, and point
+``cautodoc_root`` at the source tree. See the extension documentation for
+details.
+
+.. _PyPI: https://pypi.org/project/hawkmoth/
+
+.. _Arch Linux: https://aur.archlinux.org/packages/?K=hawkmoth
+
+Development and Contributing
+----------------------------
+
+Hawkmoth source code is available on GitHub_. The development version can be
+checked out via ``git`` using this command::
+
+  git clone https://github.com/jnikula/hawkmoth.git
+
+Please file bugs and feature requests as GitHub issues. Contributions are
+welcome both as emailed patches to the mailing list and as pull requests.
+
+.. _GitHub: https://github.com/jnikula/hawkmoth
+
+Dependencies
+------------
+
+- Python 3.4
+- Sphinx 3
+- Clang 6.0
+- Python 3 Bindings for Clang 6.0
+- sphinx-testing 1.0.0 (for development)
+
+These are the versions Hawkmoth is currently being developed and tested
+against. Other versions might work, but no guarantees.
+
+License
+-------
+
+Hawkmoth is free software, released under the `2-Clause BSD License`_.
+
+.. _2-Clause BSD License: https://opensource.org/licenses/BSD-2-Clause
+
+Contact
+-------
+
+IRC channel ``#hawkmoth`` on freenode_.
+
+Mailing list hawkmoth@freelists.org. Subscription information at the `list home
+page`_.
+
+.. _freenode: https://freenode.net/
+
+.. _list home page: https://www.freelists.org/list/hawkmoth

Documentation/hawkmoth/README.txt

-Hawkmoth - Sphinx Autodoc for C
-===============================
-
-Hawkmoth is a minimalistic Sphinx_ `C Domain`_ autodoc directive extension to
-incorporate formatted C source code comments written in reStructuredText_ into
-Sphinx based documentation. It uses Clang Python Bindings for parsing, and
-generates C Domain directives for C API documentation, and more. In short,
-Hawkmoth is Sphinx Autodoc for C.
-
-Hawkmoth aims to be a compelling alternative for documenting C projects using
-Sphinx, mainly through its simplicity of design, implementation and use.
-
-.. _Sphinx: http://www.sphinx-doc.org
-
-.. _C Domain: http://www.sphinx-doc.org/en/stable/domains.html
-
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-
-Example
--------
-
-Given C source code with rather familiar looking documentation comments::
-
-  /**
-   * Get foo out of bar.
-   */
-  void foobar();
-
-and a directive in the Sphinx project::
-
-  .. c:autodoc:: filename.c
-
-you can incorporate code documentation into Sphinx. It's as simple as that.
-
-You can document functions, their parameters and return values, structs, unions,
-their members, macros, function-like macros, enums, enumeration constants,
-typedefs, variables, as well as have generic documentation comments not attached
-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 `showcasing what Hawkmoth can do`_ is available at `Read the
-Docs`_.
-
-.. _showcasing what Hawkmoth can do: https://hawkmoth.readthedocs.io/en/latest/examples.html
-
-.. _Read the Docs: https://hawkmoth.readthedocs.io/
-
-Installation
-------------
-
-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)
-
-Alternatively, installation packages are available for:
-
-* `Arch Linux`_
-
-In Sphinx ``conf.py``, add ``hawkmoth`` to ``extensions``, and point
-``cautodoc_root`` at the source tree. See the extension documentation for
-details.
-
-.. _PyPI: https://pypi.org/project/hawkmoth/
-
-.. _Arch Linux: https://aur.archlinux.org/packages/?K=hawkmoth
-
-Development and Contributing
-----------------------------
-
-Hawkmoth source code is available on GitHub_. The development version can be
-checked out via ``git`` using this command::
-
-  git clone https://github.com/jnikula/hawkmoth.git
-
-Please file bugs and feature requests as GitHub issues. Contributions are
-welcome both as emailed patches to the mailing list and as pull requests.
-
-.. _GitHub: https://github.com/jnikula/hawkmoth
-
-Dependencies
-------------
-
-- Python 3.4
-- Sphinx 1.8
-- Clang 6.0
-- Python 3 Bindings for Clang 6.0
-- sphinx-testing 1.0.0 (for development)
-
-These are the versions Hawkmoth is currently being developed and tested
-against. Other versions might work, but no guarantees.
-
-License
--------
-
-Hawkmoth is free software, released under the `2-Clause BSD License`_.
-
-.. _2-Clause BSD License: https://opensource.org/licenses/BSD-2-Clause
-
-Contact
--------
-
-IRC channel ``#hawkmoth`` on freenode_.
-
-Mailing list hawkmoth@freelists.org. Subscription information at the `list home
-page`_.
-
-.. _freenode: https://freenode.net/
-
-.. _list home page: https://www.freelists.org/list/hawkmoth

Documentation/hawkmoth/VERSION

-0.4
+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')