Screen Light Extractor

Table of Contents

Introduction

The screen light extractor allows you to monitor whether the screen of the client is lit or dim. There are two light extractors available in the framework. The first extractor works periodically with a configurable period, and the second extractor works whenever the status of the screen light is updated.

This tutorial will cover the basics of how to to implement these extractors to dynamically monitor and access the status of the screen light.

Prerequisites

We could check for the presence of a screen for the Android device as a prerequisite. However, we make the assumption that the device will always have a screen. Thus, the function reqSatisfied() for this extractor never throws any exception. However, if there were prerequisites that the extractor does not meet, reqSatisfied() would throw a ExtractorPrerequisiteUnsatisfiedException instead of returning void , so we still include a try-catch statement. Further details about this method can be found on the extractors and estimators page. Again, this function does not throw any exceptions.

Periodic Screen Light Extractor

The periodic screen extractor will try to obtain the screen light data at the specified period and add the point to the encapsulator specified upon instantiation. To initialize a periodic screen extractor, we first define the period (5 minutes in our example), next we create a backable encapsulator which will store the screen light data. The TimeZonedTimestampedObject is of type Boolean since the screen light only has two states: on and off.

We also add a listener which gets triggered when the screen light data is updated.

The above steps are implemented using the following code:

int period = 5 * 60 * 1000; // 5 minutes
DataJobIdentifier ScreenLightID = new DataJobIdentifier("Screen Light");
BackableEncapsulator<TimeZonedTimestampedObject<Boolean>> ScreeenLightData = new BackableEncapsulator<TimeZonedTimestampedObject<Boolean>>(ScreenLightID);
ScreenLightData.addListener(new SendDataAtFullListener());

We can now instantiate a screen light data collector that updates periodically:

ScreenLightDataCollector periodicScreenLight = new ScreenLightDataCollector(ScreeenLightData, period, this.getApplicationContext());

Finally, we can start the extractor, once we make sure that the necessary prerequisites are satisfied. In our case, since we make the assumption that the device has a screen, the extractor will always pass the check and start. However, if there were prerequisites that the extractor does not meet, reqSatisfied() would throw a ExtractorPrerequisiteUnsatisfiedException instead of returning void , so we include a try-catch statement.

try {
    periodicScreenLight.reqSatisfied();
    periodicScreenLight.start();
} catch (ExtractorPrerequisiteUnsatisfiedException e) {
    // The prerequisites of the extractor were not met
}

Now, the state of the screen light will be periodically updated to the backable encapsulator.

To stop running the extractor, call the screen light extractor’s terminate() method.

Event Based Screen Light Extractor

The event based screen light extractor will update the encapsulator only when a change in the state of the screen light occurs. So instead of collecting data at a fixed time period, it will do so only when the screen light turns on or off.

Just like we did for the periodic extractor, we will first initialize the extractor and then create a backable encapsulator which will store the screen light data. We also add a listener which gets triggered when the screen light data is updated.

DataJobIdentifier ScreenLightID = new DataJobIdentifier("Screen Light");
BackableEncapsulator<TimeZonedTimestampedObject<Boolean>> ScreeenLightData = new BackableEncapsulator<TimeZonedTimestampedObject<Boolean>>(ScreenLightID);
ScreenLightData.addListener(new SendDataAtFullListener());

We can now instantiate a screen light data collector that updates on change of state:

ScreenLightDataCollectorEventBased screenLight = new ScreenLightDataCollectorEventBased(ScreeenLightData, this.getApplicationContext());

We can now start the extractor, once we make sure that the necessary prerequisites are satisfied. Again, in our case, we assume that a screen comes with the device, so the extractor will always start.

try {
    periodicScreenLight.reqSatisfied();
    periodicScreenLight.start();
} catch (ExtractorPrerequisiteUnsatisfiedException e) {
    // The prerequisites of the extractor were not met
}

Now, the state of the screen light will be updated to the backable encapsulator every time it changes.

To stop running the extractor, call the event based screen light extractor’s terminate() method.

Running Example

(TODO: complete)

Privacy-Aware Health Telemonitoring