CARP Documentation

This page builds a small but complete study: a phone, a watch paired with it, and a task that collects motion, heart rate, battery and sound from the watch.

This assumes you have finished Install & Configure and added the companion watch app.

The complete example

import 'package:carp_core/carp_core.dart' hide Smartphone;
import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
import 'package:carp_aware_package/carp_aware_package.dart';

void main() async {
  // 1. Register the package before anything else.
  SamplingPackageRegistry().register(AppleWatchSamplingPackage());

  // 2. Create a protocol.
  final protocol = SmartphoneStudyProtocol(
    ownerId: 'owner@dtu.dk',
    name: 'Apple Watch Sensing Example',
  );

  // 3. The devices: a phone, and a watch connected to it.
  final phone = Smartphone();

  final watch = AppleWatchDevice(
    motionSamplingRate: 10,
    heartRateEnabled: true,
    batteryEnabled: true,
    audioEnabled: true,
    fileTransferInterval: const Duration(minutes: 15),
    transferMode: WatchTransferMode.incremental,
    backgroundSessionType: WatchBackgroundSessionType.microphone,
  );

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

  // 4. What to collect — added to the watch, not to the phone.
  protocol.addTaskControl(
    ImmediateTrigger(),
    BackgroundTask(measures: [
      Measure(type: AppleWatchSamplingPackage.MOTION),
      Measure(type: AppleWatchSamplingPackage.HEART_RATE),
      Measure(type: AppleWatchSamplingPackage.BATTERY),
      Measure(type: AppleWatchSamplingPackage.AMBIENT_NOISE),
      Measure(type: AppleWatchSamplingPackage.AUDIO_LABEL),
      Measure(type: AppleWatchSamplingPackage.DEVICE),
    ]),
    watch,
  );

  // 5. Deploy and start sampling.
  final client = SmartPhoneClientManager();
  await client.configure();
  final study = await client.addStudyFromProtocol(protocol);
  await client.tryDeployment(study.studyDeploymentId, study.deviceRoleName);
  client.resume();

  // 6. Everything collected — phone and watch alike — arrives here.
  client.measurements.listen(print);
}

Registration

SamplingPackageRegistry().register(AppleWatchSamplingPackage()) makes the nine watch measure types and the AppleWatchDevice known to CAMS.

Watch as a connected device

The watch is connected to the phone and the phone is the primary device that runs the study and uploads the data, and the watch is a peripheral that sends data to it.

protocol.addConnectedDevice(watch, phone);

Watch configuration

Sampling rates and which sensors run are properties of the AppleWatchDevice, not of the individual Measure. See Configuring the Watch.

Add measures

protocol.addTaskControl(ImmediateTrigger(), BackgroundTask(...), watch);

If you add the measures to phone, the files still arrive from the watch but nothing is converted into measurements.

Note

fileTransferInterval (why your data is 15 minutes old)

The watch buffers records locally and hands them over on a timer. With the default of 15 minutes, a measurement collected at 10:00 reaches your app around 10:15, together with everything else from that quarter hour.Lower the interval for faster data transfer but cause fast battery drain.

backgroundSessionType (how the watch keeps collecting)

watchOS suspends an app shortly after the wrist is lowered, unless it holds a background runtime session. The default, microphone, starts a silent capture session that keeps the watch app alive without registering a workout.The alternative, workout, runs longer and more reliably but appears in the participant’s fitness apps and affects their activity rings. This solution can result in app store rejection.

Status of the Watch

The AppleWatchDeviceManager holds the live state of the watch connection. Whether a watch is paired, if the companion app is installed, and how transfers are going:

final watchManager =
    DeviceController().getDeviceManager(AppleWatchDevice.DEVICE_TYPE)
        as AppleWatchDeviceManager;

// Ready to collect? (paired + companion app installed)
if (!watchManager.watchStatus.isAvailable) {
  print('Ask the participant to install the watch app.');
}

watchManager.watchStatusEvents.listen((status) => print(status));
watchManager.fileTransferEvents.listen((transfer) => print(transfer));

See Runtime State for details.

On the Watch App

Open app and press Start

watchOS will not run a freshly installed app in the background before its first launch.

Grant the permissions

HealthKit for heart rate, microphone for sound. The prompts appear on the watch.

Check the status

AppleWatchStatus reports paired: true, appInstalled: true, collecting: true.

First transfer

Wait up to fileTransferInterval to check for the first transfer. Press Send data to phone on the watch to skip the wait while testing.

Getting Started

The Watch App

Core Concepts

Reference

Quickstart

The complete example

Note

Status of the Watch

On the Watch App

​The complete example

​Note

​Status of the Watch

​On the Watch App

The complete example

Note

Status of the Watch

On the Watch App