Building sampling packages

A sampling package adds measure types to CARP Mobile Sensing (CAMS). For each type, it defines the data class that holds the values of a measurement and the probe that collects them. For a wearable or an online service, it also connects the phone to the device.

Build one when no existing package collects the data your study needs. To find an existing one, see Measure types.

A sampling package is a Flutter package of its own. You can use it in your app, share it with other CAMS apps or publish it on pub.dev.

Written for CAMS 2.5.1

The pages and the example package target carp_mobile_sensing 2.5.1, carp_core 2.2.2 and carp_serializable 3.0.0. Where CAMS 2.5.1 has a defect that affects package authors, the pages state the rule and the workaround.

How it works

CAMS finds your package through the measure type in a study protocol:

flowchart LR
    Protocol["<b>Study protocol</b><br/>a measure with<br/>your measure type"] --> Phone
    subgraph Phone["CAMS on the phone"]
        direction TB
        Package["<b>Sampling package</b><br/>found by the registry<br/>for the measure type"] -->|creates| Probe["<b>Probe</b><br/>reads the sensor"]
        Probe --> Measurement["<b>Measurement</b><br/>your data class<br/>and its timestamps"]
    end
    Phone --> Manager[("<b>Data manager</b><br/>stores or uploads<br/>the measurements")]

1. A task in the study protocol holds a measure whose type is one of your package's measure types, such as com.example.airpressure.
2. When the phone gets the deployment, CAMS asks the SamplingPackageRegistry for the registered package that declares the type. That package's create() method returns a new probe for the measure.
3. When the task's trigger fires, CAMS resumes the probe. The probe reads the sensor and adds measurements, each holding an object of your data class and its timestamps.
4. CAMS applies the privacy schema and data format that the protocol selects. The data manager then stores or uploads each measurement.

Parts of a sampling package

Example package

The guide builds one example package, barometer_sampling_package, which reads the phone's barometer with the sensors_plus plugin. It adds two measure types:

Together, the pages show every source file of the package, so you can rebuild it, and explain the rule behind each part. The package also rounds both measures to whole hectopascals in studies that ask for privacy protection.

The package is an example, not a published CARP package. Its measure types use the namespace com.example, the reverse of example.com, a domain reserved for documentation. Use a namespace that you control in your own package.

Prerequisites

• A Flutter app that runs a CAMS study and reads its measurements, as described in Using CAMS.
• Knowledge of study protocols, triggers, tasks and measures, as described in Domain model.
• A phone with the sensor that your package reads. The iOS Simulator, for example, has no barometer.

Guide pages