Compare revisions

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

build/

/build/

/Documentation/output/

__pycache__/

*.pyc

*~

compile_commands.json

/tags

/release-*/

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

        # 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

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

[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

.. _bluetooth_card10_service:

Bluetooth Card10 Service

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

- Time update characteristic:

  UUID: ``42230201-2342-2342-2342-234223422342``

  write

  read and write no response

- Vibra characteristic:

  UUID: ``4223020f-2342-2342-2342-234223422342``

  write

  write no response

- Rockets characteristic:

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

  write

  read and write no response

- Background LED Bottom Left characteristic:

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

  write

  read and write no response

- Background LED Bottom Right characteristic:

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

  write

  read and write no response

- Background LED Top Right characteristic:

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

  write

  read and write no response

- Background LED Top Left characteristic:

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

  write

  read and write no reponse

- LEDS dim bottom characteristic:

  UUID: ``42230215-2342-2342-2342-234223422342``

  write

  write with response

- LEDs dim top characteristic:

  UUID: ``42230216-2342-2342-2342-234223422342``

  write

  write with response

- LEDs powersafe characteristic:

  UUID: ``42230217-2342-2342-2342-234223422342``

  write

  write no response

- Flashlight characteristic:

  UUID: ``42230218-2342-2342-2342-234223422342``

  write

  write no response

- Personal State characteristic:

  UUID: ``42230219-2342-2342-2342-234223422342``

  read and write with response

- LEDs above characteristic:

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

  write

  read and write no reponse

- Light sensor characteristic:

  UUID: ``422302f0-2342-2342-2342-234223422342``

  read

  read no response

Time update characteristic

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

The time update characteristic makes it possible to set the current time given in milliseconds after 1.1.1970 in the UTC timezone. The value is represented as a big endian ``uint64``

The time update characteristic makes it possible to set and get the current time given in milliseconds after 1.1.1970 in the UTC timezone. The value is represented as a big endian ``uint64``

- Thu Aug 15 19:40:45 UTC 2019 : ``0x0 0x0 0x1 0x6c 0x96 0xcb 0xf8 0xcc``

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:

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:

- enabled:   ``0x01``

- disabled:  ``0x00``

Personal state characteristic

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

This characteristic makes it possible to read and write the personal state.

It writes always as persistant and it gives feedback if the value is in range and your firmware support it.

- No State ``0x0000``

- No Contact ``0x0100``

- Chaos ``0x0200``

- ...

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

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

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

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

.. _bluetooth_file_transfer:

Bluetooth File Transfer

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

===== ===

  0   1-4

----- ---

  C   CRC

  C   CRC(*)

===== ===

CRC32 of the whole CHUNK packet including first byte, offset and payload.

FINISH:

=== ===

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.

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

cd "$(dirname "$0")"

sphinx-build -b html . ./output

if [ "$1" = "--open" ]; then

   xdg-open ./output/index.html

fi

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

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

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

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

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

project = "card10-firmware"

# 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

# }}}

# -- Options for Auto-Doc ---------------------------------------------------- {{{

autodoc_mock_imports = ["sys_display", "sys_leds", "ucollections", "urandom", "utime"]

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",

]

autodoc_member_order = "bysource"

# }}}

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

   ...

   (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

.. _epicardium_internal_apis:

Epicardium Internal APIs

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

Core OS APIs

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

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

Mutex

=====

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

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