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	✅	✅
Advertise in foreground	✅	✅
Scan in background	✅	TODO
Advertise in background	✅	TODO
Save scanned data into local DB	✅	✅
Return scanned data to JS	✅	✅
Pass scannng & advertising configuration from JS (intervals..)	✅	✅
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

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 com.wix.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

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

rn-contact-tracing-testing

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
docs		docs
example		example
lib		lib
node_modules		node_modules
scripts		scripts
LICENSE		LICENSE
README.md		README.md
babel.config.js		babel.config.js
index.js		index.js
metro.config.js		metro.config.js
package-lock.json		package-lock.json
package.json		package.json
react-native.config.js		react-native.config.js
rn-contact-tracing.podspec		rn-contact-tracing.podspec
yarn.lock		yarn.lock

License

edwardigates/rn-contact-tracing-testing

Folders and files

Latest commit

History

Repository files navigation

RN-Contact-Tracing

WIP Library - Don't Use in Production

About

Challanges

Working plan

Getting started

Example Project

How to run the example project

Installation

android/settings.gradle

android/app/build.gradle

android/app/src/main/.../MainApplication.java

Supported Platforms

Methods

Summary

Details

setConfig(config)

getConfig(callback)

startBLEService(config)

stopBLEService()

startBLEScan(config)

stopBLEScan()

advertise(config)

stopAdvertise()

getScansByKey(token, callback)

getAllDevices()

exportAllScansCsv()

exportAllDevicesCsv()

cleanDevicesDB()

cleanScansDB()

Events from Native to JS

Why did we build this lib?

Privacy (what do we advertise and save to DB)

References

rn-contact-tracing-testing

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

`android/settings.gradle`

`android/app/build.gradle`

`android/app/src/main/.../MainApplication.java`

`setConfig(config)`

`getConfig(callback)`

`startBLEService(config)`

`stopBLEService()`

`startBLEScan(config)`

`stopBLEScan()`

`advertise(config)`

`stopAdvertise()`

`getScansByKey(token, callback)`

`getAllDevices()`

`exportAllScansCsv()`

`exportAllDevicesCsv()`

`cleanDevicesDB()`

`cleanScansDB()`

Packages