Skip to content
CARP Documentation

SmartphoneStudyController

Runs one SmartphoneStudy on this phone.

There is one controller per study. Use it to start and stop sampling in a single study, to listen to its measurements, or to register connected devices. Get it from SmartPhoneClientManager.getStudyController; do not create it yourself.

Key points:

  • Reacts to study events. When a deployment is received, it creates the DataManager for the study's DataEndPoint, configures and connects all devices, initializes the SmartphoneDeploymentExecutor, asks for permissions and restores the previous sampling state.
  • Deployment events are handled one at a time. A failing run is logged, not rethrown.
  • When the deployment is stopped (e.g., on the server), it removes the study's app tasks and disposes the executor for good.
  • Transforms collected Measurements with the deployment's privacy schema and data format before they reach measurements.

See also SmartPhoneClientManager, which owns all controllers.

Constructors

SmartphoneStudyController

SmartphoneStudyController(
  1. SmartphoneStudy study
)

Creates a controller for study and starts listening to its events.

Normally called by SmartPhoneClientManager.getStudyController.

Properties

dataEndPoint

DataEndPoint? get dataEndPoint

The data endpoint of the deployment, i.e. how data is saved or uploaded.

If null, data is still sampled and available in measurements, but not saved.

dataManager

DataManager? get dataManager

The data manager that saves or uploads the measurements of this study.

Created from dataEndPoint when a deployment is received. Null if there is no endpoint or no data manager is registered for its type.

deployment

SmartphoneDeployment? get deployment

The deployment associated with this study.

deploymentStatus

StudyDeploymentStatus? get deploymentStatus

The deployment status of this study.

executor

SmartphoneDeploymentExecutor get executor

The executor executing the deployment.

measurements

Stream<Measurement> get measurements

The stream of all sampled measurements.

Data in the measurements stream are transformed in the following order:

  1. privacy schema as specified in the privacySchemaName
  2. preferred data format as specified by DataEndPoint.dataFormat in the original protocol.

This is a broadcast stream and supports multiple subscribers.

permissions

Map<Permission, PermissionStatus> get permissions

The status of each permission needed by this study.

Set by askForAllPermissions. Empty until then.

privacySchemaName

String get privacySchemaName

The name of the privacy schema applied to all measurements.

Taken from the deployment. Defaults to NameSpace.CARP, which leaves data unchanged.

remainingDevicesToRegister

List<DeviceConfiguration<DeviceRegistration>> get remainingDevicesToRegister

The devices in this study that still need to be registered.

Includes both the primary device and connected devices.

Returns an empty list if the deployment status is not available yet.

study

SmartphoneStudy get study

The study that this controller runs.

Methods

askForAllPermissions

Future<void> askForAllPermissions()

Asks for the permissions needed by all measures in this study.

Only permissions relevant to the deployment are asked for, so call this after the study is deployed but before sampling is resumed. Called automatically if SmartPhoneClientManager.askForPermissions is true.

Permissions are asked for one at a time, through SmartPhoneClientManager.requestPermissions, on both Android and iOS. The result is stored in permissions.

dispose

void dispose()

Pauses data sampling and closes the dataManager.

Closing the data manager e.g. flushes data to a file. All cached deployment information and any data sampled in this deployment remain on the phone.

The controller must not be used afterwards. Called by SmartPhoneClientManager when a study is stopped or removed.

measurementsByType

Stream<Measurement> measurementsByType(
  1. String type
)

The measurements of data type, e.g. dk.cachet.carp.steps.

pause

void pause()

Pauses data sampling in this study.

restart

void restart()

Restarts data sampling, ignoring any previously stored sampling state.

All task controls are resumed, including ones that were paused.

resume

void resume()

Resumes data sampling in this study.

Task controls are resumed or kept paused based on the stored sampling state of the study. To ignore the stored state, call restart instead.

tryRegisterConnectedDevice

Future<void> tryRegisterConnectedDevice(
  1. DeviceConfiguration<DeviceRegistration> device
)

Tries to register the connected device with the deployment service.

The device must be:

  • a connected device (i.e., not the primary device),
  • connected to this phone, and
  • available in the DeviceController.

Otherwise, or if registration fails, a warning is logged and nothing is registered. On success, the local deployment and deployment status are updated too.

tryRegisterRemainingDevicesToRegister

Future<void> tryRegisterRemainingDevicesToRegister()

Tries to register all remainingDevicesToRegister.

Syncs the devices needed by the deployment with the devices on this phone. Does not wait for the registrations.

tryReregisterDevice

Future<void> tryReregisterDevice(
  1. DeviceConfiguration<DeviceRegistration> device
)

Tries to re-register the device with the deployment service.

Since there is no way to update a registration, this method first tries to unregister the device and then, 5 seconds later, to register it again. Returns before the new registration is done.

tryUnregisterDisconnectedDevice

Future<void> tryUnregisterDisconnectedDevice(
  1. DeviceConfiguration<DeviceRegistration> device
)

Tries to unregister the device with the deployment service.

Failures are logged, not thrown.