Software architecture
The runtime, infrastructure and plugin layers of CARP Mobile Sensing, and how a study is executed.
The runtime architecture of CARP Mobile Sensing (CAMS) has three layers:
| Layer | Main responsibility |
|---|---|
| Runtime | The main runtime layer of CAMS. Orchestrates the client manager with study controllers, device managers, controllers and registries. |
| Infrastructure | Provides services for deployment, background sensing, persistence, data management and sampling packages. |
| Plugins | Flutter plugins that CAMS uses to access the operating system (OS), online services and connected BLE devices on Android and iOS. |
The architecture is designed to be highly extensible, cross-platform and maintainable.
Runtime
The runtime layer is the main entry point to CAMS. It holds the client manager, a study controller for each running study, device managers, and a set of controllers and registries.
| Component | Singleton | Role |
|---|---|---|
SmartPhoneClientManager | Yes | The main entry point to CAMS. Holds references to its deployment service, the device controller and the client repository, which holds the set of running studies. |
SmartphoneStudyController | No | Created for each study added to the client manager's repository. Handles the study at runtime: collects data through its deployment executor and sends it to its data manager for storage or upload. |
DeviceController | Yes | Controls all primary and connected devices at runtime. Each device available on the phone has a DeviceManager, such as the SmartphoneDeviceManager. |
DataManagerRegistry | Yes | Registry of available DataManager implementations. |
AppTaskController | Yes | Manages the AppTask lifecycle and queueing. |
NotificationManager | Yes | Handles OS-level notifications. |
SamplingPackageRegistry | Yes | Registry of available SamplingPackage implementations. |
DataTransformerSchemaRegistry | Yes | Registry of available DataTransformerSchema mappings. |
Singletons can be accessed throughout the app.
Study execution flow
Configure the client manager
The
SmartPhoneClientManageris configured with a deployment service, a device controller and runtime options.Add studies
Adding a study creates and hosts a
SmartphoneStudyControllerfor that study.Deploy a study
Deploying a study fetches the study deployment from the deployment service and adds it to the study controller. The study deployment describes what data to collect and which data manager to use for data upload and/or transformation.
Store or upload data
The data manager associated with a study (available in the study controller) stores or uploads the sampled data.
Sampling state persists across app restarts
CAMS keeps the state of data sampling persistently across app restarts, so you only follow this flow once, when you add a new study. Once a study is added and deployed, its runtime status is saved and restored automatically when the app restarts, for example after the OS kills the app. See background sensing.
Infrastructure
The infrastructure layer holds services for getting study deployments, collecting data and storing it. The most important part is the set of sampling packages, described in detail in this scientific paper.
| Component | Role |
|---|---|
DeploymentService | Handles study deployment configurations for the client. CAMS includes the built-in SmartphoneDeploymentService (default), used by apps that only run local deployments. CarpDeploymentService is the CAWS-specific implementation of the DeploymentService interface. |
DataManager | Data managers store, save or upload data. Examples are SQLiteDataManager and CarpDataManager. |
SamplingPackage | A sampling package supports data collection of measures on a specific device. |
Sampling packages
CAMS includes two built-in sampling packages, DeviceSamplingPackage and SensorSamplingPackage. Most sampling packages are external and you include them as needed, so an app only requests permissions for the probes and sensors it actually uses.
A sampling package always collects data from a device:
- External devices, such as Polar heart rate monitors. The Polar package uses a
PolarDeviceManagerfor data collection. - Online services, such as the
WeatherServiceManagerin thecarp_context_package.
See Measure types for the measures each sampling package provides.
Plugins
CAMS relies on the Flutter package and plugin architecture for cross-platform access to OS-level services and sensors. These packages and plugins are maintained independently of CAMS and are available from pub.dev.
Plugins for data collection are typically used in probes. Each sampling package contains one or more Probes that access the underlying sensors and collect data. The plugins are external to CAMS and are loaded by the sampling package as needed.
For example, location data, which both Android and iOS consider sensitive, is accessed in the carp_context_package, which uses the location plugin. If your study does not need this measure, leave out carp_context_package and your app does not ask for location permissions.