CARP Data Backend
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
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';
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
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;
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
// 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
CAWS and hence this plugin supports three methods of data upload:
- The (default) data stream upload using the CARP Core Data subsystem
- The (legacy)
- File upload of raw SQLite
Specifying a CARP Data Endpoint
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();
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);
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);
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
CarpAppconfiguration. 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, );
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, );
Register the Data Manager
In order to use the CAWS data manger for uploading of data, you should register its factory in the
// Register CAWS as a data backend where data can be uploaded. DataManagerRegistry().register(CarpDataManagerFactory());
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