Class Probe

Each Probe collects data of a particular type from the device. Sensus contains Probes for many of the hardware sensors present on many smartphones as well as several software events (e.g., receipt of SMS messages). Sensus also contains Probes that can prompt the user for information, which the user supplies via speech or textual input. Sensus defines a variety of Probes, with platform availability and quality varying by device manufacturer (e.g., Apple, Motorola, Samsung, etc.). Availability and reliability of Probes will depend on the device being used.

Inheritance

System.Object

Probe

ListeningProbe

PollingProbe

ScriptProbe

Implements

System.ComponentModel.INotifyPropertyChanged

IProbe

Namespace: Sensus.Probes

Assembly: SensusAndroid.dll

Syntax

public abstract class Probe : Object, INotifyPropertyChanged, IProbe

Constructors

Probe()

Declaration

protected Probe()

Properties

AllowDisableOnStartUp

Whether or not to allow the user to disable this Probe when starting the Protocol.

Declaration

[OnOffUiProperty("Allow Disable On Startup:", true, 5)]
public bool AllowDisableOnStartUp { get; set; }

Property Value

Type	Description
System.Boolean	Allow user to disable on start up.

Caption

Declaration

public string Caption { get; }

Property Value

Type	Description
System.String

CollectionDescription

Declaration

public abstract string CollectionDescription { get; }

Property Value

Type	Description
System.String

DataRateSampleSize

Declaration

protected abstract long DataRateSampleSize { get; }

Property Value

Type	Description
System.Int64

DatumType

Declaration

public abstract Type DatumType { get; }

Property Value

Type	Description
System.Type

DisplayName

Declaration

public abstract string DisplayName { get; }

Property Value

Type	Description
System.String

Enabled

Whether the Probe should be turned on when the user starts the Protocol.

Declaration

[OnOffUiProperty("Enabled:", true, 2)]
public bool Enabled { get; set; }

Property Value

Type	Description
System.Boolean	true if enabled; otherwise, false.

MaxChartDataCount

How much data to save from the Probe for the purpose of charting within the Sensus app.

Declaration

[EntryIntegerUiProperty("Max Chart Data Count:", true, 50, true)]
public int MaxChartDataCount { get; set; }

Property Value

Type	Description
System.Int32	The maximum chart data count.

MaxDataStoresPerSecond

Declaration

public abstract Nullable<double> MaxDataStoresPerSecond { get; set; }

Property Value

Type	Description
System.Nullable<System.Double>

MostRecentStoreTimestamp

Declaration

public Nullable<DateTimeOffset> MostRecentStoreTimestamp { get; }

Property Value

Type	Description
System.Nullable<System.DateTimeOffset>

OriginallyEnabled

Gets or sets whether or not this probe was originally enabled within the protocol. Some probes can become disabled when attempting to start them. For example, the temperature probe might not be supported on all hardware and will thus become disabled after its failed initialization. Thus, we need a separate variable (other than Enabled) to tell us whether the probe was originally enabled. We use this value to calculate participation levels and also to restore the probe before sharing it with others (e.g., since other people might have temperature hardware in their devices).

Declaration

public bool OriginallyEnabled { get; set; }

Property Value

Type	Description
System.Boolean	Whether or not this probe was enabled the first time the protocol was started.

Protocol

Declaration

public Protocol Protocol { get; set; }

Property Value

Type	Description
Protocol

RawParticipation

Declaration

protected abstract double RawParticipation { get; }

Property Value

Type	Description
System.Double

StartStopTimes

Gets a list of times at which the probe was started (tuple bool = True) and stopped (tuple bool = False). Only includes those that have occurred within the protocol's participation horizon.

Declaration

public List<Tuple<bool, DateTime>> StartStopTimes { get; }

Property Value

Type	Description
System.Collections.Generic.List<System.Tuple<System.Boolean, System.DateTime>>	The start stop times.

State

Declaration

public ProbeState State { get; }

Property Value

Type	Description
ProbeState

StoreData

Whether the Probe should store the data it collects. This might be turned off if the Probe is used to trigger the ScriptProbe but the probed data are not needed.

Declaration

[OnOffUiProperty("Store Data:", true, 3)]
public bool StoreData { get; set; }

Property Value

Type	Description
System.Boolean	true if store data; otherwise, false.

SubCaption

Declaration

public string SubCaption { get; }

Property Value

Type	Description
System.String

SuccessfulHealthTestTimes

Gets the successful health test times. Only includes those that have occurred within the protocol's participation horizon.

Declaration

public List<DateTime> SuccessfulHealthTestTimes { get; }

Property Value

Type	Description
System.Collections.Generic.List<System.DateTime>	The successful health test times.

Methods

add_MostRecentDatumChanged(Probe.MostRecentDatumChangedDelegateAsync)

Declaration

public void add_MostRecentDatumChanged(Probe.MostRecentDatumChangedDelegateAsync value)

Parameters

Type	Name	Description
Probe.MostRecentDatumChangedDelegateAsync	value

GetAll()

Declaration

public static List<Probe> GetAll()

Returns

Type	Description
System.Collections.Generic.List<Probe>

GetChart()

Declaration

public SfChart GetChart()

Returns

Type	Description
Syncfusion.SfChart.XForms.SfChart

GetChartDataPointFromDatum(Datum)

