CARP Documentation

The main purpose of the CARP Mobile Sensing framework is to allow for extension with domain-specific studies, triggers, tasks, measures, probes, and data types. This is done by implementing classes that inherit from the (abstract) classes in the library.

Add Triggers

Define custom triggers to be used as part of a study protocol.

Add Sampling Packages

Introduce new measures, probes, data classes, and optional device managers.

Add Data Managers

Support custom storage or upload of measurements via new endpoints and data managers.

Add Data Transformers

Creating data and privacy transformer schemas for data re-formatting and privacy control.

JSON serialization

Extension to CAMS often rely on serialization to/from JSON - this applies for triggers, measures, sampling schemas, data, etc. CAMS relies on polymorphic serialization as supported by the carp_serializable package, which is an extension to the standard json_serializable provided in Dart. Support for polymorphic JSON serialization implies four steps when designing your classes:

Define a serializable class

Extend from Serializable and annotate the class:

@JsonSerializable(includeIfNull: false, explicitToJson: true)
class FreeMemory extends Data {
  ...
}

JSON serializable methods

Implement the three JSON serializable methods:

  @override
  Function get fromJsonFunction => _$FreeMemoryFromJson;
  factory FreeMemory.fromJson(Map<String, dynamic> json) =>
      FromJsonFactory().fromJson<FreeMemory>(json);
  @override
  Map<String, dynamic> toJson() => _$FreeMemoryToJson(this);

Registration

Register the class’s fromJsonFunction in the FromJsonFactory, e.g. in the onRegister() callback function of a sampling package:

  @override
  void onRegister() {
    FromJsonFactory()
        .register(FreeMemory()));
  } 

Running the code generator

When all JSON classes have been implemented, the final step is to generate the JSON serialization helper classes. These can be generated using build_runner, by running the following command in the root of your Flutter project:

dart run build_runner build --delete-conflicting-outputs

This will generate the necessary .g.dart files.

See the carp_serializable and json_serializable packages for details on JSON serialization.

Adding new triggers

Triggers are a central part of a StudyProtocol and CAMS allows creating your own triggers and add them to the framework. This is done by the following steps:

Define one or more new Triggers.
Define a TriggerExecutor for each new trigger.
Define and register a TriggerFactory that knows how to create the correct TriggerExecutor based on a specific trigger.

Define a new trigger

Any trigger should extend the TriggerConfiguration class and implement domain-specific fields that configure this trigger. In the example below, we have defined a RemoteTrigger that listens to resources on a server identified by a URI, and triggers when this resource is available.

/// A trigger that triggers based on event from a remote server.
@JsonSerializable(includeIfNull: false, explicitToJson: true)
class RemoteTrigger extends TriggerConfiguration {
  RemoteTrigger({
    required this.uri,
    this.interval = const Duration(minutes: 10),
  }) : super();

  /// The URI of the resource to listen to.
  String uri;

  /// How often should we check the server?
  Duration interval;

  @override
  Function get fromJsonFunction => _$RemoteTriggerFromJson;
  factory RemoteTrigger.fromJson(Map<String, dynamic> json) =>
      FromJsonFactory().fromJson<RemoteTrigger>(json);
  @override
  Map<String, dynamic> toJson() => _$RemoteTriggerToJson(this);
}

Trigger configurations are part of a study protocol and hence needs to be serializable to/from JSON.

Define a trigger executor

Each trigger needs a corresponding TriggerExecutor to execute the trigger on sampling runtime. An example of a RemoteTriggerExecutor executor is shown below. Every Executor in CAMS can implement runtime behavior on init, start, stop, restart, and dispose. The abstract class TriggerExecutor is a convenient class to use for the implementation of a trigger executor since it has default implementations of all methods. Hence, you only need to override the lifecycle methods you need something to happen. Typically — and as shown below — the most relevant method to override is the onStart() method which is called when sensing is started. In this method, you will implement the trigger logic. In the RemoteTriggerExecutor the trigger starts a periodic timer that regularly checks the resources specified by the URI in the trigger configuration. If there is a resource available, it triggers by calling the onTrigger() callback method.

/// Executes a [RemoteTrigger], i.e. check if there is a resource on
/// the server and triggers if so.
class RemoteTriggerExecutor extends TriggerExecutor<RemoteTrigger> {
  final client = Client();

