patch-1 to master · card10 / firmware

Some changes are not shown.

For a faster browsing experience, only 78 of 1000 files are shown. Download one of the files below to see all changes.

.clang

+1
−1

Original line number
Diff line number
Diff line

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

+2
−1

Original line number
Diff line number
Diff line

build/

/build/

/Documentation/output/

__pycache__/

*.pyc

@@ -6,3 +6,4 @@ __pycache__/

*~

compile_commands.json

/tags

/release-*/

.gitlab-ci.yml

+15
−4

Original line number
Diff line number
Diff line

@@ -4,22 +4,33 @@ image: "derq3k/card10-build-env:20190806-195837Z-f95b541-dirty"

build:

    stage: build

    script:

        - ./bootstrap.sh

        - 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:

        - ./bootstrap.sh

        - 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

+9
−0

Original line number
Diff line number
Diff line

@@ -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

+424
−1

Original line number
Diff line number
Diff line

@@ -4,19 +4,430 @@ 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

#### 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

### Added

- ECG plotter tool (for desktop machines) which can plot ECG logs taken with card10.

- The `input()` Python function.

- Enabled the MicroPython `framebuf` module for a Pycardium-only framebuffer

  implementation.

- Added the `utime.ticks_us()` and `utime.ticks_ms()` functions for very

  accurate timing of MicroPython code.

- Added an option to use the right buttons for scrolling and the left one for

  selecting.  This will be made configurable in a future release.

- Made timezone configurable with a new `timezone` option in `card10.cfg`.

- Added a setting-menu to the ECG App.

### Changed

- Changed default timezone to CET.

- Made a few library functions callable without any parameters so they are

  easier to use.

- Refactored the `card10.cfg` config parser.

### Fixed

- Fixed the Pycardium delay implementation in preparation for features like

  button-interrupts.  Should also be more accurate now.

- Fixed the filter which is used by the ECG app.

- Fixed the display staying off while printing the sleep-messages.

- Improved the USB-Storage mode in the menu app.

- Fixed GPIO module not properly configuring a pin if both IN and ADC are given.

- Added missing documentation for `os.mkdir()` and `os.rename()`.

- Fixed all `-Wextra` warnings, including a few bugs.  Warnings exist for a reason!

### Removed

- Removed unnecessary out-of-bounds checks in display module.  Drawing outside

  the display is now perfectly fine and the pixels will silently be ignored.

## [v1.12] - 2019-10-19 - [Leek]

[Leek]: https://card10.badge.events.ccc.de/release/card10-v1.12-Leek.zip

### Added

- **USB Storage mode**!  You can now select 'USB Storage' in the menu and

  access card10's filesystem via USB.  No more rebooting into bootloader!

- LED feedback on boot.  If your display is broken, you can still see it doing

  something now.

- `./tools/pycard10.py --set-time` to set card10's system time from your host.

- 4 new functions in `utime` modules:

  * `set_time_ms()`

  * `set_unix_time_ms()`

  * `unix_time()`

  * `unix_time_ms()`

### Changed

- Updated BLE stack

- Refactored gfx API for drawing images (internal).

- Draw partially clipped primitives in all cases (Fixes menu scrolling

  animation).

- Fatal errors are now handled in a central 'panic' module.

### Fixed

- Make BLE interrupts higher priority than anything else to hopefully increase

  stability.

- Turn off BLE encryption after closing a connection.

- Fixed mainline bootloader being broken.

- Fixed menu entries being ordered by path instead of name.

- Fixed menu crashing without a message.

- Fixed QSTR build-system.

## [v1.11] - 2019-09-24 - [Karotte]

[Karotte]: https://card10.badge.events.ccc.de/release/card10-v1.11-Karotte.zip

### Added

- **Support for sleep-mode instead of full power-off.  This means the RTC now

  retains its state!**