Declaration

protected abstract ChartDataPoint GetChartDataPointFromDatum(Datum datum)

Parameters

Type	Name	Description
Datum	datum

Returns

Type	Description
Syncfusion.SfChart.XForms.ChartDataPoint

GetChartPrimaryAxis()

Declaration

protected abstract ChartAxis GetChartPrimaryAxis()

Returns

Type	Description
Syncfusion.SfChart.XForms.ChartAxis

GetChartSecondaryAxis()

Declaration

protected abstract RangeAxisBase GetChartSecondaryAxis()

Returns

Type	Description
Syncfusion.SfChart.XForms.RangeAxisBase

GetChartSeries()

Declaration

protected abstract ChartSeries GetChartSeries()

Returns

Type	Description
Syncfusion.SfChart.XForms.ChartSeries

GetParticipation()

Gets the participation level for the current probe. If this probe was originally enabled within the protocol, then this will be a value between 0 and 1, with 1 indicating perfect participation and 0 indicating no participation. If this probe was not originally enabled within the protocol, then the returned value will be null, indicating that this probe should not be included in calculations of overall protocol participation. Probes can become disabled if they are not supported on the current device or if the user refuses to initialize them (e.g., by denying Health Kit). Although they become disabled, they were originally enabled within the protocol and participation should reflect this. Lastly, this will return null if the probe is not storing its data, as might be the case if a probe is enabled in order to trigger scripts but not told to store its data.

Declaration

public Nullable<double> GetParticipation()

Returns

Type	Description
System.Nullable<System.Double>	The participation level (null, or somewhere 0-1).

InitializeAsync()

Declaration

protected virtual Task InitializeAsync()

Returns

Type	Description
System.Threading.Tasks.Task

ProcessDataAsync(CancellationToken)

Instructs the current probe to process data that it has collected. This call does not provide the data to process. Rather, it is up to each probe to cache data in memory or on disk as appropriate, in such a way that they can be processed when this method is called. This method will only be called under suitable conditions (e.g., when the device is charging). Any Datum objects that result from this processing should be stored via calls to StoreDatumAsync(Datum, Nullable<CancellationToken>). The System.Threading.CancellationToken passed to this method should be monitored carefully when processing data. If the token is cancelled, then the data processing should abort immediately and the method should return as quickly as possible. The System.Threading.CancellationToken passed to this method should also be passed to StoreDatumAsync(Datum, Nullable<CancellationToken>), as this ensures that all operations associated with data storage terminate promptly if the token is cancelled. It is up to the overriding implementation to handle multiple calls to this method (even in quick succession and/or concurrently) properly.

Declaration

public virtual Task ProcessDataAsync(CancellationToken cancellationToken)

Parameters

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

Returns

Type	Description
System.Threading.Tasks.Task	The data async.

ProtectedStartAsync()

Declaration

protected virtual Task ProtectedStartAsync()

Returns

Type	Description
System.Threading.Tasks.Task

ProtectedStopAsync()

Declaration

protected virtual Task ProtectedStopAsync()

Returns

Type	Description
System.Threading.Tasks.Task

remove_MostRecentDatumChanged(Probe.MostRecentDatumChangedDelegateAsync)

Declaration

public void remove_MostRecentDatumChanged(Probe.MostRecentDatumChangedDelegateAsync value)

Parameters

Type	Name	Description
Probe.MostRecentDatumChangedDelegateAsync	value

ResetAsync()

Declaration

public virtual Task ResetAsync()

Returns

Type	Description
System.Threading.Tasks.Task

RestartAsync()

Declaration

public Task RestartAsync()

Returns

Type	Description
System.Threading.Tasks.Task

StartAsync()

Declaration

public Task StartAsync()

Returns

Type	Description
System.Threading.Tasks.Task

StopAsync()

Declaration

public Task StopAsync()

Returns

Type	Description
System.Threading.Tasks.Task

StoreDatumAsync(Datum, Nullable<CancellationToken>)

Stores a Datum within the System.LocalDataStore. Will not throw an System.Exception.

Declaration

public Task StoreDatumAsync(Datum datum, Nullable<CancellationToken> cancellationToken = null)

Parameters

Type	Name	Description
Datum	datum	Datum.
System.Nullable<System.Threading.CancellationToken>	cancellationToken	Cancellation token.

Returns

Type	Description
System.Threading.Tasks.Task

TestHealthAsync(List<AnalyticsTrackedEvent>)

Declaration

public virtual Task<HealthTestResult> TestHealthAsync(List<AnalyticsTrackedEvent> events)

Parameters

Type	Name	Description
System.Collections.Generic.List<AnalyticsTrackedEvent>	events

Returns

Type	Description
System.Threading.Tasks.Task<HealthTestResult>

Events

MostRecentDatumChanged

Fired when the most recently sensed datum is changed, regardless of whether the datum was stored.

Declaration

public event Probe.MostRecentDatumChangedDelegateAsync MostRecentDatumChanged

Event Type

Type	Description
Probe.MostRecentDatumChangedDelegateAsync

PropertyChanged

Declaration

public event PropertyChangedEventHandler PropertyChanged

Event Type

Type	Description
System.ComponentModel.PropertyChangedEventHandler

Implements

System.ComponentModel.INotifyPropertyChanged

IProbe