  @override
  Future<bool> onStart() async {
    // Set up a periodic timer to look for a resource at the specified URI
    timer = Timer.periodic(configuration!.interval, (_) async {
      var response = await client.get(
        Uri.parse(Uri.encodeFull(configuration!.uri)),
      );

      if (response.statusCode == HttpStatus.ok) {
        // If there is a resource at the specified URI, then trigger this executor
        onTrigger();
      }
    });
    return true;
  }
}

Note that this trigger executor is very simplistic and does not cover any edge cases, like exceptions from network errors.

Define and register a trigger factory

The last step is to define a TriggerFactory that knows how to map triggers to their executors on runtime. An example of the RemoteTriggerFactory is shown below. Note that a factory can handle multiple triggers, as defined in the set of trigger types it supports. The main method of the factory is the create method that can create the correct trigger executor for the specified trigger.

/// A [TriggerFactory] for remote triggers.
class RemoteTriggerFactory implements TriggerFactory {
  @override
  Set<Type> types = {
    // Note that this factory might support several types of remote triggers
    RemoteTrigger,
  };

  @override
  void onRegister() {
    // When registering this factory add the triggers to the JSON serialization
    FromJsonFactory().registerAll([RemoteTrigger(uri: 'uri')]);
  }

  @override
  TriggerExecutor<TriggerConfiguration> create(TriggerConfiguration trigger) =>
      switch (trigger) {
        RemoteTrigger _ => RemoteTriggerExecutor(),
        _ => ImmediateTriggerExecutor(),
      };
}

Note that in the onRegister() callback function, the trigger configurations are added to the FromJsonFactory(). This allows trigger configurations defined in a study protocol to be serialized to/from JSON.

The last step is to register this trigger factory with CAMS. This is done by calling:

ExecutorFactory().registerTriggerFactory(RemoteTriggerFactory());

This is typically done when initializing CAMS before any protocol is made or loaded.

Adding new sampling capabilities

If you want to add new sensing capabilities you would basically create a new SamplingPackage. A sampling package implements the following classes:

SamplingPackage - the overall specification of what measures this package can collect.
SamplingSchema - specifies sampling configurations.
Data - specifies the data model of the measures collected.
Probe - implements the runtime of data collection.
DeviceManager - specifies how an external device is managed (if any).

Not all sampling packages use an external device and are hence simpler to implement since they can extend the default SmartphoneDeviceManager. In the following, we will use the DeviceSamplingPackage as an example of a sampling package that does not use any external device.

Sampling package

The first step is that your new sampling package should implement the SamplingPackage interface:

class DeviceSamplingPackage extends SmartphoneSamplingPackage {
  /// Measure type for collection of basic device information 
  static const String DEVICE_INFORMATION =
      '${CarpDataTypes.CARP_NAMESPACE}.deviceinformation';

  /// Measure type for collection of free physical and virtual memory.
  static const String FREE_MEMORY =
      '${CarpDataTypes.CARP_NAMESPACE}.freememory';

  /// Measure type for collection of battery level and charging status.
  static const String BATTERY_STATE =
      '${CarpDataTypes.CARP_NAMESPACE}.batterystate';

  /// Measure type for collection of screen events (on/off/unlocked).
  static const String SCREEN_EVENT =
      '${CarpDataTypes.CARP_NAMESPACE}.screenevent';

  /// Measure type for collection of the time zone of the device.
  static const String TIMEZONE = '${CarpDataTypes.CARP_NAMESPACE}.timezone';

  @override
  DataTypeSamplingSchemeMap get samplingSchemes =>
      DataTypeSamplingSchemeMap.from([
        DataTypeSamplingScheme(CamsDataTypeMetaData(
          type: DEVICE_INFORMATION,
          displayName: "Device Information",
          timeType: DataTimeType.POINT,
          dataEventType: DataEventType.ONE_TIME,
        )),
        DataTypeSamplingScheme(
            CamsDataTypeMetaData(
              type: FREE_MEMORY,
              displayName: "Free Memory",
              timeType: DataTimeType.POINT,
            ),
            IntervalSamplingConfiguration(
              interval: const Duration(minutes: 1),
            )),
        DataTypeSamplingScheme(CamsDataTypeMetaData(
          type: BATTERY_STATE,
          displayName: "Battery State",
          timeType: DataTimeType.POINT,
        )),
        DataTypeSamplingScheme(CamsDataTypeMetaData(
          type: SCREEN_EVENT,
          displayName: "Screen Events",
          timeType: DataTimeType.POINT,
        )),
        DataTypeSamplingScheme(CamsDataTypeMetaData(
          type: TIMEZONE,
          displayName: "Device Timezone",
          timeType: DataTimeType.POINT,
          dataEventType: DataEventType.ONE_TIME,
        )),
      ]);

