card10.rst

Bluetooth Card10 Service
========================

.. warning::
    The specification is still work in progress

The Card10 Service implemented a direct Hardware access of the card10.

BLE Service
-----------

The current draft uses following service specification:

- Service

  UUID: ``42230200-2342-2342-2342-234223422342``

- Time update characteristic:

  UUID: ``42230201-2342-2342-2342-234223422342``
  read and write no response

- Vibra characteristic:

  UUID: ``4223020f-2342-2342-2342-234223422342``
  write no response

- Rockets characteristic:

  UUID: ``42230210-2342-2342-2342-234223422342``
  read and write no response

- Background LED Bottom Left characteristic:

  UUID: ``42230211-2342-2342-2342-234223422342``
  read and write no response

- Background LED Bottom Right characteristic:

  UUID: ``42230212-2342-2342-2342-234223422342``
  read and write no response

- Background LED Top Right characteristic:

  UUID: ``42230213-2342-2342-2342-234223422342``
  read and write no response

- Background LED Top Left characteristic:

  UUID: ``42230214-2342-2342-2342-234223422342``
  read and write no reponse

- LEDS dim bottom characteristic:

  UUID: ``42230215-2342-2342-2342-234223422342``
  write with response

- LEDs dim top characteristic:

  UUID: ``42230216-2342-2342-2342-234223422342``
  write with response

- LEDs powersafe characteristic:

  UUID: ``42230217-2342-2342-2342-234223422342``
  write no response

- Flashlight characteristic:

  UUID: ``42230218-2342-2342-2342-234223422342``
  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``
  read and write no reponse

- Light sensor characteristic:

  UUID: ``422302f0-2342-2342-2342-234223422342``
  read no response

Time update characteristic
---------------------------------

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

Vibra characteristic
---------------------------------

The vibra characteristic makes it possible to let the card10 for given millisecound in a ``uint16`` vibrate.

- One secound: ``0xe803``

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:

======= ======= =======
   0       1       2
------- ------- -------
Rocket0 Rocket1 Rocket2
======= ======= =======

- 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 or read the current value.

Dataformat:

===== ======= =======
  0      1       2
----- ------- -------
 red   green   blue
===== ======= =======

- set led blue: ``0x0000ff``
- disabled:  ``0x000000``

LEDs dim <Position> characteristic
----------------------------------

The LEDs dim <Position> characteristic makes it possible to dim LEDs by position.
Just write a ``uint8`` between ``1`` and ``8``.

LEDs powersafe characteristic
---------------------------------

This characteristic makes it possible to set the LEDs in powersafe mode.
Even when set to zero, the RGB LEDs still individually consume ~1mA.
Powersave intelligently switches the supply power in groups.
This introduces delays in the magnitude of ~10µs, so it can be disabled for high speed applications such as POV

- enabled:   ``0x01``
- disabled:  ``0x00``

Flashlight characteristic
---------------------------------

This characteristic makes it possible to activate the flashlight.

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

Light sensor characteristic
---------------------------------

The light sensor characteristic makes it possible to read the current value of the light sensor by receiving a ``uint16``.
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