carp_backend

Description:

carp backend

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
uploading collected data
getting and uploading an informed consent document
getting and uploading translations
getting and uploading messages

from/to a CAWS server.

Note that this library does nothing 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_auth/carp_auth.dart';
import 'package:carp_webservices/carp_services/carp_services.dart';
import 'package:carp_backend/carp_backend.dart';
copied to clipboard
Configuration #
This library uses the carp_webservices API for accessing CAWS. In order to access CAWS, a CarpApp needs to be configured like this:
// Configure an app that points to the CARP web services (CAWS)
final Uri uri = Uri(
scheme: 'https',
host: 'dev.carp.dk',
);

late CarpApp app = CarpApp(
name: "CAWS @ DTU",
uri: uri,
studyId: '<the_study_id_if_known>',
studyDeploymentId: '<the_study_deployment_id_if_known>',
);

// The authentication configuration
late CarpAuthProperties authProperties = CarpAuthProperties(
authURL: uri,
clientId: 'studies-app',
redirectURI: Uri.parse('carp-studies-auth://auth'),
// For authentication at CAWS the path is '/auth/realms/Carp'
discoveryURL: uri.replace(pathSegments: [
'auth',
'realms',
'Carp',
]),
);

// Configure the CAWS services
await CarpAuthService().configure(authProperties);
CarpService().configure(app);

// Authenticate at CAWS using username and password
await CarpAuthService().authenticateWithUsernamePassword(
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());
copied to clipboard
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];
copied to clipboard
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();
copied to clipboard
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 upload using the CARP Core Data subsystem
The (legacy) DataPoint 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. For example, a streaming data upload is created like this:
// Using the (default) data stream batch upload method
var streamingEndPoint = CarpDataEndPoint();
copied to clipboard
Upload methods are defined in the uploadMethod property. A data point upload method is created like this:
// Using the "legacy" DataPoint endpoint for uploading batches of data points.
var dataPointEndPoint =
CarpDataEndPoint(uploadMethod: CarpUploadMethod.datapoint);
copied to clipboard
Similarly, an endpoint uploading the raw SQLite db files can be specified:
// Using the file method would upload SQLite db files.
var fileEndPoint = CarpDataEndPoint(uploadMethod: CarpUploadMethod.file);
copied to clipboard
There are some details in how the three different types of endpoints work:


Streaming - Using the streaming data method requires that the study deployment has been obtained from CAWS via an invitation, as shown above. This ensures that there is a linkage between the study deployment ID from the deployment and the ID in the data being streamed back to CAWS.


Data Point & File - The data point and file endpoints need the study ID and study deployment ID. This can be obtained via the invitation (as above), but it can also be specified when creating the CarpApp configuration. Hence, the data point and file endpoints can be used if these IDs are known, e.g., are static to the app.


For all three upload types (stream, data point, and file), additional parameters can be specified for a an endpoint.
/// Specify parameters on upload interval (in minutes), if upload only
/// should happen when the phone is connected to WiFi, and whether data
/// buffered locally on the phone should be deleted when uploaded.
streamingEndPoint = CarpDataEndPoint(
uploadInterval: 20,
onlyUploadOnWiFi: true,
deleteWhenUploaded: false,
);
copied to clipboard
Adding a Data Endpoint to the Study Protocol #
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,
);
copied to clipboard
Register the Data Manager #
In order to use the CAWS data manger for uploading of data, you should register its factory in the DataManagerRegistry.
// Register CAWS as a data backend where data can be uploaded.
DataManagerRegistry().register(CarpDataManagerFactory());
copied to clipboard
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.