Implementation of contact tracing with the Covid-19 Exposure Notification API by Apple and Google on an ESP32 (with ESP-IDF). More information about the Covid-19 Exposure Notification at Apple and Google. This is fully compatible with the official API and is meant for people without smartphone or without access to Apple/Google's implementation.
The main source (the Exposure Notification API) is also available in a separate branch in component.
This implementation fully covers the BLE part including the cryptography specifications needed and the exposure check.
The following acronyms will be used in code and comments:
Interface with display and input to
Due to limited storage, I made some calculations. I have fixed counting of TEKs (14 for two weeks), temporary beacons (1000, longest period for temp. storage is 20 minutes, so recognizing about 1000 different beacons in 20 minutes is possible) and exposure information (choose 500, this is like a limit of infected keys to be met). So the biggest limitation is to store beacons permanently after threshold of 5 minutes. That's what those calculations are for to check, if storage is enough for practical use.
overview of storage in bytes without permanent beacons: | size (B) | num | overall (B) | |
---|---|---|---|---|
TEK | 21 | 14 | 294 | |
Exposure Info | 20 | 500 | 10000 | |
temp. Beacon | 32 | 1000 | 32000 |
Additional 4 bytes counting for every type gives overall 42310B used without perm. beacons.
For now, a partition size of 2494464B will leave 2452154B free for met beacons which leads to a total storage of 76629 beacons. This gives the following table, where I added some lower boundaries to calculate with. | total beacons | aver. per day | aver. for 10 minute window |
---|---|---|---|
50000 | 3571 | 24 | |
70000 | 5000 | 34 | |
76629 | 5473 | 38 |
So on average it is possible to meet 38 (24 on a lower boundary) different devices inside of 10 minutes. I have no practical experience/numbers how many beacons are stored on average for a 14-days period in currently running ENA-Apps. But I think regarding the average is calculated for 24h (which is quite unpractical because of sleep and hours without meeting many people), the storage should be enough for the purpose of contact tracing.
For base functionality just an ESP32 is required, for full device M5StickC (PLUS) or for a custom device DS3231 RTC, SSD1306 Display and 7 buttons are required.
idf.py menuconfig
required
Component config -> Bluetooth -> [*] Bluetooth
Partition Table -> Partition table -> (x) Custom partition table CSV
Component config -> mbedTLS -> [*] HKDF algorithm (RFC 5869)
Serial flasher config -> Flash size -> (x) 4MB
ENA Interface -> ENA Interface device
important
If you ran into error region 'iram0_0_seg' overflowed by xxx bytes
you can try disabling WiFi IRAM optimization
Component config -> Wi-Fi -> WiFi IRAM speed optimization -> ( )
Component config -> Wi-Fi -> WiFi RX IRAM speed optimization -> ( )
recommended
Component config -> Bluetooth -> Bluetooth controller -> Scan Duplicate Type -> (X) Scan Duplicate By Device Address And Advertising Data
debug options
Component config -> Log output -> Default log verbosity -> (X) Debug
Exposure Notification API -> Storage -> [X] Dump storage
For ena-eke-proxy connection over SSL a valid certificate for used server under components/ena-eke-proxy/certs/cert.pem is required.
For my own proxy server, I have added a self signed cert for cwa-proxy.champonthis.de. For using, copy or rename components/ena-eke-proxy/certs/cwa-proxy.champonthis.de.pem to components/ena-eke-proxy/certs/cert.pem.
copy valid cert to components/ena-eke-proxy/certs/cert.pem
May flash partition table:
idf.py partition_table-flash -b 1500000
Build the project and flash it to the board, then run monitor tool to view serial output:
idf.py -p PORT flash -b 1500000 monitor
(Replace PORT with the name of the serial port to use.)
(To exit the serial monitor, type Ctrl-]
.)
The project is divided in different components. The main.c just wrap up all components. The Exposure Notification API is in ena module.
The ena module contains the main functions of eps-ena with Bluetooth scanning and advertising, storing data, handle beacons and check exposure.
This module is for connecting to an Exposure Key export proxy server. The server must provide daily (and could hourly) fetch of daily keys in binary blob batches with the following format
Key Data | Rolling Start Interval Number | Rolling Period | Days Since Onset Of Symptoms |
---|---|---|---|
16 bytes | 4 bytes | 4 bytes | 4 bytes |
Request URL is parametrized with {day-string},({hour} in hourly mode,) {page}, {page-size}.
Adds interface functionality for control and setup.
Interface input with 7 button input.
Interface input for M5StickC (PLUS) with 2 button input and accelerometer as axis input.
I²C driver for MPU6886 6-Axis IMU of M5StickC (PLUS).
Interface input for TTGO T-Wristband with 1 button input and accelerometer as axis input.
I²C driver for LSM9DS1 6-Axis IMU of TTGO T-Wristband.
General module for display and gfx.
I²C driver for a SSD1306 display, implementation of display module.
I²C driver for AXP192 PMU of M5StickC (PLUS).
SPI driver for a ST7735s display of M5StickC, implementation of display module.
SPI driver for a ST7789 display of M5StickC PLUS, implementation of display module
SPI driver for a ST7735 display of TTGO T-Wristband, implementation of display module.
General module for set/get time from RTC.
I²C driver for a DS3231 RTC, implementation of rtc module.
I²C driver for BM8563 of M5StickC (PLUS), implementation of rtc module.
Just start I²C driver.
Module to decode Exposure Key export. [Deprecated through ena-eke-proxy module]
Connection to German Exposure App (Corona Warn App) for download Exposure Key export (and maybe later report infection). [Deprecated through ena-eke-proxy module]
Nanopb for reading Protocol Buffers of Exposure Key export. Including already generated Headers from *.proto files. [Deprecated through ena-eke-proxy module]