CarpDeploymentService

A CARP Core DeploymentService that talks to CAWS.

A participant app uses it to register the phone as the primary device of a study deployment, download the SmartphoneDeployment that says what to measure, and report it as deployed. Researcher tools can also create study deployments from a protocol.

Key points:

• A singleton; call configure (or configureFrom) before use.
• deployment returns a DeploymentReference that remembers the study deployment and device role, and is the easier way to run the steps above.
• Removing deployments is not supported from the client and throws a CarpServiceException.

The study deployment ID usually comes from an invitation found by CarpParticipationService. The downloaded deployment is run by the CARP Mobile Sensing runtime.

Inheritance

• Object
• CarpBaseService
• CarpDeploymentService

Implemented types

• DeploymentService

Constructors

CarpDeploymentService

CarpDeploymentService()

Singleton default instance of the CarpDeploymentService. Before this instance can be used, it must be configured using the configure method.

Properties

rpcEndpointName

1. @override

String get rpcEndpointName

override

The name of this service's RPC endpoint at CAWS, like deployment-service.

Methods

createStudyDeployment

1. @override

Future<StudyDeploymentStatus> createStudyDeployment(

1. StudyProtocol protocol, [
2. List<ParticipantInvitation> invitations = const [],
3. String? id,
4. Map<String, DeviceRegistration>? connectedDevicePreregistrations,

])

override

Creates a study deployment for a given protocol with participants defined in invitations.

The identities specified in the invitations are used to invite and authenticate the participants. In case no account is associated to an identity, a new account is created for it. An invitation (and account details) is delivered to the person managing the identity, or should be handed out manually to the relevant participant by the person managing the identity.

Note that id is currently not sent to CAWS, which assigns the deployment ID itself.

CAWS throws IllegalArgumentException when:

• protocol is invalid
• invitations is empty
• any of the assigned device roles in invitations is not part of the study protocol
• not all necessary primary devices part of the study protocol have been assigned a participant

Returns the StudyDeploymentStatus of the newly created study deployment.

deployment

DeploymentReference deployment([

1. String? studyDeploymentId,
2. String? primaryDeviceRoleName

])

Gets a DeploymentReference for a studyDeploymentId and primaryDeviceRoleName. studyDeploymentId and primaryDeviceRoleName can be omitted if already specified as part of this service's study.

deviceDeployed

1. @override

Future<StudyDeploymentStatus> deviceDeployed(

1. String studyDeploymentId,
2. String primaryDeviceRoleName,
3. DateTime deviceDeploymentLastUpdatedOn

)

override

Tells stakeholders in the study deployment with studyDeploymentId that the device with primaryDeviceRoleName was deployed successfully, using the device deployment with timestamp deviceDeploymentLastUpdatedOn, i.e., that the study deployment was loaded on the device and that the necessary runtime is available to run it.

CAWS throws IllegalArgumentException when:

• a deployment with studyDeploymentId does not exist
• primaryDeviceRoleName is not present in the deployment
• the deviceDeploymentLastUpdatedOn does not match the expected timestamp of the deployment, indicating that the deployment on the device is outdated and needs to be updated before it can be deployed.

CAWS throws IllegalStateException when the deployment cannot be deployed yet, or the deployment has stopped.

getDeviceDeploymentFor

1. @override

Future<SmartphoneDeployment> getDeviceDeploymentFor(

1. String studyDeploymentId,
2. String primaryDeviceRoleName

)

override

Gets the deployment for the primary device with primaryDeviceRoleName in the study deployment with studyDeploymentId.

The PrimaryDeviceDeployment from CAWS is returned as a SmartphoneDeployment.

CAWS throws IllegalArgumentException when:

• a deployment with studyDeploymentId does not exist
• primaryDeviceRoleName is not present in the deployment
• the device with primaryDeviceRoleName has not yet been registered

CAWS throws IllegalStateException when the deployment for the requested primary device is not yet available.

getStudyDeploymentStatus

1. @override

Future<StudyDeploymentStatus> getStudyDeploymentStatus(

1. String studyDeploymentId

)

override

Gets the status for a study deployment with the given studyDeploymentId.

CAWS throws IllegalArgumentException when a deployment with studyDeploymentId does not exist.

getStudyDeploymentStatusList

1. @override

Future<List<StudyDeploymentStatus>> getStudyDeploymentStatusList(

1. List<String> studyDeploymentIds

)

override

Gets the status for a set of deployments with the specified studyDeploymentIds. If studyDeploymentIds is empty, an empty list is returned.

CAWS throws IllegalArgumentException when studyDeploymentIds contains an ID for which no deployment exists.

registerDevice

1. @override

Future<StudyDeploymentStatus> registerDevice(

1. String studyDeploymentId,
2. String deviceRoleName,
3. DeviceRegistration registration

)

override

Registers the device with the specified deviceRoleName for the study deployment with studyDeploymentId. The registration contains a matching configuration for the device with deviceRoleName.

A CamsDeviceRegistration is sent as a DefaultDeviceRegistration (workaround for CAWS issue #561).

CAWS throws IllegalArgumentException when:

• a deployment with studyDeploymentId does not exist
• deviceRoleName is not present in the deployment or is already registered and a different registration is specified than a previous request
• registration is invalid for the specified device or uses a device ID which has already been used as part of registration of a different device

CAWS throws IllegalStateException when this deployment has stopped.

removeStudyDeployments

1. @override

Future<Set<String>> removeStudyDeployments(

1. Set<String> studyDeploymentIds

)

override

Not supported from the client side; always throws a CarpServiceException.

stop

1. @override

Future<StudyDeploymentStatus> stop(

1. String studyDeploymentId

)

override

Asks CAWS to stop the study deployment with the specified studyDeploymentId and returns its updated status. This call does not itself stop data collection in the local sensing runtime.

CAWS throws IllegalArgumentException when a deployment with studyDeploymentId does not exist.

unregisterDevice

1. @override

Future<StudyDeploymentStatus> unregisterDevice(

1. String studyDeploymentId,
2. String deviceRoleName

)

override

Unregisters the device with the specified deviceRoleName for the study deployment with studyDeploymentId.

CAWS throws IllegalArgumentException when:

• a deployment with studyDeploymentId does not exist
• deviceRoleName is not present in the deployment

CAWS throws IllegalStateException when this deployment has stopped.