SmartphoneStudyProtocol

A study protocol that runs on a smartphone.

A protocol says what to measure and when. It holds the primary device (PrimaryDeviceConfiguration) that collects data, the connected devices (DeviceConfiguration), and the task controls (TaskControl) that pair a trigger with a task. CAMS adds a studyDescription, a dataEndPoint that says where data goes, and a privacySchemaName. You build one in code (or load it from JSON) and add it with SmartPhoneClientManager.addStudyFromProtocol.

Key points:

• The first device added with addPrimaryDevice is the phone running the study.
• addTaskControl pairs one TriggerConfiguration with one TaskConfiguration.
• Adding a device also adds a MonitoringTask that collects errors and triggered and completed tasks from that device.
• Serializes to JSON, so the same protocol can be deployed from a server.
• SmartphoneStudyProtocol.local creates a ready-to-use local protocol.

See also SmartphoneDeployment, which is created from a protocol, and SmartphoneDeploymentExecutor, which runs it.

// Create a study protocol storing data in a local SQLite database.
SmartphoneStudyProtocol protocol = SmartphoneStudyProtocol(
  ownerId: 'abc@dtu.dk',
  name: 'Track patient movement',
  dataEndPoint: SQLiteDataEndPoint(),
);

// Define which devices are used for data collection.
// In this case, its only this smartphone.
Smartphone phone = Smartphone();
protocol.addPrimaryDevice(phone);

// Automatically collect step count, ambient light, screen activity, and
// battery level. Sampling starts immediately.
protocol.addTaskControl(
  ImmediateTrigger(),
  BackgroundTask(measures: [
    Measure(type: SensorSamplingPackage.STEP_COUNT),
    Measure(type: SensorSamplingPackage.AMBIENT_LIGHT),
    Measure(type: DeviceSamplingPackage.SCREEN_EVENT),
    Measure(type: DeviceSamplingPackage.BATTERY_STATE),
  ]),
  phone,
);

Inheritance

• Object
• Snapshot
• StudyProtocol
• SmartphoneStudyProtocol

Mixed-in types

• SmartphoneProtocolExtension

Annotations

• @JsonSerializable(includeIfNull: false, explicitToJson: true)

Constructors

SmartphoneStudyProtocol.fromJson

SmartphoneStudyProtocol.fromJson(

1. Map<String, dynamic> json

)

SmartphoneStudyProtocol.local

SmartphoneStudyProtocol.local({

1. String? name,
2. List<Measure>? measures,

})

Creates a SmartphoneStudyProtocol for local data collection using this smartphone as the primary device and with just one participant role called "Participant".

The data is stored locally using a SQLiteDataEndPoint.

This protocol also includes a default background sampling task of collecting device and application information every time sensing starts.

Optionally, a list of measures can be provided which will be collected as part of a default background sampling task by this smartphone. Additional measures can be added later using addTaskControl, if needed.

SmartphoneStudyProtocol

SmartphoneStudyProtocol({

1. String? ownerId,
2. required String name,
3. String? applicationName,
4. StudyDescription? studyDescription,
5. DataEndPoint? dataEndPoint,
6. String? privacySchemaName,

})

Creates a new SmartphoneStudyProtocol with a unique name.

The ownerId is typically the ID of the user uploading this protocol to CAWS. If ownerId is not specified, a UUID will be generated. Note, however, that this will be replaced with the ID of the user uploading the protocol, if uploaded to CAWS.

The applicationName is the name of the application which will execute this protocol. This is the Flutter application name as specified in the pubspec.yaml file of the app executing this protocol. This is used to filter invitations to studies from CAWS.

The studyDescription contains the title, description, purpose, and the responsible researcher for this study.

The dataEndPoint specifies where and how to store or upload the data collected in this study. If null, the data is not stored, but can still be used in the app.

The privacySchemaName is the name of a PrivacySchema to be used for protecting sensitive data. Use PrivacySchema.DEFAULT for the default, built-in schema. If not specified, no privacy schema is used and data is saved as collected.

Constants

CAMS_DEMO_APP_NAME

String const CAMS_DEMO_APP_NAME

The applicationName of the CARP Mobile Sensing demo app.

CAMS_EXAMPLE_APP_NAME

String const CAMS_EXAMPLE_APP_NAME

The applicationName of the example app included in CAMS.

CAMS_PROTOCOL_API_LEVEL

String const CAMS_PROTOCOL_API_LEVEL

The API level used by study protocols. This reflects the major version of the CARP Mobile Sensing framework as set in the pubspec.yaml file.

CARP_STUDY_APP_NAME

String const CARP_STUDY_APP_NAME

The applicationName of the CARP Studies app.

PULMONARY_MONITOR_APP_NAME

String const PULMONARY_MONITOR_APP_NAME

The applicationName of the Pulmonary Monitor demo app.

Properties

description

String get description

inherited

1. @override

set description (String? description)

override

The description from studyDescription, or an empty string if none.

Methods

addConnectedDevice

1. @override

bool addConnectedDevice(

1. DeviceConfiguration<DeviceRegistration> device,
2. PrimaryDeviceConfiguration<DeviceRegistration> primaryDevice

)

override

Adds device as connected to primaryDevice, plus a MonitoringTask for it.

Always returns true.

addPrimaryDevice

1. @override

bool addPrimaryDevice(

1. PrimaryDeviceConfiguration<DeviceRegistration> primaryDevice

)

override

Adds primaryDevice and a MonitoringTask for it.

Always returns true.

getDeviceByRoleName

DeviceConfiguration<DeviceRegistration>? getDeviceByRoleName(

1. String roleName

)

The primary or connected device with roleName, or null if not found.

toJson

1. @override

Map<String, dynamic> toJson()

override