Connecting a device

A study protocol names a Polar sensor only by its role. To collect data, the app binds the role to a physical sensor on the phone. CARP Mobile Sensing (CAMS) then connects to the sensor over Bluetooth Low Energy (BLE):

sequenceDiagram
    participant A as App
    participant C as CAMS
    participant M as PolarDeviceManager
    participant S as Polar sensor
    A->>M: requestPermissions()
    A->>M: set polarIdentifier
    A->>C: tryDeployment()
    C->>M: configure() and connect()
    M->>S: connect through the Polar BLE SDK
    S-->>M: connected, data types reported
    M-->>C: status connected
    Note over C: starts the Polar measures
    S-->>M: batches of samples

1. The app asks for the Bluetooth permissions and gives PolarDeviceManager the Polar ID of the sensor.
2. When CAMS deploys the study, it configures the device manager and calls connect().
3. The device manager connects to the sensor through the Polar BLE SDK. When the sensor has reported the data types it offers, the status becomes connected.
4. CAMS starts the Polar measures, and the sensor streams batches of samples.

Add the device to the protocol

Add a PolarDevice to the protocol as a connected device of the phone. Add the Polar measures to tasks that run on polar, not on phone:

final phone = Smartphone();
final polar = PolarDevice(roleName: 'Polar H10');

protocol
  ..addPrimaryDevice(phone)
  ..addConnectedDevice(polar, phone);

protocol.addTaskControl(
  ImmediateTrigger(),
  BackgroundTask(
    measures: [
      Measure(type: PolarSamplingPackage.HR),
      Measure(type: PolarSamplingPackage.ECG),
    ],
  ),
  polar,
);

PolarDevice takes these parameters:

Like every BLEDevice, PolarDevice also has the scan settings serviceUuids, minRssi, allowDuplicates and timeout, which CAMS does not use either. The protocol does not identify the physical sensor: you bind it on the phone.

Request Bluetooth permissions

CAMS does not ask for Bluetooth permissions by itself. Its automatic permission requests cover what the measures declare, and the Polar measures declare none. After you configure SmartPhoneClientManager, and before the sensor connects for the first time, get the PolarDeviceManager and call requestPermissions():

final polarManager =
    SmartPhoneClientManager().deviceController.getDeviceManager(
      PolarDevice.DEVICE_TYPE,
    ) as PolarDeviceManager;

if (!await polarManager.hasPermissions()) {
  await polarManager.requestPermissions();
}

requestPermissions() shows the system dialogs one at a time, through SmartPhoneClientManager().requestPermissions():

On Android, connect() fails without these permissions: the log says that the permissions required to connect are missing, and the status becomes disconnected. On iOS with CocoaPods, the Bluetooth request needs the PERMISSION_BLUETOOTH macro; see Installation.

Bind the sensor

PolarDeviceManager connects with the Polar ID: the identifier printed on the sensor, eight hexadecimal characters such as B5FC172F. It is also the last word of the sensor's Bluetooth name, for example Polar H10 B5FC172F or Polar Sense B36B5B21. The Polar ID is not the Bluetooth address, which the device manager does not use to connect.

Bind the sensor in one of two ways:

polarManager.polarIdentifier = 'B5FC172F';

polarManager.pair(
  bleAddress: '00:11:22:33:44:55',
  bleName: 'Polar H10 B5FC172F',
);

Connect to the sensor

When CAMS configures the deployment, it connects to the sensor if the device manager has a Polar ID and the Bluetooth permissions are granted. If you bind the sensor later, call connect() yourself:

final DeviceStatus status = await polarManager.connect();

connect() returns while the connection is being set up, usually with the status connecting. It does nothing while the device manager is connecting or connected, or before CAMS has configured it.

When the Polar BLE SDK reports the connection, the status becomes reconnected. The SDK then reports the heart rate feature and, on sensors with online streaming, the online streaming feature as ready. The device manager adds the data types of each feature to dataTypes, and the first one sets the status to connected.

CAMS then starts the tasks that run on the sensor. A measure whose data type is not in dataTypes at that moment does not start. The log then says that the Polar device does not support the data type.

To disconnect, call disconnect(). It pauses the Polar measures and tells the Polar BLE SDK to disconnect, so the SDK does not reconnect.

Monitor the connection

statusEvents emits each new DeviceStatus of the sensor:

polarManager.statusEvents.listen((status) => print('Polar: ${status.name}'));

The device manager reports these statuses:

These properties of the device manager describe the sensor and the connection:

Read the battery level

batteryLevel holds the last battery level that the sensor reported, in percent, and batteryEvents emits each new level:

polarManager.batteryEvents.listen((level) => print('Polar battery: $level%'));

The battery level is not a measure, so CAMS does not store it. There is no heartbeat measure for the sensor either: the CAMS heartbeat covers the phone only.

When CAMS registers the sensor with the deployment, the registration records the level as a battery charging state. It maps 0–10% to critical, 11–20% to low, 21–90% to normal and 91–100% to full.

Handle disconnections

When the link to the sensor is lost, the status becomes disconnecting. CAMS pauses the Polar measures, marks them to resume and sets the status to disconnected.

Unless the app called disconnect(), the Polar BLE SDK keeps trying to reconnect. When it succeeds, the status goes from connecting through reconnected to connected, and CAMS resumes the Polar measures. The data has a gap for the time the sensor was disconnected.

Use one sensor per phone

CAMS keeps one device manager per device type, so a phone connects to one Polar sensor at a time. Add one PolarDevice to a protocol, and bind each participant's phone to their own sensor.

Restore the binding after a restart

Each time the sensor connects, CAMS registers it with the deployment as a PolarDeviceRegistration. The registration holds the Polar ID, model, Bluetooth name, battery state and data types of the sensor. CAMS also stores the registration on the phone, with the deployment.

What happens after the app restarts depends on the deployment service:

Troubleshooting