Connecting a device

A study protocol names a Movisens 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 MovisensDeviceManager
    participant S as Movisens sensor
    A->>M: requestPermissions()
    A->>M: set deviceName
    A->>C: tryDeployment()
    C->>M: configure() and connect()
    M->>S: find the name, then connect
    M->>S: write the wearer's data
    M-->>C: status connected
    Note over C: starts the Movisens measures
    S-->>M: values about once a minute

1. The app asks for the Bluetooth permissions and gives MovisensDeviceManager the Bluetooth name of the sensor.
2. When CAMS deploys the study, it configures the device manager and calls connect().
3. The movisens_flutter plugin finds the sensor by its name and connects to it. The device manager writes the wearer's data to the sensor, and the status becomes connected.
4. CAMS starts the Movisens measures, and the sensor sends its values about once a minute.

Add the device to the protocol

Add a MovisensDevice with the wearer's data to the protocol as a connected device of the phone. Add the Movisens measures to tasks that run on movisens, not on phone:

final phone = Smartphone();
final movisens = MovisensDevice(
  sensorLocation: SensorLocation.RightSideHip,
  sex: Sex.Female,
  height: 168, // cm
  weight: 62, // kg
  age: 34,
);

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

protocol.addTaskControl(
  ImmediateTrigger(),
  BackgroundTask(
    measures: [Measure(type: MovisensSamplingPackage.TAP_MARKER)],
  ),
  movisens,
);

MovisensDevice takes these parameters:

The sensor uses the wearer's data to compute the metabolic equivalent of task (MET), MET levels and body position, so set it for each participant. SensorLocation has the values RightSideHip, Chest, RightWrist, LeftWrist, LeftAnkle, RightAnkle, RightThigh, LeftThigh, RightUpperArm, LeftUpperArm and LeftSideHip.

A MovisensDevice is always optional: isOptional is true, so the study can run without the device. Like every BLEDevice, it also has the scan settings serviceUuids, namePrefix, minRssi, allowDuplicates and timeout, which CAMS does not use. 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 Movisens measures declare none. After you configure SmartPhoneClientManager, and before the sensor connects for the first time, get the MovisensDeviceManager and call requestPermissions():

final manager = SmartPhoneClientManager().deviceController.getDeviceManager(
  MovisensDevice.DEVICE_TYPE,
) as MovisensDeviceManager;

if (!await manager.hasPermissions()) {
  await manager.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 location permission also needs the ACCESS_COARSE_LOCATION entry from Installation. On iOS, the system asks for Bluetooth access the first time flutter_blue_plus uses Bluetooth.

Bind the sensor

MovisensDeviceManager connects by the Bluetooth name of the sensor, not by its address. The name has the form MOVISENS Sensor <serial>, where <serial> is the five-digit serial number on the back of the sensor, such as MOVISENS Sensor 03348. The package binds by name because iOS gives each phone a different identifier for the same sensor.

Set deviceName, for example from a settings screen where the participant enters the serial number of the sensor:

manager.deviceName = 'MOVISENS Sensor 03348';

Setting the name does not change the status, so you can set it at any time, also before the study is deployed. pair(), which other Bluetooth devices use, does not set deviceName, and without a name the device manager cannot connect.

To bind another sensor, set deviceName to null and read device once before you set the new name. The device manager keeps the device it created for the first name, and drops it only when device is read while deviceName is null.

Update the wearer's data

The device manager writes the wearer's data to the sensor when it connects. To change the data, for example after the participant enters their age and weight in the app, change the configuration before you call connect():

final movisens = manager.configuration;
if (movisens != null) {
  movisens.age = 41;
  movisens.weight = 64; // kg
}

Connect to the sensor

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

final DeviceStatus status = await manager.connect();

connect() returns with the status connecting. It does nothing while the device manager is connecting or connected, or before CAMS has configured it. The movisens_flutter plugin looks for the sensor in this order:

1. A sensor with that name that is already connected to the app.
2. On Android, a sensor with that name that is bonded with the phone, that is, paired in the Android Bluetooth settings.
3. A 10-second scan, which connects to the first sensor with that name.

Once the sensor is connected and its services are known, the device manager writes the wearer's data to it. It also turns on battery notifications and follows the sensor's connection state. When that state is connected, the status becomes connected, and CAMS starts the tasks that run on the sensor.

To disconnect, call disconnect(). It pauses the Movisens measures and disconnects from the sensor.

Monitor the connection

statusEvents emits each new DeviceStatus of the sensor:

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

The device manager reports these statuses:

The Movisens device manager does not use the statuses paired, reconnected and disconnecting.

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:

// Battery level in percent, or null until the sensor reports it
final level = manager.batteryLevel;

The device manager turns on battery notifications only when movisens_flutter connects to the sensor without a scan, and it does not emit batteryEvents. The battery level is not a measure, so CAMS does not store it, and there is no heartbeat measure for the sensor.

Handle disconnections

The Movisens device manager does not reconnect after a lost link, and neither does movisens_flutter. While the device manager follows the sensor's connection state, a lost link sets the status to disconnected. Listen to statusEvents to detect it, and call connect() to connect again.

Use one sensor per phone

CAMS keeps one device manager per device type, so a phone connects to one Movisens sensor at a time. Add one MovisensDevice to a protocol.

Restore the binding after a restart

deviceName lives in the device manager's memory, and CAMS does not restore it. After the app restarts, set it again for local deployments and for deployments from CARP Web Services (CAWS) alike. Store the name in your app:

// After the study is deployed
manager.deviceName ??= await loadSensorName(); // from your app's own storage
if (manager.deviceName != null) await manager.connect();

Troubleshooting