  @override
  void onRegister() {
    FromJsonFactory().registerAll([
      DeviceInformation(),
      BatteryState(),
      FreeMemory(),
      ScreenEvent(),
      Timezone(''),
    ]);
  }

  @override
  Probe? create(String type) => switch (type) {
        DEVICE_INFORMATION => DeviceProbe(),
        FREE_MEMORY => MemoryProbe(),
        BATTERY_STATE => BatteryProbe(),
        TIMEZONE => TimezoneProbe(),
        SCREEN_EVENT => (Platform.isAndroid) ? ScreenProbe() : null,
        _ => null,
      };
}

The measures supported by this package are listed as static strings, such as FREE_MEMORY defining the type dk.cachet.carp.freememory. The DataTypeSamplingSchemeMap defines the configuration of each measure, by specifying the CamsDataTypeMetaData for each measure and its sampling configuration (if needed). The onRegister() method is called when the package is registered and in this case registers the data classes for JSON serialization. Finally, the create() method is called when a probe is to be created and returns the right probe based on the measure type.

A note on Permissions - the CamsDataTypeMetaData allows the specification of what OS-specific permissions are needed to collect a measure.In the measures used as an example above, no permissions are required. However, in the SensorSamplingPackage, the activityRecognition permission is required in order to collect step counts, as shown in the samplingSchemes of that package.

Sampling configurations

Default sampling configurations can be specified as part of samplingSchemes, like the IntervalSamplingConfiguration specified for the FREE_MEMORY measure type above. There are several built-in sampling configurations available:

Sampling configuration	Description
`PersistentSampling Configuration`	Persistently saves the state of data sampling for continuous long-running sampling behavior across app restart.
`HistoricSampling Configuration`	Configures retrospective or backfilled collection of historical data.
`IntervalSampling Configuration`	Samples at a fixed interval (delay) between measurements.
`PeriodicSampling Configuration`	Samples in periodic windows using both interval and duration settings.

But you can write your own sampling configuration tailored to a specific measure and hence how data should be collected in a probe. As an example of how to write a sampling configuration, the IntervalSamplingConfiguration is shown below:

/// A sampling configuration that allows configuring the time [interval] in
/// between subsequent measurements.
@JsonSerializable(includeIfNull: false, explicitToJson: true)
class IntervalSamplingConfiguration extends PersistentSamplingConfiguration {
  /// Sampling interval (i.e., delay between sampling).
  Duration interval;

  IntervalSamplingConfiguration({required this.interval}) : super();

  @override
  Function get fromJsonFunction => _$IntervalSamplingConfigurationFromJson;
  @override
  Map<String, dynamic> toJson() => _$IntervalSamplingConfigurationToJson(this);
  factory IntervalSamplingConfiguration.fromJson(Map<String, dynamic> json) =>
      FromJsonFactory().fromJson(json) as IntervalSamplingConfiguration;
}

Note that a sampling configuration must extend from one of the sampling configuration types (e.g., SamplingConfiguration or PersistentSamplingConfiguration). Sampling configurations can be part of a study protocol where you can override the sampling configuration of a measure.

Data

Next, you should define the package-specific Data that the package collects. Here is the example of the collected FreeMemory data item;

/// Holds information about free memory on the phone.
@JsonSerializable(includeIfNull: false, explicitToJson: true)
class FreeMemory extends Data {
  static const dataType = DeviceSamplingPackage.FREE_MEMORY;

  /// Amount of free physical memory in bytes.
  int? freePhysicalMemory;

  /// Amount of free virtual memory in bytes.
  int? freeVirtualMemory;

  FreeMemory([this.freePhysicalMemory, this.freeVirtualMemory]) : super();

  @override
  Function get fromJsonFunction => _$FreeMemoryFromJson;
  factory FreeMemory.fromJson(Map<String, dynamic> json) => FromJsonFactory().fromJson(json) as FreeMemory;
  @override
  Map<String, dynamic> toJson() => _$FreeMemoryToJson(this);
}

A small note on Privacy; it is possible to add privacy protection of collected data to the package. See Creating Data Privacy for how to do this.

Probes

