carp_backend 1.1.0

CARP data backend for CARP Mobile Sensing. Supports downloading study deployments and uploading data from/to a CARP Web Service (CAWS) server.

CARP Data Backend

This package integrates the CARP Mobile Sensing Framework with the CARP Web Services (CAWS) backend.

For an overview of all CAMS packages, see CARP Mobile Sensing in Flutter. For documentation on how to use CAMS, see the CAMS wiki.

This library supports;

• downloading a study invitation
• download a study deployment
• downloading translations
• downloading messages
• uploading collected data, and
• uploading an informed consent document

from/to a CAWS server.

Note that this library makes little sense on its own and is only to be used as part of the overall CARP Mobile Sensing ecosystem. See the CAMS wiki for documentation on how to use CAMS, and checkout the CARP Mobile Sening Demo App for a full example of an app using CARP Mobile Sensing and CAWS, including this library.

Using the Plugin

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

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

Configuration

This library uses the carp_webservices API for accessing CAWS. In order to access CAWS, a CarpApp needs to be configured like this:

final String uri = "https://cans.cachet.dk";

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

// Configure the CAWS service
CarpService().configure(app);

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

// Configure the other services needed.
// Note that these CAWS services work as singletons and can be
// accessed throughout the app.
CarpParticipationService().configureFrom(CarpService());
CarpDeploymentService().configureFrom(CarpService());

Downloading a study invitation and deployment from CAWS

Getting a study invitation and deployment from CAWS is done using the CarpParticipationService and CarpDeploymentService services, respectively.

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

// Use the first (i.e. latest) invitation.
final invitation = invitations[0];

The invitation contains information about the deployment, including the studyDeploymentId and the device roleName. This invitation is used to configure a study, which can be deployed and started in a SmartPhoneClientManager.

// Create and configure a client manager for this phone.
// If no deployment service is specified in the configure method,
// the default CarpDeploymentService() singleton is used.
final client = SmartPhoneClientManager();
await client.configure();

// Define the study based on the invitation and add it to the client.
final study = await client.addStudy(
  invitation.studyDeploymentId!,
  invitation.assignedDevices!.first.device.roleName,
);

// Get the study controller and try to deploy the study.
//
// If "useCached" is true and the study has already been deployed on this
// phone, the local cache will be used (default behavior).
// If not deployed before (i.e., cached) the study deployment will be
// fetched from the deployment service.
final controller = client.getStudyRuntime(study);
await controller?.tryDeployment(useCached: false);

// Configure the controller
await controller?.configure();

// Start sampling
controller?.start();

Uploading of data to CARP

Configuration of data upload is done as a DataEndPoint, which is part of a SmartphoneStudyProtocol.

CAWS and hence this plugin supports three methods of data upload:

• The (default) data stream batch upload using the CARP Core Data subsystem
• The (legacy) DataPoint batch upload
• File upload of raw SQLite .db files

Specifying 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 property. For example, a streaming data upload is created like this:

// Using the (default) data stream batch upload method
CarpDataEndPoint streamingEndPoint = CarpDataEndPoint(
  uploadMethod: CarpUploadMethod.stream,
  deleteWhenUploaded: true,
);

Or a DataPoint upload method is created like this:

// Using the "old" DataPoint endpoint for uploading batches of data points.
//
// Note that if a user is already authenticated to a CAWS server - for example
// based on the download of invitations and deployments - specification
// authentication info is not needed in the CarpDataEndPoint.
CarpDataEndPoint dataPointEndPoint = CarpDataEndPoint(
    uploadMethod: CarpUploadMethod.datapoint,
    name: 'CARP Staging Server',
    uri: 'http://staging.carp.cachet.dk:8080',
    clientId: 'carp',
    clientSecret: 'a_secret',
    email: '[e-mail]',
    password: 'password');

To use the data endpoint, add it to the study protocol like this:

// Create a study protocol with a specific data endpoint.
SmartphoneStudyProtocol protocol = SmartphoneStudyProtocol(
  ownerId: 'AB',
  name: 'Track patient movement',
  dataEndPoint: streamingEndPoint,
);

Register the Data Manager

In order to use the CAWS data manger for uploading of data, you should register it in the DataManagerRegistry.

// Register CAWS as a data backend where data can be uploaded.
DataManagerRegistry().register(CarpDataManagerFactory());

Authentication to CAWS

Configuration and authentication to CAWS only needs to be done once. Hence, if you app is already authenticated to CARP (for example, because the study deployment has been downloaded from CAWS), there is NO need for specifying the server information (name and uri) and authentication information (client_id, client_secret, username, and password) in the CarpDataEndPoint. Hence, in this case, you would specify a data endpoint like this:

var endpoint = CarpDataEndPoint(uploadMethod: CarpUploadMethod.datapoint);

Features and bugs

Please file feature requests and bug reports at the issue tracker. Remember to specify which CARP library you're filing an issue for (in this case carp_backend).

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.