rn-contact-tracing
rn-contact-tracing copied to clipboard
React Native Library For Contact Tracing Over BLE (Bluetooth Low Energy) To Fight COVID-19 Pandemic
RN-Contact-Tracing
WIP Library - Don't Use in Production
About
This is a react-native library for tracing close contact between 2 mobile devices by exchanging ephemeral tokens over BLE (Bluetooth Low Energy).
The library will do the following:
- Advertise message with specific service_uuid and generated ephemeral token
- Scan for for BLE signals with a specific service_uuid and store the relevant scanned data into local device storage
- Provide simple API for JS to init these tasks in background and retrieve the scanned tokens
- Integrate with a module that will provide ephemerally encrypted tokens (might be optional part of the lib)
There is a chance this lib will be updated after Google & Apple will release the full Contact Tracing API solution.
Challanges
- iOS limitation of using ble while the app in the background - link
- Estimate the distance between 2 devices without violating user's privacy, using the data we can send over the ble
Working plan
Functionality | Android | iOS |
---|---|---|
Scan in foreground | :white_check_mark: | :white_check_mark: |
Advertise in foreground | :white_check_mark: | :white_check_mark: |
Scan in background | :white_check_mark: | TODO |
Advertise in background | :white_check_mark: | TODO |
Save scanned data into local DB | :white_check_mark: | :white_check_mark: |
Return scanned data to JS | :white_check_mark: | :white_check_mark: |
Pass scannng & advertising configuration from JS (intervals..) | :white_check_mark: | :white_check_mark: |
Integration with tokens provider | TODO | TODO |
Tests | TODO | TODO |
Features for rssi calibration (GPS, Proximity) | WIP | TODO |
Getting started
Example Project
The Example project can be used as a reference of how to use the rn-contact-tracing API and as a helpful tool to fine-tune the scanning/advertising configuration
![](https://github.com/MohGovIL/rn-contact-tracing/raw/master/docs/example.gif)
How to run the example project
npm install
cd example/ios
pod install
For Android - npm run android
For iOS - npm run ios
In Android - Click on Request Location Permission button
Installation
yarn add rn-contact-tracing
or
npm install rn-contact-tracing --save
Android - Steps to manually link the library
android/settings.gradle
include ':rn-contact-tracing'
project(':rn-contact-tracing').projectDir = new File(rootProject.projectDir, '../node_modules/rn-contact-tracing/lib/android')
android/app/build.gradle
dependencies {
...
implementation project(":rn-contact-tracing")
}
android/app/src/main/.../MainApplication.java
On top, where imports are:
import moh.gov.il.specialble.SpecialBlePackage;
Add the RNLocationPackage
class to your list of exported packages.
@Override
protected List<ReactPackage> getPackages() {
return Arrays.asList(
List<ReactPackage> packages = new PackageList(this).getPackages();
...
packages.add(new SpecialBlePackage());
...
);
}
Supported Platforms
- iOS 10+
- Android API 21+
Methods
Summary
-
setConfig
-
getConfig
-
startBLEService
-
stopBLEService
-
startBLEScan
-
stopBLEScan
-
startBLEAdvertise
-
stopAdvertise
-
getScansByKey
-
getAllDevices
-
exportAllScansCsv
-
exportAllDevicesCsv
-
cleanDevicesDB
-
cleanScansDB
Details
setConfig(config)
SpecialBle.setConfig(config);
Sets configuration options that will be used in scanning & advertising tasks.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
config | object | Yes | See below. |
Supported options:
-
serviceUUID
- the ServiceUUID which identify the BLE broadcast you are going to advertise and scan for. -
scanDuration
- scanning duration in milisec -
scanInterval
- the time in milisec between every scan -
advertiseDuration
- advertising duration in milisec (up to 180000ms) -
advertiseInterval
- the time in milisec between every advertising -
token
- temporary token to advertise (for testing)
For Android
-
advertiseTXPowerLevel
- advertise TX power level docs -
scanMatchMode
- match mode for Bluetooth LE scan filters hardware match docs -
notificationTitle
- the title of the foreground service notification -
notificationContent
- the content of the foreground service notification
getConfig(callback)
SpecialBle.getConfig((config) => {
....
})
Gets the scanning & advertising configuration options that are currently defined in the library
startBLEService(config)
SpecialBle.startBLEService(config);
Starts BLE background task scanning for a specific - config is optional
stopBLEService()
SpecialBle.stopBLEService();
Stops the background service and all the tasks the service executing
startBLEScan(config)
SpecialBle.startBLEScan(config);
Starts BLE scanning in foreground - config is optional
stopBLEScan()
SpecialBle.stopBLEScan();
Starts BLE scanning
advertise(config)
SpecialBle.advertise(config);
Starts BLE advertising in foreground - config is optional
stopAdvertise()
SpecialBle.stopAdvertise();
Stops BLE advertising
getScansByKey(token, callback)
SpecialBle.getScansByKey(token, (scans) => {
...
})
Get list of scans events for a specific token, each object contains:
-
scan_id
- unique id -
scan_timestamp
- epoch time of the scan event in -
public_key
- token key -
scan_address
- scaned device address -
scan_rssi
- rssi strength -
scan_tx
- tx strength -
scan_protocol
- the protocol used to scan the data (currently GAP/GATT)
getAllDevices()
SpecialBle.getAllDevices((devices) => {
setDevices(devices)
})
Get list of unique devices that were scanned, each object contains:
-
device_first_timestamp
- epoch time of the first scan event -
device_last_timestamp
- epoch time of the last scan event -
public_key
- token key -
device_address
- scaned device address -
device_rssi
- rssi strongest value -
device_tx
- tx strongest value -
device_protocol
- the protocol used to scan the data (currently GAP/GATT)
exportAllScansCsv()
SpecialBle.exportAllScansCsv();
Export the full Scans events DB to csv file
exportAllDevicesCsv()
SpecialBle.exportAllDevicesCsv();
Export the full Devices DB to csv file
cleanDevicesDB()
SpecialBle.cleanDevicesDB();
Clear all scanned devices
cleanScansDB()
SpecialBle.cleanScansDB();
Clear all scans
Events from Native to JS
-
scanningStatus
- event can be true/false -
advertisingStatus
- event can be true/false -
foundDevice
- event has 2 params: {event.device_name, event.device_address} -
error
- {event.error_message}
Why did we build this lib?
Due to COVID-19 pandemic, several groups and health authorities released apps that will help to identify and notify people that are at risk of exposure.
Some of these apps are written with RN and based on tracking user location which is not enough such as Hamagen, and they willing to add BLE based functionality.
There are lots of great libs that expose ble functionality for RN, i.e react-native-ble-plx & react-native-ble-manager but we wanted reduce the amount of dependancies as much as possible and exectue very specfic BLE functionality in background.
In addition, we looked at several great apps written for the same purpose in native, but each one of them is not written in a way that we could use as a stand-alone library. OpenTrace) - includes the full business logic (UI..) that we don't want to use. DP^3T Project - include cryptography logic that we prefer to replace
Privacy (what do we advertise and save to DB)
TBD
References
- https://github.com/opentrace-community
- ....