The next step is to implement probes for each measure type. A probe collects the data and returns it as Measurement. The abstract Probe interface defines a probe and how to implement probes. But in order to create your own probes, CAMS has a set of predefined, abstract probes to extend from:

Probe base class	Description
`MeasurementProbe`	Collects one measurement and then stops.
`IntervalProbe`	Collects measurements at a regular interval.
`StreamProbe`	Listens continuously to a stream of measurements.
`PeriodicStreamProbe`	Listens to a stream during periodic windows defined by interval and duration.
`BufferingPeriodicProbe`	Buffers data for a period and emits a derived measurement.
`BufferingInterval StreamProbe`	Buffers an underlying stream and emits a measurement on regular intervals.
`BufferingPeriodic StreamProbe`	Buffers an underlying stream for a fixed period and then emits a measurement.

The DeviceProbe is an example of a simple MeasurementProbe that collects device information about the phone using the device_info_plus plugin and map this to a DeviceInformation data and returns a Measurement with this data. As shown below, since the DeviceProbe extends MeasurementProbe it just need to implement the getMeasurement() method, which returns the device info mapped to a DeviceInformation data item.

/// A probe that collects the device info about this device.
class DeviceProbe extends MeasurementProbe {
  @override
  Future<Measurement?> getMeasurement() async =>
      Measurement.fromData(DeviceInformation(
        deviceData: DeviceInfo().deviceData,
        platform: DeviceInfo().platform,
        deviceId: DeviceInfo().deviceID,
        deviceName: DeviceInfo().deviceName,
        deviceModel: DeviceInfo().deviceModel,
        deviceManufacturer: DeviceInfo().deviceManufacturer,
        operatingSystem: DeviceInfo().operatingSystemName,
        hardware: DeviceInfo().hardware,
      ));
}

The ScreenProbe is an example of a StreamProbe that collects screen activity data. This probe implements the stream property, which maps screen events from the screen_state plugin to ScreenEvent data objects, which again is wrapped in a measurement using the Measurement.fromData factory.

/// A probe collecting screen events:
///  - SCREEN ON
///  - SCREEN OFF
///  - SCREEN UNLOCK
/// which are stored as a [ScreenEvent].
class ScreenProbe extends StreamProbe {
  Screen screen = Screen();

  @override
  Stream<Measurement> get stream => screen.screenStateStream.map(
    (event) => Measurement.fromData(ScreenEvent.fromScreenStateEvent(event)),
  );
}

Device manager

If a sampling package handles (i.e., collects data from) an external device or service, then it should be able to specify what type of device it supports and provide corresponding DeviceManager and DeviceConfiguration classes. For example, in the eSense sampling package, the ESenseSamplingPackage implements the following two methods:

class ESenseSamplingPackage implements SamplingPackage {
  final DeviceManager _deviceManager =
      ESenseDeviceManager(ESenseDevice.DEVICE_TYPE);

  // other parts of the package omitted

  @override
  List<Permission> get permissions => [];

  @override
  String get deviceType => ESenseDevice.DEVICE_TYPE;

  @override
  DeviceManager get deviceManager => _deviceManager;
}

The ESenseDevice device configuration describes how an eSense device is to be configured:

/// A [DeviceConfiguration] for an eSense device used in a [StudyProtocol].
@JsonSerializable(fieldRename: FieldRename.none, includeIfNull: false)
class ESenseDevice extends BLEDevice<BLEDeviceRegistration> {
  /// The type of an eSense device.
  static const String DEVICE_TYPE =
      '${CamsDevice.CAMS_DEVICE_NAMESPACE}.ESenseDevice';

  /// The default role name for an eSense device.
  static const String DEFAULT_ROLE_NAME = 'eSense';

  /// The sampling rate in Hz of getting sensor data from the device.
  int samplingRate;

  ESenseDevice({
    super.roleName = ESenseDevice.DEFAULT_ROLE_NAME,
    super.isOptional = true,
    this.samplingRate = 10,
  });

  @override
  Function get fromJsonFunction => _$ESenseDeviceFromJson;
  factory ESenseDevice.fromJson(Map<String, dynamic> json) =>
      FromJsonFactory().fromJson(json) as ESenseDevice;
  @override
  Map<String, dynamic> toJson() => _$ESenseDeviceToJson(this);
}

