Class SensingAgent

An agent that observes data collected by the app and controls sensing parameters. See the adaptive sensing article for more information.

Inheritance

System.Object

SensingAgent

ExampleAccelerationSensingAgent

AsplSensingAgent

Implements

System.ComponentModel.INotifyPropertyChanged

Namespace: Sensus.Adaptation

Assembly: Sensus.Shared.NuGet.dll

Syntax

public abstract class SensingAgent : Object, INotifyPropertyChanged

Constructors

SensingAgent(String, String, TimeSpan)

Initializes a new instance of the Sensus.SensingAgent class, without a repeating action call.

Declaration

protected SensingAgent(string id, string description, TimeSpan controlCompletionCheckInterval)

Parameters

Type	Name	Description
System.String	id	Identifier.
System.String	description	Description.
System.TimeSpan	controlCompletionCheckInterval	Control completion check interval.

SensingAgent(String, String, TimeSpan, TimeSpan, TimeSpan)

Initializes a new instance of the Sensus.SensingAgent class, with a repeating action call.

Declaration

protected SensingAgent(string id, string description, TimeSpan controlCompletionCheckInterval, TimeSpan actionInterval, TimeSpan observationDuration)

Parameters

Type	Name	Description
System.String	id	Identifier.
System.String	description	Description.
System.TimeSpan	controlCompletionCheckInterval	Control completion check interval.
System.TimeSpan	actionInterval	Action interval.
System.TimeSpan	observationDuration	Observation duration.

Properties

ActionInterval

Interval of time between successive calls to ActAsync(CancellationToken). If null, then a repeating call to ActAsync(CancellationToken) will not be made and only calls to ObserveAsync(IDatum, CancellationToken) will provide opportunities for the SensingAgent to control sensing parameters.

Declaration

public Nullable<TimeSpan> ActionInterval { get; set; }

Property Value

Type	Description
System.Nullable<System.TimeSpan>	The action interval.

ActionIntervalToleranceAfter

Tolerance for ActionInterval after the scheduled time, if doing so will increase the number of batched actions and thereby decrease battery consumption.

Declaration

public Nullable<TimeSpan> ActionIntervalToleranceAfter { get; set; }

Property Value

Type	Description
System.Nullable<System.TimeSpan>	The delay tolerance before.

ActionIntervalToleranceBefore

Tolerance for ActionInterval before the scheduled time, if doing so will increase the number of batched actions and thereby decrease battery consumption.

Declaration

public Nullable<TimeSpan> ActionIntervalToleranceBefore { get; set; }

Property Value

Type	Description
System.Nullable<System.TimeSpan>	The delay tolerance before.

ActiveObservationDuration

How long to observe data before checking control criteria. If ActionInterval is not null, then this value may not be null either. If ActionInterval is null, then this value is ignored.

Declaration

public Nullable<TimeSpan> ActiveObservationDuration { get; set; }

Property Value

Type	Description
System.Nullable<System.TimeSpan>	The observation interval.

ControlCompletionCheckInterval

How much time between checks for control completion.

Declaration

public TimeSpan ControlCompletionCheckInterval { get; set; }

Property Value

Type	Description
System.TimeSpan	The control completion check interval.

Description

Readable description for the SensingAgent.

Declaration

public string Description { get; set; }

Property Value

Type	Description
System.String	The description.

Id

Unique identifier for the SensingAgent.

Declaration

public string Id { get; set; }

Property Value

Type	Description
System.String	The identifier.

MaxObservedDataAge

Maximum age of observed IDatum readings to retain for state estimation. Can be null to place no limit on the age of retained readings; however, either MaxObservedDataCount or MaxObservedDataAge should be enabled, or readings will be retained indefinitely, likely exhausting memory over time. This setting applies to all IDatum regardless of type. As different types of IDatum have dramatically different data rates (e.g., IAccelerometerDatum versus IActivityDatum), this should be set sufficiently high to avoid data loss.

Declaration

public Nullable<TimeSpan> MaxObservedDataAge { get; set; }

Property Value

Type	Description
System.Nullable<System.TimeSpan>	The max observed data age.

MaxObservedDataCount

Maximum number of observed IDatum readings to retain for state estimation. Can be null to place no limit on the number of retained readings; however, either MaxObservedDataCount or MaxObservedDataAge should be enabled, or readings will be retained indefinitely, likely exhausting memory over time. This setting applies to all IDatum regardless of type. As different types of IDatum have dramatically different data rates (e.g., IAccelerometerDatum versus IActivityDatum), this should be set sufficiently high to avoid data loss.

Declaration

public Nullable<int> MaxObservedDataCount { get; set; }

Property Value

Type	Description
System.Nullable<System.Int32>	The max observed data count.

Protocol

Gets the IProtocol.

Declaration

public IProtocol Protocol { get; set; }

Property Value

Type	Description
IProtocol	The protocol.

SensusServiceHelper

Gets the ISensusServiceHelper.

Declaration

public ISensusServiceHelper SensusServiceHelper { get; set; }

Property Value

Type	Description
ISensusServiceHelper	The sensus service helper.

State

Current SensingAgentState of the SensingAgent.

Declaration

public SensingAgentState State { get; }

Property Value

Type	Description
SensingAgentState	The state.

StateDescription

A human-readable description of the SensingAgent's current state. Used to track the state trajectory of the SensingAgent and to tag each IDatum produced while the SensingAgent is exerting sensing control.

