Connecting a device

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

sequenceDiagram
    participant A as App
    participant C as CAMS
    participant M as ESenseDeviceManager
    participant E as eSense earbud
    A->>M: requestPermissions()
    A->>M: set bleName
    A->>C: tryDeployment()
    C->>M: configure() and connect()
    M->>E: scan for the name, then connect
    E-->>M: connected
    M-->>C: status connected
    Note over C: starts the eSense measures
    E-->>M: button and sensor events

1. The app asks for the Bluetooth permissions and gives ESenseDeviceManager the Bluetooth name of the earbud.
2. When CAMS deploys the study, it configures the device manager and calls connect().
3. The esense_flutter plugin scans for an earbud with that name and connects to it. The status becomes connected, and the device manager sets the sampling rate.
4. CAMS starts the eSense measures, and the earbud sends button and sensor events.

Add the device to the protocol

Add an ESenseDevice to the protocol as a connected device of the phone. Add the eSense measures to tasks that run on eSense, not on phone:

final phone = Smartphone();
final eSense = ESenseDevice(
  roleName: 'eSense',
  samplingRate: 20, // Hz
);

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

protocol.addTaskControl(
  ImmediateTrigger(),
  BackgroundTask(
    measures: [
      Measure(type: ESenseSamplingPackage.ESENSE_BUTTON),
      Measure(type: ESenseSamplingPackage.ESENSE_SENSOR),
    ],
  ),
  eSense,
);

ESenseDevice takes these parameters:

The sampling rate belongs to the device, not to a measure. The device manager sets it on the earbud when it connects. The earbud treats it as a hint: depending on the Bluetooth connection, motion events may arrive faster or slower.

CAMS does not check the value, so keep it from 1 to 100. In release builds on Android, a value outside this range starts no sampling.

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

Request Bluetooth permissions

Neither CAMS nor the esense_flutter plugin asks for Bluetooth permissions by itself. The automatic permission requests of CAMS cover what the measures declare, and the eSense measures declare none. After you configure SmartPhoneClientManager, and before the earbud connects for the first time, get the ESenseDeviceManager and call requestPermissions():

final eSenseManager =
    SmartPhoneClientManager().deviceController.getDeviceManager(
      ESenseDevice.DEVICE_TYPE,
    ) as ESenseDeviceManager;

if (!await eSenseManager.hasPermissions()) {
  await eSenseManager.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 Android 12 or later, the participant must allow precise location, because the plugin declares ACCESS_FINE_LOCATION. On iOS with CocoaPods, the Bluetooth request needs the PERMISSION_BLUETOOTH macro; see Installation.

Bind the earbud

ESenseDeviceManager connects by the Bluetooth name of the earbud, not by its address. Each left earbud has a unique name of the form eSense- and four digits, such as eSense-0332. The right earbud has no BLE interface.

To find the name, the eSense documentation suggests a Bluetooth scanner app, such as nRF Connect. Pairing the earbud in the phone's Bluetooth settings is not needed. According to the eSense user documentation, the BLE interface works without pairing, which only audio needs.

The earbud accepts one BLE connection at a time and may become unstable if several phones or apps connect to it. If the participant also uses the earbuds for audio, the eSense documentation recommends the right earbud for audio and the left earbud for motion data. The data rate may drop when one earbud handles motion data, the microphone and music at the same time.

Bind the earbud in one of two ways:

eSenseManager.bleName = 'eSense-0332';

eSenseManager.pair(bleAddress: '00:04:79:00:0D:04', bleName: 'eSense-0332');

Connect to the earbud

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

final DeviceStatus status = await eSenseManager.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.

The plugin scans for a device with exactly that name and then connects to it. On Android, the scan lasts 5 seconds: if the earbud is not found, the status becomes disconnected, and neither CAMS nor the plugin tries again. On iOS, connecting may take several seconds, and while the earbud is not found, the status stays connecting for up to about 83 minutes.

When the earbud is connected, the status becomes connected. The device manager then sets the sampling rate from samplingRate and starts reading the battery voltage every 2 minutes. CAMS starts the tasks that run on the earbud.

To disconnect, call disconnect(). It pauses the eSense measures and disconnects from the earbud.

Monitor the connection

statusEvents emits each new DeviceStatus of the earbud:

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

The device manager reports these statuses:

The eSense device manager does not use the statuses reconnected and disconnecting.

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

Read the battery level

The earbud reports its battery voltage, not a level. While the earbud is connected, the device manager reads the voltage every 2 minutes. It estimates the level in percent with a linear formula: (1.19 * voltage - 3.91) * 100.

batteryLevel holds the last estimate, and batteryEvents emits each new one:

eSenseManager.batteryEvents.listen((level) => print('eSense battery: $level%'));

The first estimate arrives 2 minutes after the connection. Because the formula is linear, the estimate can fall below 0 or rise above 100. The battery level is not a measure, so CAMS does not store it, and there is no heartbeat measure for the earbud.

Handle disconnections

When the earbud goes out of range or turns off, the status becomes disconnected. Neither CAMS nor the plugin connects to the earbud again by itself. Listen to statusEvents to detect a lost link.

Use one earbud per phone

CAMS keeps one device manager per device type, and the plugin connects to one earbud at a time. A phone therefore collects data from one eSense earbud. Add one ESenseDevice to a protocol.

Restore the binding after a restart

Each time the earbud connects, CAMS registers it with the deployment as a BLEDeviceRegistration, with the name of the earbud as its device ID. CAMS also stores the registration on the phone, with the deployment. What happens after the app restarts depends on the deployment service:

Troubleshooting