Note that since a device configuration can be part of a study protocol, it needs to support JSON serialization. The device manager should implement the DeviceManager interface. CAMS has a set of predefined device managers which can be extended, including the SmartphoneDeviceManager, ServiceManager, HardwareDeviceManager, and BLEDeviceManager. Since the eSense sensor is a BLE device, the ESenseDeviceManager extends the BLEDeviceManager class.

/// A [DeviceManager] for the eSense device.
///
/// Note that eSense use the [bleName] (and not the BLE address) for connecting to it.
/// Typically of the form `eSense-xxxx`.
class ESenseDeviceManager
    extends BLEDeviceManager<ESenseDevice, BLEDeviceRegistration> {
  Timer? _batteryTimer;
  StreamSubscription<ESenseEvent>? _batterySubscription;
  double? _voltageLevel;
  final StreamController<int> _batteryEventController =
      StreamController.broadcast();

  ESenseManager? _manager;

  /// The eSense device handler.
  /// Only available after [bleName] has been set.
  ESenseManager? get manager =>
      bleName != null ? _manager ??= ESenseManager(bleName!) : _manager = null;

  @override
  String? get displayName => bleName;

  /// An estimate of the battery level based on the voltage level.
  @override
  int? get batteryLevel => (_voltageLevel != null)
      ? ((1.19 * _voltageLevel! - 3.91) * 100).toInt()
      : null;

  @override
  Stream<int> get batteryEvents => _batteryEventController.stream;

  ESenseDeviceManager(super.type, {super.configuration});

  @override
  bool get canConnect => bleName != null;

  @override
  BLEDeviceRegistration createRegistration() => BLEDeviceRegistration(
    deviceDisplayName: bleName,
    isConnected: isConnected,
    batteryChargingState: batteryLevel != null
        ? HardwareDeviceRegistration.parseBatteryLevel(batteryLevel!)
        : BatteryChargingState.unknown,
    bleAddress: bleName ?? 'Unknown eSense Device',
    bleName: bleName,
  );

  @override
  Future<DeviceStatus> onConnect() async {
    try {
      // listen for connection events
      manager?.connectionEvents.listen((event) async {
        switch (event.type) {
          case ConnectionType.connected:
            status = DeviceStatus.connected;

            await manager?.setSamplingRate(configuration?.samplingRate ?? 10);

            // when connected, listen for battery events
            _batterySubscription = manager!.eSenseEvents.listen((event) {
              if (event is BatteryRead) {
                _voltageLevel = event.voltage;
                if (batteryLevel != null) {
                  _batteryEventController.add(batteryLevel!);
                }
              }
            });

            // set up a timer that asks for the voltage level
            _batteryTimer = Timer.periodic(const Duration(minutes: 2), (_) {
              if (status == DeviceStatus.connected) {
                manager?.getBatteryVoltage();
              }
            });
            break;
          case ConnectionType.unknown:
            status = DeviceStatus.unknown;
            break;
          case ConnectionType.device_found:
            status = DeviceStatus.connecting;
            break;
          case ConnectionType.device_not_found:
          case ConnectionType.disconnected:
            status = DeviceStatus.disconnected;
            _voltageLevel = null;
            _batteryTimer?.cancel();
            _batterySubscription?.cancel();
            break;
        }
      });

      // try to connect to the manager with the [bleName]
      manager?.connect();
    } catch (error) {
      warning(
        '$runtimeType - Error connecting to eSense device: $bleName - $error',
      );
      return DeviceStatus.disconnected;
    }

    return DeviceStatus.connecting;
  }

  @override
  Future<bool> onDisconnect() async => await manager?.disconnect() ?? false;
}

Once the eSense device manager is in place, the eSense probes (button and IMU sensor) can be implemented as stream probes.

/// Collects eSense button pressed events. It generates an [ESenseButton]
/// every time the button is pressed or released.
class ESenseButtonProbe extends StreamProbe {
  @override
  ESenseDeviceManager get deviceManager =>
      super.deviceManager as ESenseDeviceManager;

  @override
  Stream<Measurement>? get stream => (deviceManager.isConnected)
      ? deviceManager.manager!.eSenseEvents
            .where((event) => event.runtimeType == ButtonEventChanged)
            .map(
              (event) => Measurement.fromData(
                ESenseButton(
                  deviceName: deviceManager.manager!.deviceName,
                  pressed: (event as ButtonEventChanged).pressed,
                ),
              ),
            )
            .asBroadcastStream()
      : null;
}