- For debugger users: A GDB macro `task_backtrace` which allows to view

  backtraces of tasks which are currently swapped out.  Use like

  ```text

  (gdb) task_backtrace serial_task_id

  ...

  (gdb) task_backtrace dispatcher_task_id

  ...

  (gdb) task_backtrace ble_task_id

  ```

- BHI160 magnetometer sensor

- ESB API in Pycardium.

- Monotonic clock API

- New FOSS font ...

### Changed

- `Display.print()` uses a transparent background when printing with `bg == fg`.

- Try different crc16 module during build because different environments might

  have different ones installed.

- Improved ECG app, it can now blink on pulse and more!

- Improved BHI160 and BME680 apps.

### Fixed

- Fixed a regression which made it impossible to turn off the flashlight.

- Fixed CRT for l0dables not allowing to overwrite interrupt handlers.

- Fixed ECG App not closing the sensor on `KeyboardInterrupt`.

- Fixed a bug which made the power-button unresponsive when pressed during boot

  (Interrupts were getting ignored).

- Fixed `simple_menu.Menu.exit()` not actually working.

- Added a few missing locks in `leds` module.

- Added a workaround for BHI160 axis mapping not being applied in some cases.

- Added a critical-section in BLE stack initialization to prevent weird lock-ups.

- Fixed vibra module crashing when calling `vibra.vibrate()` while already running.

- Fixed sensor-sample overflow leading to I2C bus lockup.

## [v1.10] - 2019-09-05 21:42 - [JerusalemArtichoke]

[JerusalemArtichoke]: https://card10.badge.events.ccc.de/release/card10-v1.10-JerusalemArtichoke.zip

### Added

- **ws2812**: Connect Neopixels to the wristband GPIOs and make your card10

  even more colorful!

- DigiClk is now in the default prelude!

- High-pass filter and pulse detection in default ECG app.

- Actually added `uuid` module - it was not built into the firmware before,

  by accident.

- `leds.get_rgb()`: Get the current color of an LED.

- `leds.get_rocket()`: Get the current brightness of one of the rockets.

- `micropython.mem_use()` function.

- The analog-clock can now also set the time using the buttons.

### Changed

- **Pycardium**: Switched from `long-long` to `mpz` integer representation.

  This should resolve any issues with large numbers which had popped up so far.

- Refactored BME680 sensor interface.

- Made OpenOCD scripts work with more debuggers out of the box.

- Internal changes in preparation for button-interrupts.

### Fixed

- Backlight and Vibration motor were not reset when switching apps.

- Mismatch in default settings of the *Card10 Nickname* app.

- Fixed the PMIC ADC muxer not being properly reset to neutral after a

  measurement.

- Fixed wrong timezone offset calculation in `utime.time_ms()`.

