Merge branch 'aspl-agent' into develop

DocFX/articles/adaptive-sensing.md

@@ -47,24 +47,27 @@ criterion might specify that sensing control should occur when the average accel
 magnitude exceeds a critical threshold. This is demonstrated in the 
 [example](https://github.com/predictive-technology-laboratory/sensus/blob/develop/ExampleSensingAgent.Shared/ExampleAccelerationSensingAgent.cs)
 sensing agent. This agent also demonstrates a control criterion based on proximity of the phone
-to a surface (e.g., face).
+to a surface (e.g., face) and user activities (e.g., walking).
 
-* Control completion check interval:  Once sensing control is invoked, the app will periodically 
+* Control completion check interval:  Once sensing control is invoked, the agent will periodically 
 recheck the control criterion to determine whether it is still met. If the criterion is not met, 
 then sensing control ends, the sensing agent transitions sensing settings as needed (e.g., reducing
 sampling rates), and the sensing agent returns to its idle state. If the criterion is still met, 
 then sensing control continues unabated until the next completion check occurs. This parameter governs 
-how long Sensus should wait between each completion check.
+how long the agent should wait between each completion check.
 
-## Android
+Sensus supports two mechanisms for incorporating sensing agents into a study. The first involves
+writing software (in C#) to define the sensing agent. The second involves defining the agent
+in a JSON-based specification language. The following sections provide more information about these
+two alternatives.
 
-### Sensing Agent Plug-Ins
-On Android, Sensus supports a plug-in architecture for modules (or agents) that control Sensing configuration.
-This architecture is intended to support research into adaptive sensing by providing a simple interface
-through which researchers can deploy agents that implement specific adaptation approaches.
+## Software-Defined Sensing Agents
 
-### Implementing and Deploying a Sensing Agent Plug-In
-Follow the steps below to implement and deploy a sensing agent within your Sensus study.
+### Android
+On Android, Sensus supports a plug-in architecture for software-defined sensing agents.
+This architecture is intended to support research into adaptive sensing by providing a simple interface
+through which researchers can deploy agents that implement specific adaptation approaches. Follow the 
+steps below to implement and deploy an Android sensing agent.
 
 1. Create a new Android Class Library project in Visual Studio. In Visual Studio for Mac, the following image
 shows the correct selection:
@@ -73,60 +76,119 @@ shows the correct selection:
 
 1. Add a NuGet reference to [the Sensus package](https://www.nuget.org/packages/Sensus).
 
-1. Add a new class that inherits from <xref:Sensus.SensingAgent>. Be sure to provide a parameterless constructor
+1. Add a new class that inherits from <xref:Sensus.Adaptation.SensingAgent>. Be sure to provide a parameterless constructor
 for your class, as this constructor will be called at run time to create your agent. Your class will be required
-to override a few methods related to control. These methods are where your sensing agent should execute its control 
-policy. The <xref:Sensus.SensingAgent> class provides a set of predefined control criterion functions 
-[here](https://github.com/predictive-technology-laboratory/sensus/blob/develop/Sensus.Shared.NuGet/SensingAgentControlCriteria.cs).
-You can call these diretly from your code or write your own in order to suit your adaptation requirements.
+to override a few methods related to sensing control. These methods are where your sensing agent should execute its control 
+policy. The <xref:Sensus.Adaptation.SensingAgent> class provides a set of predefined control criterion functions 
+[here](https://github.com/predictive-technology-laboratory/sensus/blob/develop/Sensus.Shared.NuGet/Adaptation/SensingAgentControlCriteria.cs).
+You can call these diretly from your code or write your own functions to suit your adaptation requirements.
 
 1. Build the library project, and upload the resulting .dll to a web-accessible URL. A convenient
 solution is to upload the .dll to a Dropbox directory and copy the sharing URL for the .dll file.
 
 1. Generate a QR code that points to your .dll (e.g., using [QR Code Generator](https://www.qr-code-generator.com/)).
 The content of the QR code must be exactly as shown below:
-```
+```plain
 sensing-agent:URL
 ```
 where URL is the web-accessible URL that points to your .dll file. If you are using Dropbox, then the QR code
 content will be similar to the one shown below (note the `dl=1` ending of the URL, and note that the following 
 URL is only an example -- it is not actually valid):
-```
+```plain
 sensing-agent:https://www.dropbox.com/s/dlaksdjfasfasdf/SensingAgent.dll?dl=1
 ```
 
 1. In your <xref:Sensus.Protocol> settings, tap "Set Agent" and scan your QR code. Sensus will fetch your .dll file and 
 extract any agent definitions contained therein. Select your desired agent.
 
 1. Continue with [configuration](xref:protocol_creation) and [distribution](xref:protocol_distribution)
-of your protocol.
+of your protocol. When run, your protocol will invoke the selected sensing agent according to the state diagram shown
+above.
 
-### Example Sensing Agents
-See the following implementations for example agents:
+See the following implementation for an example:
 
 * [Acceleration](xref:ExampleSensingAgent.ExampleAccelerationSensingAgent) (code [here](https://github.com/predictive-technology-laboratory/sensus/blob/develop/ExampleSensingAgent.Shared/ExampleAccelerationSensingAgent.cs)):  A 
 sensing agent that samples continuously if the device is moving or near a surface (e.g., face).
 
-## iOS
-
+### iOS
 In contrast with Android, iOS does not allow apps to load code (e.g., from the above .dll assembly) at
-run time. Thus, adaptive sensing agents are more limited on iOS compared with Android. Here are the options:
+run time. Thus, software-defined adaptive sensing agents are more limited on iOS compared with Android. Here 
+are the options:
 
-* The app comes with one example sensing agent; however, it is simply for demonstration and is unlikely to work
-well in practice. Nonetheless, the examples is:
-
-  * [Acceleration](xref:ExampleSensingAgent.ExampleAccelerationSensingAgent) (code [here](https://github.com/predictive-technology-laboratory/sensus/blob/develop/ExampleSensingAgent.Shared/ExampleAccelerationSensingAgent.cs)):  A 
-sensing agent that samples continuously if the device is moving or near a surface (e.g., face).
-
-You can select this agent when configuring the <xref:Sensus.Protocol>.
+* The app comes with one 
+[example](xref:ExampleSensingAgent.ExampleAccelerationSensingAgent) sensing agent (code 
+[here](https://github.com/predictive-technology-laboratory/sensus/blob/develop/ExampleSensingAgent.Shared/ExampleAccelerationSensingAgent.cs)); 
+however, this is simply for demonstration and is unlikely to work well in practice. Nonetheless, you 
+can select this agent when configuring the <xref:Sensus.Protocol>.
 
 * You can [redeploy](xref:redeploying) Sensus as your own app, to which you can add your own agent implementations.
 
 * You can implement your own agent implementations following the instructions above for Android and email 
-our team ([email protected]) to include them in a future release.
+our team ([email protected]) to include your implementation in a future release of the iOS app.
+
+## Adaptive Sensing Policy Language (ASPL) Defined Sensing Agents
+In addition to the software-defined adaptive sensing agents described above, Sensus supports the definition
+of sensing agents in a general-purpose adaptive sensing policy language (ASPL). ASPL specifies both the 
+control criteria as well as the control actions depicted in the above state diagram. The 
+[example ASPL policy file](https://github.com/predictive-technology-laboratory/sensus/blob/develop/Sensus.Shared/Adaptation/example-aspl-policy.json)
+demonstrates the ASPL format. The elements of the format are described in the documentation for
+<xref:Sensus.Adaptation.SensingAgent> and <xref:Sensus.Adaptation.AsplSensingAgent>. If more than 1 
+<xref:Sensus.Adaptation.AsplStatement> is provided to the <xref:Sensus.Adaptation.AsplSensingAgent>, 
+then the first one whose criterion is satisfied by the observed data will be used for sensing control.
+
+In the example ASPL policy file, you will see many places where property types and property names are specified. In
+general, each <xref:Sensus.Adaptation.AsplElement> will specify a property type that is the fully-qualified 
+name of a <xref:Sensus.Datum> sub-type. The fully-qualified type name is the concatenation of the type's namespace
+and name. For example, the <xref:Sensus.Probes.Movement.AccelerometerDatum> type has namespace `Sensus.Probes.Movement` 
+and name `AccelerometerDatum`. The fully-qualified type name is thus `Sensus.Probes.Movement.AccelerometerDatum`. 
+You can find the namespace for each type in the API documentation (e.g., see 
+[here](<xref:Sensus.Probes.Movement.AccelerometerDatum>)). The API documentation page for each type also lists
+the properties available for that type (e.g., 
+[here](https://predictive-technology-laboratory.github.io/sensus/api/Sensus.Probes.Movement.AccelerometerDatum.html#properties)).
+So, for example, if you wish to specify the <xref:Sensus.Probes.Movement.AccelerometerDatum.X> 
+property within the <xref:Sensus.Adaptation.AsplElement>, then the property type should be 
+`Sensus.Probes.Movement.AccelerometerDatum` and the property name should be `X`.
+
+The other places where property types and property names appear in ASPL are the 
+<xref:Sensus.Adaptation.AsplStatement.BeginControlSettings> and <xref:Sensus.Adaptation.AsplStatement.EndControlSettings>.
+These types and names refer to the <xref:Sensus.Probes.Probe> properties that should be changed to begin and end sensing control.
+For example, you may wish to begin control by enabling the <xref:Sensus.Probes.Movement.AccelerometerProbe> with a sampling 
+rate of 50 Hz. This involves two settings:  (1) enabling the probe, and (2) setting the sampling rate. Each of these
+is specified within a <xref:Sensus.ProtocolSetting> in the ASPL JSON.
+
+## Softare- Versus ASPL-Defined Sensing Agents
+There are pros and cons of software- and ASPL-defined sensing agents:
+
+* Software-Defined
+  * Pros:  Sophistication of control criteria. Actions are not limited to the logical structure of ASPL. Any 
+  criterion that can be implemented in C# would be feasible.
+  * Cons:  Low-level programming is required. Third-party deployment of iOS agents is complicated
+  by iOS's prohibition of run-time code loading (see above). Changing the agent definition (whether on Android
+  or iOS) involves modifying code and, for iOS, redeploying the application.
+
+* ASPL-Defined
+  * Pros:  Agent definitions use the relatively simple ASPL syntax. Agent definitions can be loaded at run-time 
+  into both Android and iOS without the need for code changes or app redeployment.
+  * Cons:  ASPL has limited logical expressiveness.
+
+## Distributing Sensing Agent Policies
+Regardless of whether a software- or ASPL-defined sensing agent is used, a policy must be provided to the
+agent, specifying the agent's control parameters. This can be done in two ways:
+
+* Set within protocol:  In the protocol settings, tap "Set Agent Policy", then select your JSON policy file. This 
+works well to set the initial policy used by the sensing agent; however, this is not a very effective means of 
+providing updated sensing policies to users during an ongoing study. Updating the policy would require the study
+administrator to edit the protocol and distribute the new protocol to all users (e.g., via email), who would then 
+need to manually update their protocols.
+
+* Send via push notification:  Request a 
+[push notification update](https://github.com/predictive-technology-laboratory/sensus/blob/develop/Scripts/ConfigureAWS/ec2-push-notifications/example-requests.json)
+with the `type` set to <xref:Sensus.Notifications.PushNotificationUpdateType.SensingAgentPolicy> and `content` set to the 
+policy you wish to provide. Sensus will parse the `content` into a JSON object and pass the resulting object to your
+agent via <xref:Sensus.Adaptation.SensingAgent.ProtectedSetPolicyAsync>. This is an effective option for updating the sensing 
+agent's policy during ongoing studies, as users will not need to do anything in order to receive the updated policies.
 
 ## Testing and Debugging
-
 Regardless of whether your sensing agent targets Android or iOS, there are a few ways to test and debug it:
 
 * Monitor the agent state:  Within your <xref:Sensus.Protocol> settings, tap "View Agent State" to see a real-time
@@ -144,3 +206,30 @@ messages will appear for a short duration.
 run Sensus in the debugger with your sensing agent. You will need to add your agent code to the Sensus app projects in order to 
 step through it in the debugger.
 
+## Known Limitations and Future Improvements
+
+* Initiation of continuous sensing from the background on iOS:  iOS places significant constraints on Sensus's ability
+to operate in the background. This impacts all sensing agents' ability to initiate continuous sensing from the background. 
+A sensing agent will be able to update its state estimtes from the background upon receipt of a push notification; however, 
+there is no known way to initiate continuous background operation while in the background state. As a result, if the agent's 
+state estimate indicates that continuous sensing control is warranted, then this control will not be initiated until the 
+next time the app is brought to the foreground by the user. It would be useful to add the option of notifying the user from 
+the background when continuous sensing is requested by the sensing agent.
+
+* Termination of sensing control:  Currently, sensing control (whether opportunistic or active) can only be terminated
+after the control completion check interval elapses. This is probably too coarse, and it would be helpful to complement
+this check with checks run after a certain number of data readings have been observed while in a control state.
+
+## Data Streams
+In addition to directly impacting the data streams that are collected (e.g., via sampling rates and enabling/disabling
+[probes](<xref:Sensus.Probes.Probe)), the use of a sensing agent will cause additional data to be written to the 
+[local data store](xref:Sensus.DataStores.Local.LocalDataStore). These include:
+
+* Datum-level tagging:  Each <xref:Sensus.Datum> collected by the app will be tagged with a description of the sensing 
+agent's state at the time when the <xref:Sensus.Datum> was collected. This is achieved by setting 
+<xref:Sensus.Datum.SensingAgentStateDescription> to the value of <xref:Sensus.Adaptation.SensingAgent.StateDescription>.
+
+* Sensing agent lifecycle:  Each time the sensing agent transitions from one state to another, a 
+<xref:Sensus.Adaptation.SensingAgentStateDatum> will be written to the 
+[local data store](xref:Sensus.DataStores.Local.LocalDataStore) to record the transition. This will be done regardless 
+of whether any other <xref:Sensus.Datum> readings are collected.

DocFX/articles/authentication-servers.md

@@ -3,5 +3,47 @@ uid: authentication_servers
 ---
 
 # Authentication Servers
+Authentication servers allow backend infrastructure to manage accounts and
+credentials that are used by Sensus.
 
-TODO
+## Required REST Endpoints
+
+## Updating Protocols Mid-Study
+Since the authentication server is able to serve up new versions of protocols
+mid-study, care should be taken when editing protocols for distribution. The
+steps below constitute the recommended approach for editing a protocol mid-study
+when using an authentication server.
+
+1. Delete all existing protocols from Sensus.
+1. Scan a study QR code to pull down the most current version of the protocol
+from the authentication server.
+1. Edit the protocol as desired.
+1. Run the edited protocol on your phone to test the new settings. Test for a
+period sufficient to exercise all desired functionality (data collection, EMAs,
+etc.) It is important to test changes before distributing the new protocol 
+version to participants.
+1. Stop the protocol on your testing phones.
+1. After testing the new settings, set the protocol's identifier from within 
+the protocol settings. Use a random identifier to mark the new version. Setting 
+a new protocol identifier is crucial, as it signals participants' devices to 
+update their protocols to the new version. If multiple protocols are used within 
+a single study (e.g., one for Android and one for iOS), ensure that the identifiers 
+match across protocols. If you need to transfer the new protocol identifier from
+one protocol (e.g., iOS) to another (e.g., Android), copy the new identifier
+(tap the "Copy Identifier" button for convenience), email it to yourself, and
+set the new identifier within the other protocol.
+1. From within Sensus on your phone(s), share the protocol(s) with the person 
+responsible for uploading protocols into the authentication server. The best way
+to share the protocol is to edit it and tap the "Share" button from within the
+protocol settings.
+1. After confirming upload into the authentication server, delete the protocol 
+from your phone, rescan the study QR code to pull down the new version from the
+authentication server, inspect the protocol to confirm that it reflects your 
+edits and the new protocol identifier, and run the new version of the protocol 
+to test it again.
+
+There is no need to notify participants about the update. Within a few hours, 
+their devices will notice that the protocol identifier provided by the 
+authentication server is different from the identifier in the protocol running
+on their devices. When this happens, participant devices will automatically 
+pull down the new protocol and use it to replace their existing protocols.

DocFX/articles/redeploying-sensus.md

@@ -25,12 +25,6 @@ in-app visualization of certain data streams.
 You should carefully inspect the terms and conditions associated with other libraries and packages consumed by 
 Sensus to ensure that your intended use is compliant.
 
-## Facebook API
-
-Sensus uses the Facebook API to collect public profile information from users who grant this permission. To do this, 
-visit the [Facebook developer console](https://developers.facebook.com) and create a new app, noting your app name and ID.
-If you do not do this, you will not be able to use the [Facebook Probe](xref:Sensus.Probes.Apps.FacebookProbe).
-
 ## Keys and IDs
 Edit the following fields of `Sensus.SensusServiceHelper.cs` (in the `Sensus.Shared` project):
 
@@ -121,9 +115,6 @@ services and then associate these servies with your app before compiling and dep
      <permission android:name="edu.virginia.sie.ptl.sensus.permission.MAPS_RECEIVE" android:protectionLevel="signature" />
      ```
    
-1. If you wish to use the [Facebook Probe](xref:Sensus.Probes.Apps.FacebookProbe) to collect public profile information from 
-   users who explicitly permit it, then add your Facebook app name and ID to the `Sensus.Android/Resources/values/strings.xml` file.
-   
 ## Sensus iOS
 
 Sensus iOS consumes services provided by Apple. Since these services and their authorized consumers are tied
@@ -141,14 +132,8 @@ services and then associate these servies with your app.
    * `CFBundleDisplayName`
    * `CFBundleIdentifier`
    * Each `CFBundleURLSchemes` element under `CFBundleURLTypes`
-   * `FacebookAppID`
-   * `FacebookDisplayName`
    * `CFBundleDocumentTypes`
    * Elements under `UTExportedTypeDeclarations`
    * `CFBundleShortVersionString`
    * `CFBundleVersion`
-   * Each of the usage descriptions.
-
-1. If you wish to use the [Facebook Probe](xref:Sensus.Probes.Apps.FacebookProbe) to collect public profile information from 
-   users who explicit permit it, then add your Facebook app name and ID to the `Sensus.iOS/AppDelegate.cs` file at the location 
-   indicated in the comments.
+   * Each of the usage descriptions.