/// Collects eSense sensor events.
/// It generates an [ESenseSensor] for each sensor event.
class ESenseSensorProbe extends StreamProbe {
  Stream<Measurement>? _stream;

  @override
  ESenseDeviceManager get deviceManager =>
      super.deviceManager as ESenseDeviceManager;

  @override
  Stream<Measurement>? get stream => _stream ??= (deviceManager.isConnected)
      ? deviceManager.manager!.sensorEvents
            .map(
              (event) => Measurement.fromData(
                ESenseSensor.fromSensorEvent(
                  deviceName: deviceManager.manager!.deviceName,
                  event: event,
                ),
                event.timestamp.microsecondsSinceEpoch,
              ),
            )
            .asBroadcastStream()
      : null;
}

Both the device manager and the probes make use of the ESenseManager from the esense_flutter Flutter Plugin.

Putting the package together

Finally, all files should be bundled together in a Dart library. For example, the carp_esense_package package looks like this;

import 'dart:async';
import 'package:json_annotation/json_annotation.dart';
import 'package:esense_flutter/esense.dart';

import 'package:carp_serializable/carp_serializable.dart';
import 'package:carp_core/carp_core.dart';
import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';

part 'esense_package.dart';
part 'esense_domain.dart';
part 'esense_probes.dart';
part 'esense_device_manager.dart';
part 'esense.g.dart';

To use a sampling package, import it into your app together with the carp_mobile_sensing package:

import 'package:carp_core/carp_core.dart';
import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
import 'package:carp_esense_package/esense.dart';

Before creating a study and running it, register this package in the SamplingPackageRegistry.

SamplingPackageRegistry().register(ESenseSamplingPackage());

A package can be released as a Dart package on Pub. We already provide a list of different sampling packages - both using the onboard phone sensors as well as external wearable devices and online services.

Adding a new data manager

CAMS comes with a set of built-in and external data managers - see Data Managers for an overview. It is possible to extend CAMS with support for new data managers that can save or upload data to custom data backends. Support for this is done by implementing 3 interfaces:

Create a data endpoint

Implement the DataEndPoint interface which is used in the study protocol.

Create a data manager

Implement the DataManager interface which uploads or saves the measurement as they are sampled.

Create a data manager factory

Create a DataManagerFactory that can create a data manager based on the data endpoint configuration,

Data endpoint

A data endpoint is included in the study protocol and specifies what data manager to use for storing or forwarding data, and the configuration of this data manager. Any new data manager should have a corresponding data endpoint that extends from the DataEndPoint class. For example, the FileDataEndPoint specifies that data should be saved to a file using the FileDataManager data manager. This FileDataEndPoint allows for configuring the data manager by specifying buffer size and whether the file should be zipped or encrypted.

A DataEndPoint must support JSON serialization in order to be part of a study protocol

Data manager

A data manager implements the functionality for actually storing or forwarding the collected measurements. Any new data manager should implement the DataManager interface:

/// The [DataManager] interface is used to upload [Measurement] objects to any
/// data manager that implements this interface.
abstract class DataManager {
  /// The deployment using this data manager.
  PrimaryDeviceDeployment get deployment;

  /// The ID of the study deployment that this manager is handling.
  String get studyDeploymentId;

  /// The type of this data manager as enumerated in [DataEndPointTypes].
  String get type;

  /// Configure the data manager by specifying the study [deployment], the
  /// [dataEndPoint], and the stream of [measurements] events to handle.
  Future<void> configure({
    required DataEndPoint dataEndPoint,
    required SmartphoneDeployment deployment,
    required Stream<Measurement> measurements,
  });

  /// Flush any buffered data and close this data manager.
  /// After calling [close] the data manager can no longer be used.
  Future<void> close();

  /// Stream of data manager events.
  Stream<DataManagerEvent> get events;

  /// On each measurement collected, the [onMeasurement] handler is called.
  ///
  /// Implementations of this interface should handle how to save
  /// or upload the [measurement].
  Future<void> onMeasurement(Measurement measurement);

  /// When the data stream closes, the [onDone] handler is called.
  Future<void> onDone();

  /// When an error event is send on the stream, the [onError] handler is called.
  Future<void> onError(Object error);
}

All of these methods have to be implemented. However, the AbstractDataManager class provides a useful class to start from. For example, the ConsoleDataManager provides a very simple example of a data manager that prints a json encoded version of the data to the console:

/// A very simple data manager that just "uploads" the data to the
/// console (i.e., prints it). Used mainly for testing and debugging purposes.
class ConsoleDataManager extends AbstractDataManager {
  @override
  String get type => DataEndPointTypes.PRINT;

  @override
  Future<void> onMeasurement(Measurement measurement) async =>
      debugPrint(jsonEncode(measurement));
}

Data manager factory

When creating a new data manager, a corresponding DataManagerFactory must be provided. This factory knows how to create a data manager of a specific type when the study protocol is loaded. The interface looks like this:

/// A factory which can create a [DataManager] based on the `type` of an
/// [DataEndPoint].
abstract class DataManagerFactory {
  /// The [DataEndPoint] type.
  String get type;

  /// Create a [DataManager].
  DataManager create();
}

The factory for the ConsoleDataManager looks like this:

class ConsoleDataManagerFactory implements DataManagerFactory {
  @override
  String get type => DataEndPointTypes.PRINT;

  @override
  DataManager create() => ConsoleDataManager();
}

For a data manager to be used in CAMS, its factory must be registered in the DataManagerRegistry singleton like this:

DataManagerRegistry().register(ConsoleDataManagerFactory());

This should happen at app start-up and before the protocol is loaded and sensing is started.

Adding data and privacy transformers

Creating data transformer schemas

Data transformation is supported by the DataTransformerSchema class and can be implemented by implementing the namespace getter and the onRegister() callback function. As an example, the implementation of the Open mHealth transformer schema is shown below:

/// A default [DataTransformerSchema] for Open mHealth (OMH) transformers
class OMHTransformerSchema extends DataTransformerSchema {
  @override
  String get namespace => NameSpace.OMH;
  @override
  void onRegister() {}
}

Each transformer schema must be registered in the DataTransformerSchemaRegistry (which is a singleton). Hence, add the following line to your setup up part of the app:

DataTransformerSchemaRegistry().register(OMHTransformerSchema());

Once the schema is registered, transformers for each data type can be created. Data transformation is a transformation of one type of data to another type of data. I.e. data transformation is defined by the DataTransformer typedef.

typedef DataTransformer = Data Function(Data);

For each Data you want to transform, you need to define a new class that also extends Data. For example the following OMHGeopositionDataPoint class represents an OMH Geoposition data point.

/// Holds an OMH [Geoposition] data point.
class OMHGeopositionDataPoint extends OMHContextDataPoint
    implements DataTransformerFactory {
  OMHGeopositionDataPoint(DataPoint datapoint) : super(datapoint);

  factory OMHGeopositionDataPoint.fromLocationData(Location location) {
    var pos = Geoposition(
        latitude: PlaneAngleUnitValue(
            unit: PlaneAngleUnit.DEGREE_OF_ARC, value: location.latitude),
        longitude: PlaneAngleUnitValue(
            unit: PlaneAngleUnit.DEGREE_OF_ARC, value: location.longitude),
        positioningSystem: PositioningSystem.GPS);

    return OMHGeopositionDataPoint(
        DataPoint(body: pos, provenance: OMHContextDataPoint.provenance));
  }

  factory OMHGeopositionDataPoint.fromJson(Map<String, dynamic> json) =>
      OMHGeopositionDataPoint(DataPoint.fromJson(json));

  static DataTransformer get transformer =>
      ((data) => OMHGeopositionDataPoint.fromLocationData(data as Location));
}

The most important function to implement is the transformer, and to make sure JSON serialization is supported (in the example above, this is handled by the superclass OMHContextDataPoint). The transformer is a function that can transform one type of Data to another. The mapping between the two data types happens in the fromLocationData factory. The toJson method is needed in order to serialize and store the data. Also, note that the namespace of the DataFormat of this OMHGeopositionDataPoint is OMH. Once the mapper Data class is created, it must be added to the schema. This is done by calling;

DataTransformerSchemaRegistry().lookup(NameSpace.OMH)!
  ..add(LOCATION, OMHGeopositionDataPoint.transformer);

In the carp_context_package, this is done in the onRegister() method in the ContextSamplingPackage.

Using data transformer schemas

Data transformation can be done “manually” by looking up a specific transformer schema and applying its transformer. For example, the following code transforms a Location into an OMHGeopositionDatum.

    Location loc = Location()
      ..longitude = 12.23342
      ..latitude = 3.34224
      ..altitude = 124.2134235;
    OMHGeopositionDatum geo = TransformerSchemaRegistry().lookup(NameSpace.OMH).transform(loc);