- Fixed bug where `\` characters were not parsed as path separators.

- Fixed the alignment request check in our ELF l0der.

- Fixed a buffer-overflow in the config-parser.

## [v1.9] - 2019-08-28 23:23 - [IcebergLettuce]

[IcebergLettuce]: https://card10.badge.events.ccc.de/release/card10-v1.9-IcebergLettuce.zip

### Added

- `tools/pycard10.py`: Tool to interact with card10's serial connection and

  upload files directly:

  ```bash

  ./tools/pycard10.py path/to/python-script.py

  ```

- `epic_disp_print_adv` & `Display.print(font=...)`: Print with different

  fonts!  The following fonts are supported: `8px`, `12px`, `16px`, `20px`,

  and `24px`.

- **pycardium**: Support for RAW REPL mode.

- **bhi160**: Function to disable all sensors (`bhi160.disable_all_sensors()`).

- `ls_cmsis_dap`: A tool to enumerate CMSIS-DAP debuggers.

- Tons of new features to `simple_menu`: Timeout, scrolling of long texts,

  robustness against crashes, and proper exiting.

- `card10.cfg` config file which allows enabling *ELF* files.

- Analog read for wristband GPIOs.

### Changed

- Refactored *menu* and *personal-state* apps.

- `main.py` was moved into an app to allow easier reconfiguration of the

  default app.  The new `main.py` points to the "old" one so behavior is not

  changed.

- After a timeout, the menu will close and `main.py` will run again.

- BLE security updates.

- More detailed battery state display in nickname app.

- Improved ECG app.

### Removed

- Some unused font files.

### Fixed

- Fixed a regression which made the ECG app no longer work.

- Fixed card10 advertising support for AT-commands.

- Rectangles being one pixel too small.

## [v1.8] - 2019-08-27 11:38 - [HabaneroChilli]

[HabaneroChilli]: https://card10.badge.events.ccc.de/release/card10-v1.8-HabaneroChilli.zip

### Added

- API-call for direct light-sensor readout: `epic_light_sensor_read`.

- Pause mode in ECG-App.

- `bin` field in metatdata for an alternate entrypoint.

- `shell.nix`: Nix-Shell which installs patched OpenOCD and dependencies.

- Cool LED animation in default ECG app.

### Changed

- No longer require locking the display for setting the backlight.

## [v1.7] - 2019-08-24 21:48 - [Garlic]

[Garlic]: https://card10.badge.events.ccc.de/release/card10-v1.7-Garlic.zip

### Added

- **ESB**: Epic Serial Bus (Better than USB!), stability improvements of the

  USB module.  Preparation for mass-storage access in the Firmware.

- Enabled the Hardware Watchdog;  Card10 will reset itself if the firmware crashes

- Log messages when BLE is pairing / connected.

- The name of the offending app is printed to the serial console, if an app

  crashes the metatdata parser.

### Changed

- Improved log messages in cases of lock-contention.

- Menu will show an error message if a crash occurs.

### Fixed

- Fixed race-conditions in serial writes by using a queue.

- "Card10 Nickname" crashing if only `nickname.txt` exists.

- Lockup when debug prints are enabled.

- Delayed BHI160 startup a bit so the PMIC task can check the battery first.

- Relaxed the PMIC lock-timeouts so other task can take a little more time.

- Fixed off-by-one error in `gfx_line()`.

- Fixed the API interrupts sometimes getting stuck.

- Fixed binary building on MacOS.

- Fixed race-conditions in serial console prints by introducing a queue.

- Fixed API & MAX30001 mutexes being initialized late sometimes.

- Fixed wrong stripe width in bi flag.

## [v1.6] - 2019-08-23 20:30 - [Fennel]

@@ -137,7 +548,19 @@ 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.6...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

[v1.10]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.9...v1.10

[v1.9]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.8...v1.9

[v1.8]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.7...v1.8

[v1.7]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.6...v1.7

[v1.6]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.5...v1.6

[v1.5]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.4...v1.5

[v1.4]: https://git.card10.badge.events.ccc.de/card10/firmware/compare/v1.3...v1.4

Documentation/bluetooth/card10.rst

+73
−10

Original line number
Diff line number
Diff line

.. _bluetooth_card10_service:

Bluetooth Card10 Service

========================

@@ -28,27 +30,27 @@ The current draft uses following service specification:

- Rockets characteristic:

  UUID: ``42230210-2342-2342-2342-234223422342``

  write no response

  read and write no response

- Background LED Bottom Left characteristic:

  UUID: ``42230211-2342-2342-2342-234223422342``

  write no response

  read and write no response

- Background LED Bottom Right characteristic:

  UUID: ``42230212-2342-2342-2342-234223422342``

  write no response

  read and write no response

- Background LED Top Right characteristic:

  UUID: ``42230213-2342-2342-2342-234223422342``

  write no response

  read and write no response

- Background LED Top Left characteristic:

  UUID: ``42230214-2342-2342-2342-234223422342``

  write no reponse

  read and write no reponse

- LEDS dim bottom characteristic:

@@ -78,7 +80,7 @@ The current draft uses following service specification:

- LEDs above characteristic:

  UUID: ``42230220-2342-2342-2342-234223422342``

  write no reponse

  read and write no reponse

- Light sensor characteristic:

@@ -104,6 +106,9 @@ Rockets characteristic

The Rockets characteristic makes it possible to address every three rockets.

Just write there three byte array, one for evey rocket.

On read you get the current value of all three rockets.

Range is between 0 and 31 (``0x1f``) if send higher value it will set to max of 31.

Dataformat:

@@ -113,14 +118,14 @@ Dataformat:

Rocket0 Rocket1 Rocket2

======= ======= =======

- Enable only Rocket0:  ``0xff0000``

- Enable all rockets with 50% brightness: ``0x7f7f7f``

- Enable only Rocket0:  ``0x1f0000``

- Enable all rockets with 50% brightness: ``0x0f0f0f``

Background LED <Position> characteristic

----------------------------------------

The Background LEDs <Position> characteristic makes it possible to address the bottom LEDs by position.

Just write there three ``uint8`` for the rgb color.

Just write there three ``uint8`` for the rgb color or read the current value.

Dataformat:

@@ -170,7 +175,7 @@ It writes always as persistant and it gives feedback if the value is in range an

LEDs above characteristic

---------------------------------

This characteristic set every 11 leds on the top module at once.

This characteristic set or read the current value of every 11 leds on the top module at once.

By defining 11x rgb from left to right. You need also to set exchange a bigger MTU to use this feature.

- set a rainbow beginnig with red on the right edge: ``0xff0000ff8b00e8ff005dff0000ff2e00ffb900b9ff002eff5d00ffe800ffff008b``

@@ -182,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.rst0 → 100644

+31
−0

Original line number
Diff line number
Diff line

.. _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.rst0 → 100644

+99
−0

Original line number
Diff line number
Diff line

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

+2
−0

Original line number
Diff line number
Diff line

.. _bluetooth_file_transfer:

Bluetooth File Transfer

=======================

Documentation/bluetooth/nimble.rst0 → 100644

+115
−0

Original line number
Diff line number
Diff line

NimBLE

======

On the card10 the ARM Cordio-B50 stack is used, which is in a very early experimental state and has some incompatibilities with some smartphones.

Therefore some alternative stacks are evaluated, which meight be used as a replacement in the long term.

Here a stack called NimBLE is presented, which claims to be feature complete. Originally it has been developed for Mynewt, an open source embedded operating system by Apache (https://mynewt.apache.org/).

There is a working port for the ESP32 espressif ESP-IDF framework.

Like Epicardium, ESP-IDF is based on FreeRTOS. Therefore it can be used for evaluation purposes.

Getting NimBLE run on the ESP32

-------------------------------

Install required packages:

Ubuntu:

.. code-block:: shell-session

  sudo apt install git virtualenv python2.7 cmake

Arch:

.. code-block:: shell-session

  sudo pacman -S git python2 python2-virtualenv cmake

Download and extract xtensa ESP32 compiler:

.. code-block:: shell-session

  wget https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_2_0-esp32-2018r1-linux-amd64.tar.xz

  tar -xf xtensa-esp32-elf-gcc8_2_0-esp32-2018r1-linux-amd64.tar.xz

Clone esp-idf:

.. code-block:: shell-session

    git clone https://github.com/espressif/esp-idf.git

Add xtensa and ESP-IDF path to $PATH:

bash shell:

.. code-block:: shell-session

  export IDF_PATH=$PWD/esp-idf

  export PATH=${PATH}:$PWD/xtensa-esp32-elf/bin:$PWD/esp-idf/tools

fish shell:

.. code-block:: shell-session

  set -gx IDF_PATH $PWD/esp-idf

  set -gx PATH $PWD/xtensa-esp32-elf/bin/ $PWD/esp-idf/tools $PATH

Create a python2.7 virtualenv:

.. code-block:: shell-session

  cd esp-idf

  virtualenv -p /usr/bin/python2.7 venv

Enter the virtualenv:

bash shell:

.. code-block:: shell-session

  . venv/bin/activate

fish shell:

.. code-block:: shell-session

  . venv/bin/activate.fish

Init git submodules and install all required Python packages:

.. code-block:: shell-session

  git submodule update --init --recursive

  pip install -r requirements.txt

Now you are ready to build!

The following steps assume that your ESP32 is connected via USB and

is accessible via /dev/ttyUSB0. This meight be different on your system.

There are a few NimbLE examples which can be used for playing around:

Build a BLE server example (host mode):

---------------------------------------

.. code-block:: shell-session

  cd examples/bluetooth/nimble/bleprph

  idf.py -p /dev/ttyUSB0 flash monitor

This will build and flash the example to the ESP32 and instantly listens on /dev/ttyUSB0 serial port.

After the flashing process the ESP32 will anounce itself as **nimble-bleprph** device via BLE.

Build a BLE client example (central mode):

------------------------------------------

.. code-block:: shell-session

  cd examples/bluetooth/nimble/blecent

  idf.py -p /dev/ttyUSB0 flash monitor

This will build and flash the example to the ESP32 and instantly listens on /dev/ttyUSB0 serial port.

After the flashing process the ESP32 creates a GATT client and performs passive scan, it then connects to peripheral device if the device advertises connectability and the device advertises support for the Alert Notification service (0x1811) as primary service UUID.

Documentation/bluetooth/overview.rst0 → 100644

+43
−0

Original line number
Diff line number
Diff line

.. _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
−0

Original line number
Diff line number
Diff line

@@ -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.rst0 → 100644

+69
−0

Original line number
Diff line number
Diff line

.. _card10_cfg:

card10.cfg

==========

Certain high-level settings can be configured using a filed named ``card10.cfg``.  It is accessed from the :ref:`usb_file_transfer` of the bootloader.  Once you are in this mode and have mounted the badge's flash device, you can either create or update a file named ``card10.cfg``.

The file is in the well-known INI-style format, with one setting per line. For instance, if there were an option called ``answer_to_life``, you could set it by writing the following line in the ``card10.cfg`` file:

.. code-block:: text

   answer_to_life = 42

Don't forget to unmount the filesystem before rebooting your badge after changing any setting.

Syntax and Types

----------------

Lines that start with a ``#`` character are ignored.

Any other line will have the overall syntax of ``option_name = option_value``, with spaces around the ``=`` character optional.

Option names are internal to card10 and described below. Each option has a defined type.

========= ===========

Type name Description

========= ===========

Boolean   A true/false value. ``1`` or ``true`` is true, ``0`` or ``false`` is false. Example: ``foo = true``.

String    An unquoted string value of maximum 20 bytes. Values longer than 20 bytes are trimmed. Example: ``foo = bar``.

Integer   A signed 32-bit integer in base 10. Example: ``foo = 42`` or ``bar = -1337``.

Float     A single-precision (32-bit) floating-point number in base 10. Example: ``foo = 13.37``.

========= ===========

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``

------------------ ---------- -----------

``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

+59
−1

Original line number
Diff line number
Diff line

@@ -3,6 +3,8 @@ import subprocess

import sys

import time

import sphinx.util.logging

from docutils import nodes

from docutils.parsers import rst

# If extensions (or modules to document with autodoc) are in another directory,

# add these directories to sys.path here. If the directory is relative to the

@@ -13,7 +15,6 @@ sys.path.insert(0, os.path.abspath("./"))

logger = sphinx.util.logging.getLogger("card10/conf.py")

# -- Project information -----------------------------------------------------

project = "card10-firmware"

@@ -47,6 +48,23 @@ todo_include_todos = True

# This pattern also affects html_static_path and html_extra_path.

exclude_patterns = ["output", "Thumbs.db", ".DS_Store", "hawkmoth"]

# -- Extensions -------------------------------------------------------------- {{{

class ColorExample(rst.Directive):

    has_content = False

    required_arguments = 1

    optional_arguments = 0

    option_spec = {}

    def run(self):

        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 ------------------------------------------------- {{{

# The Read the Docs theme is available from

@@ -90,10 +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",

]

@@ -123,3 +148,36 @@ except ImportError as e:

# -- Sphinx Setup ------------------------------------------------------------

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

+7
−1

Original line number
Diff line number
Diff line

@@ -115,6 +115,12 @@ command to soft-reset card10.

   ...

   (gdb)

.. 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-both.gdb,  flash-epicardium.gdb,  flash-pycardium.gdb``

.. warning::

   If you are used to use ``mon reset halt``, be aware that the card10 prototypes

   do not connect the reset line to the debugger. OpenOCD is configured to only do

Documentation/epicardium/internal.rst0 → 100644

+8
−0

Original line number
Diff line number
Diff line

.. _epicardium_internal_apis:

Epicardium Internal APIs

========================

Core OS APIs

------------

.. c:autodoc:: epicardium/os/core.h

Documentation/epicardium/mutex.rst0 → 100644

+136
−0

Original line number
Diff line number
Diff line

Mutex

=====

Ontop of FreeRTOS, we have our own mutex implementation.  **Never use the

FreeRTOS mutexes directly!  Always use this abstraction layer instead**.  This

mutex implementation tries to make reasoning about program flow and locking

behavior easier.  And most importantly tries to help with debugging possible

dead-locks.

Design

------

There are a few guiding design principles:

- Mutexes can only be used from tasks, **never** from interrupts!

- Timers can use mutexes, but only with :c:func:`mutex_trylock`, **never** with

  :c:func:`mutex_lock` (Because they are not allowed to block).

- Locking can *never* fail (if it does, we consider this a fatal error ⇒ panic).

- No recursive locking.

- An unlock can only occur from the task which previously acquired the mutex.

- An unlock is only allowed if the mutex was previously acquired.

For a more elaborate explanation of the rationale behind these rules take a

look at the :ref:`mutex-design-reasons`.

Definitions

-----------

.. c:autodoc:: epicardium/os/mutex.h

.. _mutex-design-reasons:

Reasons for this Design

-----------------------

Locking can *never* fail

^^^^^^^^^^^^^^^^^^^^^^^^

This might seem like a bold claim at first but in the end, it is just a matter

of definition and shifting responsibilities.  Instead of requiring all code to

be robust against a locking attempt failing, we require all code to properly

lock and unlock their mutexes and thus never producing a situation where

locking would fail.

Because all code using any of the mutexes is contained in the Epicardium

code-base, we can - *hopefully* - audit it properly behaving ahead of time and

thus don't need to add code to ensure correctness at runtime.  This makes

downstream code easier to read and easier to reason about.

History of this project has shown that most code does not properly deal with

locking failures anyway: There was code simply skipping the mutexed action on

failure, code blocking a module entirely until reboot, and worst of all: Code

exposing the locking failure to 'user-space' (Pycardium) instead of retrying.

This has lead to spurious errors where technically there would not need to be

any.

Only from tasks

^^^^^^^^^^^^^^^

Locking a mutex from an ISR, a FreeRTOS software timer or any other context

which does not allow blocking is complicated to do right.  The biggest

difficulty is that a task might be holding the mutex during execution of such a

context and there is no way to wait for it to release the mutex.  This requires

careful design of the program flow to choose an alternative option in such a

case.  A common approach is to 'outsource' the relevant parts of the code into

an 'IRQ worker' which is essentially just a task waiting for the IRQ to wake it

up and then attempts to lock the mutex.

If you absolutely do need it (and for legacy reasons), software timers *can*

lock a mutex using :c:func:`mutex_trylock` (which never blocks).  I strongly

recommend **not** doing that, though.  As shown above, you will have to deal

with the case of the mutex being held by another task and it is very well

possible that your timer will get starved of the mutex because the scheduler

has no knowledge of its intentions.  In most cases, it is a better idea to use

a task and attempt locking using :c:func:`mutex_lock`.

.. todo::

   We might introduce a generic IRQ worker queue system at some point.

No recursive locking

^^^^^^^^^^^^^^^^^^^^

Recursive locking refers to the ability to 'reacquire' a mutex already held by

the current task, deeper down in the call-chain.  Only the outermost unlock

will actually release the mutex.  This feature is sometimes implemented to

allow more elegant abstractions where downstream code does not need to know

about the mutexes upstream code uses and can still also create a larger region

where the same mutex is held.

But exactly by hiding the locking done by a function, these abstractions make

it hard to trace locking chains and in some cases even make it impossible to

create provably correct behavior.  As an alternative, I would suggest using

different mutexes for the different levels of abstraction.  This also helps

keeping each mutex separated and 'local' to its purpose.

Only unlock from the acquiring task

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Because of the above mentioned mutex locking semantics, there should never be a

need to force-unlock a forgein mutex.  Even in cases of failures, all code

should still properly release all mutexes it holds.  One notable exceptions is

``panic()``\s which will abort all ongoing operations anyway.

Only unlock once after acquisition

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Justified with an argument of robustness, sometimes the :c:func:`mutex_unlock`

call is written in a way that allows unlocking an already unlocked mutex.  But

robustness of downstream code will not really be improved by the upstream API

dealing with arguably invalid usage.  For example, this could encourage

practices like unlocking everything again at the end of a function "just to be

sure".

Instead, code should be written in a way where the lock/unlock pair is

immediately recognizable as belonging together and is thus easily auditable to

have correct locking behavior.  A common pattern to help with readability in

this regard is the *Single Function Exit* which looks like this:

.. code-block:: cpp

   int function()

   {

           int ret;

           mutex_lock(&some_mutex);

           ret = foo();

           if (ret) {

                   /* Return with an error code */

                   ret = -ENODEV;

                   goto out_unlock;

           }

           ret = bar();

           if (ret) {

                   /* Return the return value from foo */

                   goto out_unlock;

           }

           ret = 0;

   out_unlock:

           mutex_unlock(&some_mutex);

           return ret;

   }

Documentation/hawkmoth/README.rst0 → 100644

+118
−0

Original line number
Diff line number
Diff line

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.txtdeleted100644 → 0

+0
−121

Original line number
Diff line number
Diff line

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

+1
−1

Original line number
Diff line number
Diff line

0.4

0.7.0

Documentation/hawkmoth/__init__.py

+5
−2

Original line number
Diff line number
Diff line

@@ -52,7 +52,10 @@ class CAutoDocDirective(Directive):

        env = self.state.document.settings.env

        for (severity, filename, lineno, msg) in errors:

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

Compare revisions

Source

Target

Files

Some changes are not shown.

.clang

.gitignore

.gitlab-ci.yml

.gitmodules

CHANGELOG.md

Documentation/bluetooth/card10.rst

Documentation/bluetooth/ecg.rst

Documentation/bluetooth/ess.rst

Documentation/bluetooth/file-transfer.rst

Documentation/bluetooth/nimble.rst

Documentation/bluetooth/overview.rst

Documentation/build-docs.sh

Documentation/card10-cfg.rst

Documentation/conf.py

Documentation/debugger.rst

Documentation/epicardium/internal.rst

Documentation/epicardium/mutex.rst

Documentation/hawkmoth/README.rst

Documentation/hawkmoth/README.txt

Documentation/hawkmoth/VERSION

Documentation/hawkmoth/init.py