carp_backend 0.21.2

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

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 = "https://cans.cachet.dk:443";

  // 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',
    ),
  );
  CarpService().configure(app);

  // 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()
      .getStudyDeploymentStatus(studyDeploymentId);

  // 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
  controller.data.listen((data) => 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.

  DataManagerRegistry().register(CarpDataManager());

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: 'http://staging.carp.cachet.dk:8080',
      clientId: 'carp',
      clientSecret: 'a_secret',
      email: '[e-mail]',
      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: 'http://staging.carp.cachet.dk:8080',
      clientId: 'carp',
      clientSecret: 'a_secret',
      email: '[e-mail]',
      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(
    CarpUploadMethod.BATCH_DATA_POINT,
    name: 'CARP Staging Server',
    uri: 'http://staging.carp.cachet.dk:8080',
    clientId: 'carp',
    clientSecret: 'a_secret',
    email: '[e-mail]',
    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.