However, a more general and common use of transformers is to specify what data format the DataEndPoint should use. This is done via the dataFormat property, which specifies the namespace, like NameSpace.OMH. The following data endpoint saves measurements to a file using the open mHealth (OMH) data format:

  // Create a study protocol storing data in files using the OMH data format
  var protocol = SmartphoneStudyProtocol(
    ownerId: 'AB',
    name: 'Track patient movement',
    dataEndPoint: FileDataEndPoint(
      bufferSize: 500 * 1000,
      zip: true,
      encrypt: false,
      dataFormat: NameSpace.OMH,
    ),
  );

Note that there is no OMH data format for all data types in CAMS. In the case that no OMH transformer is found, the data is stored in the original CARP data format.

Creating data privacy

A special instance of a data transformer schema is the PrivacySchema, which basically takes a piece of data and protects relevant properties. CAMS comes with a built-in schema with a transformer namespace specified in PrivacySchema.DEFAULT. Hence, to add privacy protection, two things have to be implemented:

A transformer function that knows how to transform a Data object so that its properties are privacy-protected.
Register this function in the DataTransformerSchemaRegistry as part of the default PrivacySchema.DEFAULT schema.

Below are examples of privacy functions that anonymize text messages and phone calls:

/// A [TextMessage] anonymizer function. Anonymizes:
///  - address
///  - body
TextMessage textMessageAnonymizer(Data data) {
  assert(data is TextMessage);
  var msg = data as TextMessage;
  if (msg.address != null) {
    msg.address = sha1.convert(utf8.encode(msg.address!)).toString();
  }
  if (msg.body != null) {
    msg.body = sha1.convert(utf8.encode(msg.body!)).toString();
  }

  return msg;
}

/// A [PhoneCall] anonymizer function. Anonymizes:
///  - formattedNumber
///  - number
///  - name
PhoneCall phoneCallAnonymizer(PhoneCall call) {
  if (call.formattedNumber != null) {
    call.formattedNumber = sha1
        .convert(utf8.encode(call.formattedNumber!))
        .toString();
  }
  if (call.number != null) {
    call.number = sha1.convert(utf8.encode(call.number!)).toString();
  }
  if (call.name != null) {
    call.name = sha1.convert(utf8.encode(call.name!)).toString();
  }

  return call;
}

This function can be put anywhere in the sampling package, but a typical place to put it is in a separate file (if you have many functions) or in the package dart file (if you only have a few). Registering the anonymizer functions in the PrivacySchema.DEFAULT schema:

TransformerSchemaRegistry().lookup(PrivacySchema.DEFAULT)!.add(TEXT_MESSAGE, textMessageAnoymizer);

This is typically done as part of the onRegister() callback in the package. The example above is implemented as part of the carp_communication_package package.

It is good practice to consider if your data sampling package needs to supply privacy-protecting functions, and if so, add these to the default privacy schema.

Getting Started

Core Concepts

Advanced Concepts

Extending CARP Mobile Sensing

Add Triggers

Add Sampling Packages

Add Data Managers

Add Data Transformers

JSON serialization

Adding new triggers

Define a new trigger

Define a trigger executor

Define and register a trigger factory

Adding new sampling capabilities

Sampling package

Sampling configurations

Data

Probes

Device manager

Putting the package together

Adding a new data manager

Data endpoint

Data manager

Data manager factory

Adding data and privacy transformers

Creating data transformer schemas

Using data transformer schemas

Creating data privacy

Add Triggers

Add Sampling Packages

Add Data Managers

Add Data Transformers

​JSON serialization

​Adding new triggers

​Define a new trigger

​Define a trigger executor

​Define and register a trigger factory

​Adding new sampling capabilities

​Sampling package

​Sampling configurations

​Data

​Probes

​Device manager

​Putting the package together

​Adding a new data manager

​Data endpoint

​Data manager

​Data manager factory

​Adding data and privacy transformers

​Creating data transformer schemas

​Using data transformer schemas

​Creating data privacy

JSON serialization

Adding new triggers

Define a new trigger

Define a trigger executor

Define and register a trigger factory

Adding new sampling capabilities

Sampling package

Sampling configurations

Data

Probes

Device manager

Putting the package together

Adding a new data manager

Data endpoint

Data manager

Data manager factory

Adding data and privacy transformers

Creating data transformer schemas

Using data transformer schemas

Creating data privacy