carp_backend 0.21.2+1
carp_backend: ^0.21.2+1 copied to clipboard

CARP data backend for CARP mobile sensing. Supports uploading json to CARP as either zipped filed or as plain json in collections.

CARP Data Backend #

pub package style: effective dart github stars MIT License

This package integrates the CARP Mobile Sensing Framework with the CARP web service backend. It support downloading a study configuration and uploading collected data.

For Flutter plugins for other CARP products, see CARP Mobile Sensing in Flutter.

Using the Plugin #

Add carp_backend as a dependency in your pubspec.yaml file and import the library along with the carp_mobile_sensing library.

import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
import 'package:carp_webservices/carp_services/carp_services.dart';
import 'package:carp_core/carp_core.dart';
import 'package:carp_backend/carp_backend.dart';

Downloading a study configuration from CARP #

Getting a study configuration from CARP is done using a CARPStudyProtocolManager. But in order to authenticate to CARP and get the available studies for the user, we make use of the carp_webservices API.

To get a study, you basically go through the following steps:

  1. Create and configure a CarpApp that points to the correct CARP web service.
  2. Authenticate to the CARP web service
  3. Get the list of study invitations for the authenticated user.
  4. Get a specific study via a CARPStudyProtocolManager or deploy it directly using the CustomProtocolDeploymentService.

The following code illustrates how this is done:

  final String uri = "";

  // configure an app that points to the CARP web service
  CarpApp app = CarpApp(
    name: 'any_display_friendly_name_is_fine',
    uri: Uri.parse(uri),
    oauth: OAuthEndPoint(
      clientID: 'the_client_id',
      clientSecret: 'the_client_secret',

  // authenticate at CARP
  await CarpService()
      .authenticate(username: 'the_username', password: 'the_password');

  // get the invitations to studies from CARP for this user
  List<ActiveParticipationInvitation> invitations =
      await CarpService().invitations();

  // use the first (i.e. latest) invitation
  String studyDeploymentId = invitations[0].studyDeploymentId;

  // create a study manager, and initialize it
  CARPStudyProtocolManager manager = CARPStudyProtocolManager();
  await manager.initialize();

  // get the study protocol from CARP
  StudyProtocol study = await manager.getStudyProtocol(studyDeploymentId);
  print('study: $study');

If you just want to deploy and run the study deployment directly, another approach is to use the CustomProtocolDeploymentService directly:

  // get the status of the deployment
  StudyDeploymentStatus status = await CustomProtocolDeploymentService()

  // create and configure a client manager for this phone
  SmartPhoneClientManager client = SmartPhoneClientManager(
    deploymentService: CustomProtocolDeploymentService(),
    deviceRegistry: DeviceController(),
  await client.configure();

  String deviceRolename = status.masterDeviceStatus.device.roleName;

  // add and deploy this deployment using its rolename
  StudyDeploymentController controller =
      await client.addStudy(studyDeploymentId, deviceRolename);

  // configure the controller with the default privacy schema
  await controller.configure();
  // controller.resume();

  // listening on the data stream and print them as json to the debug console => print(toJsonString(data)));

Uploading of data to CARP #

Upload of sensing data to the CARP web service can be done in four different ways:

  • as individual CARP data points
  • as a batch upload of a file with multiple CARP data points
  • as a CARP object in a collection
  • as a file to the CARP file store

Using the library takes three steps.

1. Register the Data Manager #

First you should register the data manager in the DataManagerRegistry.


2. Create a CARP Data Endpoint #

Create a CarpDataEndPoint that specify which method to use for uploading data, and the details. Upload methods are defined in the CarpUploadMethod class.

For example, a CarpDataEndPoint that upload data points directly looks like this:

  CarpDataEndPoint cdep = CarpDataEndPoint(CarpUploadMethod.DATA_POINT,
      name: 'CARP Staging Server',
      uri: '',
      clientId: 'carp',
      clientSecret: 'a_secret',
      email: '',
      password: 'password');

A CarpDataEndPoint that uploads data as zipped files and keeps the file on the phone, looks like this:

  CarpDataEndPoint cdep = CarpDataEndPoint(CarpUploadMethod.FILE,
      name: 'CARP Staging Server',
      uri: '',
      clientId: 'carp',
      clientSecret: 'a_secret',
      email: '',
      password: 'password',
      bufferSize: 500 * 1000,
      zip: true);

And a CarpDataEndPoint that batch uploads data points in a json file (which is deleted when uploaded) looks like this:

  CarpDataEndPoint cdep = CarpDataEndPoint(
    name: 'CARP Staging Server',
    uri: '',
    clientId: 'carp',
    clientSecret: 'a_secret',
    email: '',
    password: 'password',
    bufferSize: 500 * 1000,
    deleteWhenUploaded: true,

3. Assign the CARP Data Endpoint to your Study Controller #

To use the CARP Data Endpoint in you study controller, configure it with this end point before resuming sampling.

  // configure the controller with this data endpoint
  await controller.configure(dataEndPoint: cdep);

Features and bugs #

Please file feature requests and bug reports at the issue tracker.

License #

This software is copyright (c) Copenhagen Center for Health Technology (CACHET) at the Technical University of Denmark (DTU). This software is made available 'as-is' in a MIT license.

pub points


CARP data backend for CARP mobile sensing. Supports uploading json to CARP as either zipped filed or as plain json in collections.

Repository (GitHub)
View/report issues


API reference




carp_mobile_sensing, carp_webservices, flutter, json_annotation, meta, research_package


Packages that depend on carp_backend