Declaration

public string StateDescription { get; protected set; }

Property Value

Type	Description
System.String	The state description.

Methods

ActAsync(CancellationToken)

Requests that the SensingAgent consider beginning sensing control.

Declaration

public Task<SensingAgent.ControlCompletionCheck> ActAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	Cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task<SensingAgent.ControlCompletionCheck>	A SensingAgent.ControlCompletionCheck to be configured upon return, or null for no such check.

AverageLinearAccelerationMagnitudeExceedsThreshold(Double)

Checks whether the acceleration magnitude exceeds a threshold.

Declaration

protected bool AverageLinearAccelerationMagnitudeExceedsThreshold(double threshold)

Parameters

Type	Name	Description
System.Double	threshold	Threshold.

Returns

Type	Description
System.Boolean	true, if average linear magnitude exceeds threshold, false otherwise.

GetObservedData<DatumInterface>()

Gets observed IDatum objects for a particular type.

Declaration

protected List<IDatum> GetObservedData<DatumInterface>()
    where DatumInterface : IDatum

Returns

Type	Description
System.Collections.Generic.List<IDatum>	The observed data.

Type Parameters

Name	Description
DatumInterface	The type of data to retrieve.

InitializeAsync()

Initializes the SensingAgent. This is called when the IProtocol associated with this SensingAgent is started.

Declaration

public virtual Task InitializeAsync()

Returns

Type	Description
System.Threading.Tasks.Task

IsNearSurface()

Checks whether device is near a surface, according to the most recent IProximityDatum.

Declaration

protected bool IsNearSurface()

Returns

Type	Description
System.Boolean	true, if surface was neared, false otherwise.

ObserveAsync(IDatum, CancellationToken)

Asks the agent to observe an IDatum object that was generated by Sensus, either during OpportunisticObservation or during ActiveObservation.

Declaration

public Task<SensingAgent.ControlCompletionCheck> ObserveAsync(IDatum datum, CancellationToken cancellationToken)

Parameters

Type	Name	Description
IDatum	datum	Datum.
System.Threading.CancellationToken	cancellationToken	Cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task<SensingAgent.ControlCompletionCheck>	A SensingAgent.ControlCompletionCheck to be configured upon return, or null for no such check.

ObservedDataMeetControlCriterion(Dictionary<Type, List<IDatum>>)

Checks whether the observed data meet a control criterion. Will be called during OpportunisticObservation and ActiveObservation to check whether the observed data meet the control criterion, as well as during OpportunisticControl and ActiveControl to check whether the observed data continue to meet a control criterion and thus require control to continue.

Declaration

protected abstract bool ObservedDataMeetControlCriterion(Dictionary<Type, List<IDatum>> typeData)

Parameters

Type	Name	Description
System.Collections.Generic.Dictionary<System.Type, System.Collections.Generic.List<IDatum>>	typeData	All data by type. This collection will be locked prior to calling the concrete implementation.

Returns

Type	Description
System.Boolean	true, if data meet control criterion, false otherwise.

OnStateChangedAsync(SensingAgentState, SensingAgentState, CancellationToken)

Declaration

protected virtual Task OnStateChangedAsync(SensingAgentState previousState, SensingAgentState currentState, CancellationToken cancellationToken)

Parameters

Type	Name	Description
SensingAgentState	previousState
SensingAgentState	currentState
System.Threading.CancellationToken	cancellationToken

Returns

Type	Description
System.Threading.Tasks.Task

ProtectedSetPolicyAsync(JObject)

Implemented by the concrete class to set the SensingAgent's policy.

Declaration

protected abstract Task ProtectedSetPolicyAsync(JObject policy)

Parameters

Type	Name	Description
Newtonsoft.Json.Linq.JObject	policy	Policy.

Returns

Type	Description
System.Threading.Tasks.Task	The set policy async.

SetPolicyAsync(JObject)

Sets the control policy of the current SensingAgent. This method will be called in the following situations:

• When a push notification arrives with a new policy.
• When the SensingAgent itself instructs the app to update the policy, through a call to UpdateSensingAgentPolicyAsync(CancellationToken).
• When the user manually sets the policy from with the Protocol settings.

In any case, the new policy will be passed to this method as a Newtonsoft.Json.Linq.JObject.

Declaration

public Task SetPolicyAsync(JObject policy)

Parameters

Type	Name	Description
Newtonsoft.Json.Linq.JObject	policy	Policy.

Returns

Type	Description
System.Threading.Tasks.Task

ToString()

Declaration

public override string ToString()

Returns

Type	Description
System.String

UpdateObservedData(Dictionary<Type, List<IDatum>>)

Updates the observed data (e.g., by trimming observed data to a particular size and/or time range). When overriding this method, be sure to call the base class implementation if you wish to apply the size and age restrictions provided here.

Declaration

protected virtual void UpdateObservedData(Dictionary<Type, List<IDatum>> typeData)

Parameters

Type	Name	Description
System.Collections.Generic.Dictionary<System.Type, System.Collections.Generic.List<IDatum>>	typeData	Observed data, by type. This collection will be locked prior to calling the method.

Events

PropertyChanged

Declaration

public event PropertyChangedEventHandler PropertyChanged

Event Type

Type	Description
System.ComponentModel.PropertyChangedEventHandler

Implements

System.ComponentModel.INotifyPropertyChanged