Context States Datasheet

Contents

Overview

This page contains a list of available Context States that can be sensed using the SDK. Each Context State provides particular context information, can be optionally configured with sensing settings and some of them may require device capabilities to be defined in your application's Package.appxmanifest file. If you are using the SDK in online mode in order to retrieve or push context states to cloud services, you will be required to use the corresponding scope in the authorization method to obtain user's permission. Device-based Context States are those that can be obtained in offline mode. Cloud-based Context States require to be in online mode (that is, to be signed in and with an available Internet connection) in order to retrieve or push them.

‍‍Device-based Context States

Activity Recognition (UWP only)

Sense the physical activity of the person carrying the device, such as if the user is sedentary, walking, running, etc. A confidence level as high or low is associated with each activity.

Item identifier

  • ContextType.ACTIVITY

State information

  • Physical activity name: "SEDENTARY", "WALKING", "RUNNING", "BIKING", "INCAR", "RANDOM", "NONE".
  • Recognized confidence level, 0 or 1 associated with each activity

Sensing Settings

For enabling the sensing of Activity Recognition context Type, we can specify a settings bundle that will configure the behavior of the sensing. The sensing can be triggered in an EVENT_BASED manner i.e. new items are generated via some sort of event eg change in activity. By default, all activities will be sensed by the device sensor.

Options

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in sql database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required Device Capabilities

  • Add <DeviceCapability Name = “activity”/> under the capabilities element of app manifest file- To access the activity sensor of the device.

Battery


Provides information about the system battery. A new battery item is notified on the battery events i.e. when there is a change in battery level/usage (e.g. plugged or unplugged) or significant change in energy level/usage (e.g. energy saving mode is turned on).

Item identifier

  • ContextType.BATTERY

State information

  • Battery level.
  • Battery presence.
  • Battery status.
  • Batter capacity.
  • Remaining battery charge in MilliwattHours.
  • Full Charge Capacity in MilliwattHours.
  • Plug/AC presence.
  • Hourly charging/discharging rate of the battery.
  • Energy saving mode status.

Sensing Settings

  • SensingType: This setting is used to make a choice of activities to be reported. The sensing is performed in an EVENT_BASED manner.

Options (BatteryOptions)

  • boolean LocalStorage - boolean to save information in sql database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required Device Capabilities

  • No special capabilities required.

Location


Provides information of significant locations from the device. Location is tracked every 50 seconds. A new item is created if there is a significant change of location.

Item identifier

  • ContextType.LOCATION

State information

  • Activity:
    • "IN" (entering a previous inferred fence).
  • Coordinates: "latitude", "longitude".
  • Accuracy (e.g. 50) - in meters.

Options (LocationOptions)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not
  • uint AccuracyInMeters - desired accuracy
  • PositionAccuracy Accuracy - Windows devices geolocation accuracy (low/high)
  • Double MovementThreshold - distance that must be moved, in meters, from last event before another event is raised
  • uint ReportInterval - time interval between reports

Required Device Capabilities

  • wifiControl - In order to check the network status availability.
  • location - In order to obtain the current location of the device.

Device information


Provides device characteristics information. This item is notified when the SDK is initialized and when it detects a change in the SD card slot of the device. For example, a new memory SD card is connected or removed.

Item identifier

  • ContextType.DEVICE_INFORMATION

State information

  • Device manufacturer.
  • Device model.
  • Product name.
  • Brand.
  • Phone number.
  • Total Storage size.
  • CPU model.
  • Total RAM size.
  • Hardware name.
  • Board model.
  • External memory presence.
  • OS type.
  • OS version.
  • Natural screen orientation.
  • Display height.
  • Display width.
  • Display density.
  • Display size.
  • Sensors supported.

Options (DeviceInformationOptions)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Environment light

Environment light sensor senses the lightning level of the environment and outputs a reading changes from 0 to over 30000 in lumen values. Distribution of the range is uneven as humans feel environments up to 200 lumens as dark, 1000 lumens as normal while output environments are normally over 10000 thousands in lumens. This distributions are enumerated as brightness. Some Environment Light Sensors also provide the ambient color temperature, reported as Correlated Color Temperature in Kelvin (Supported in Classic Only).

Item identifier

  • ContextType.ENVIRONMENT_LIGHT

State information

  • Illuminance (brightness of environment as a numerical illuminance metric in lumens)
  • Brightness (categorization of environment brightness, as a human readable interpretation of illuminance reading: DARK, DIM, NORMAL, INDOOR_BRIGHT, OUTDOOR_BRIGHT, SUNNY)
  • Ambient Color Temperature (warmth of the ambient light in the environment)

Sensing settings

  • SensingType: This setting is used to make a choice of activities to be reported. The sensing can be performed in an EVENT_BASED manner or a TIME_BASED manner.

Options (EnvironmentLightOptions)

  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not
  • uint ReportInterval - interval to report new data at
  • LUID - The serial number of the sensor can be passed using this option. If left null, will use any sensor of category Environment Light (Classic only)

Network


Provides information related to network connections. A new item is notified when a network event occurs (for example, the network access is disconnected or connected), and by default, every two hours, the state is refreshed with traffic and other network values that change.

Item identifier

  • ContextType.NETWORK

State information

  • IP address.
  • Phone type.
  • Cell location.
  • Link Speed.
  • Network type.
  • SSID.
  • Security type.
  • Signal strength.
  • Roaming active.
  • Online time.
  • Traffic received.
  • Traffic sent.
  • Near WiFi networks.

Options (NetworkOptions)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not
  • long MonitorInterval - how often a new state is notified every ms, independent of the changes in the network status. Default: 7200000 (2 hours)
  • long TimeWindowMs - minimum  time window required between states notification when the network status changes. Default: 120000 (2 minutes)

Required device capabilities

  • wifiControl - Required to access information about Wi-Fi networks.
  • location - Required to access precise location from location sources such as GPS, cell towers, and Wi-Fi.

Cloud services scopes

  • context:device:information - to read from cloud services.
  • context:post:device:information - to push to cloud services.

Proximity

Proximity senses if there is any object in close proximity to the device. It detects the distance between the device and the nearby object in millimeters.

Item identifier

  • ContextType.PROXIMITY

State information

  • IsDetected (whether or not there is any object in proximity sensor range)
  • DistanceInMillimeters (distance of the object in range to the device in millimeters)

Options (ProximityOptions)

  • SensingType: The sensing can be performed in an EVENT_BASED manner or a TIME_BASED manner. Report interval can be configured.
  • ReportInterval: For TIME_BASED sensing, the polling interval can be configured
  • LUID: The serial number of the sensor can be passed using this option. Use information from Device_Information provider to get the serial number of the sensor.
  • CategoryID: This represents the categoryID of the sensor. By default it is set to category all.
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage - boolean to save information in cloud or not

Terminal context


Provides a semantic description of the current device orientation, default device orientation, device rotation and face position. A new item is created each time the device detects a change in the orientation or screen position.

Item identifier

  • ContextType.TERMINAL_CONTEXT

State information

  • Device orientation: "LANDSCAPE_UP", "LANDSCAPE_DOWN", "PORTRAIT_UP", "PORTRAIT_DOWN", "ORIENTATION_UNKNOWN".
  • Default orientation: "LANDSCAPE_UP", "LANDSCAPE_DOWN", "PORTRAIT_UP", "PORTRAIT_DOWN", "ORIENTATION_UNKNOWN".
  • Rotation degrees: -1, 0, 90, 180, 270
  • Screen position: "FACE_DOWN", "FACE_UP", "FACE_UNKNOWN".

Sensing settings

  • SensingType: This setting is used to make a choice of activities to be reported. The sensing can be performed in an EVENT_BASED manner or a TIME_BASED manner.

Options (TerminalContextOptions)

  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Cloud services scopes

  • context:device:sensor - to read from cloud services.
  • context:post:device:sensor - to push to cloud services.

Audio classification  (UWP only)


Provides the percentage speech during the recorded interval from 0 to 100 percentage. The background class of the audio for the interval is also classified as Music, Mechanical, Motion, Crowd Chatter and Unknown class. (At the present moment, the background classification is not accurate)

Item identifier

  • ContextType.AUDIO

State information

  • Percentage speech in audio (0 to 100 percentage)
  • Audio background classification name: "MUSIC", "MECHANICAL", "MOTION", "CROWD_CHATTER"
  • The classification output is UNKNOWN if it not present in any of above classes

Options (AudioOptions)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required device capabilities

  • Microphone capability is required
  • Must be able to access the application data folder from C drive
  • Model files must be deployed to the AppData folder of the application

Lift and look event detection


Senses lifting of the device. It senses whether the device was lifted vertically or non-vertically. It also senses whether the user was looking at the device while lifting it.

  • Acceptable pitch range

Device should be kept stable in portrait or landscape mode, with a pre-defined acceptable pitch range, about 25 ~ 85 degrees, shown in the figure below.

Acceptable Pitch Range

  • Ambiguous pitch range

The ambiguous pitch range is 15 ~ 25 degree and 85 ~ 95 degree as shown in the figure below. In this range, it’s possible to detect or miss the lift & look event.

Ambiguous Pitch Range

To detect Lift, the Y axis or the X axis of the phone should face the sky. It need not be fully vertical, it can be -70 ~ 70 degree tilted to the ground.

Y Axis Face SkyX Axis Face Sky

Item identifier

  • ContextType.LIFT

State information

  • Device lift orientation:
    • VERTICAL
    • NON_VERTICAL
  • User looking mode:
    • LOOK
    • NONE

Options (CustomSensorWin7Options)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not
  • uint32 MinimumReportInterval

PanZoom gesture detection


Provides information related to motion control. It refers to the rotation of the device along its X and Y axes. This gesture can be used for the photo viewer feature.

PanZoomTilt Gesture Detection

Item identifier

  • ContextType.PANZOOM

State information

  • DeltaX: rotation along X axis of the device
  • DeltaY: rotation along Y axis of the device

Options (CustomSensorWin7Options)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not
  • uint32 MinimumReportInterval

Tapping event detection


Senses when the device screen is tapped once (single tap) or twice (double tap).

Item identifier

  • ContextType.TAPPING

State information

  • DOUBLE_TAP

Options (CustomSensorWin7Options)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not
  • uint32 MinimumReportInterval

Face recognition (Classic Only)

A face model is created from the images in each training folder. Up to 10 images can be saved per PersonID and up to 32 persons can be saved in the database. The camera capture is then processed and the faces in the frame are detected and processed. The face recognition information provided is shown in the State information below.

Item identifier

  • ContextType.FACE_RECOGNITION

State information

  • Frame Number
  • Number of faces detected
  • Number of persons recognized
  • PersonsRecognized: List of Person recognized in the frame
    • Each PersonRecognized with its ID, the confidence, the similarity
    • Confidence is the % confidence that a face was detected.
    • Similarity is the % similarity between the face and a model that was generated
  • Status - Enum (FACE_RECOGNIZED/FACE_NOT_RECOGNIZED) for a particular frame whether a face was recognized or not

Options (FaceRecognitionOptions)

  • Dictionary<int, string> TrainingFolders – a dictionary with key-PersonID and value the path of the folder containing the images to be used for the model (Required)
  • boolean Continuous – boolean to run the FR provider continuously (overwrites the FramesWanted property)
  • int FramesWanted - number of frames to process from the camera capture
  • int TimeBetweenFrames - time between each camera frame
  • SensingType - N/A
  • boolean StopWhenFaceRecognized – boolean to use to stop frame capture when a face is recognized
  • boolean ShowImage - whether to display the camera capture
  • int CameraIndex - which camera to use if there is more than one, otherwise the default is chosen
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required sample app capabilities

  • Application should be able to access the camera
  • pvl.dll(pvl64.dll) need to be added to the bin directory of the sample app
  • pvl-desktop-api.dll need to be added to the bin directory of the sample app
  • Training images needed to generate the model (up to 10 images per ID and up to 100 IDs) (folder location need to be accessible by the application)
  • OpenCV nuget package v3.1.0.20160622 installed on the app
  • Windows7.SensorAndLocation.dll
  • Newtonsoft.Json

Human Presence

Provides a binary value that indicates a human presence.

Item identifier

  • ContextType.HUMAN_PRESENCE

State information

  • IsHumanDetected

Options (HumanPresenceOptions)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required Device Capabilities

  • Firmware should have Intel’s custom Biometric sensor

Human Approach (Classic Only)

Provides a binary value which indicates that human is approaching the device. It will wake the device from modern standby when human approach is detected.

Item identifier

  • ContextType.HUMAN_APPROACH

State information

  • IsHumanDetected

Options (HumanApproachOptions)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required Device Capabilities

Intel Firmware with custom Human Approach sensor

Device Backlight (Classic only)

Provides the brightness level of the device. An event is generated anytimes the user changes/updates the brightness level.

Item identifier

  • ContextType. DEVICE_BACKLIGHT

State information

  • DeviceDisplayBrightness

Options (DeviceBacklightOptions)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required Device Capabilities

  • N/A

Device Activity (Classic only)

Provides information on whether the device keyboard or mouse are in use.

Item identifier

  • ContextType.DEVICE_ACTIVITY

State information

  • MouseActivity: Boolean indicating if the mouse is in use.
  • KeyboardActivity: Boolean indicating whether the keyboard is in use.

Options (DeviceActivityOptions)

  • SensingType: The sensing can be performed in an EVENT_BASED manner or a TIME_BASED manner. Report interval can be configured.
  • ReportInterval(ms): For TIME_BASED sensing, the polling interval can be configured
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required Device Capabilities

  • N/A

OnTable Detection

Provides information on whether the device is on table or not.

Item identifier

  • ContextType.ON_TABLE

State information

  • OnTable: Boolean indicating if the device is on table or not.

Options (CustomSensorWin7Options)

  • SensingType: The sensing can be performed in an EVENT_BASED manner or a TIME_BASED manner. Report interval can be configured.
  • ReportInterval: For TIME_BASED sensing, the polling interval can be configured
  • LUID: The serial number of the sensor should be passed using this option. Use information from Device_Information provider to get the serial number of the sensor.
  • CategoryID:  This represents the categoryID of the sensor. By default it is set to category all.
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required Device Capabilities

  • The device needs to have a firmware with OnTable sensor as a part of the BOM.

Hinge

Provides information the hinge angle, screen angle and keyboard angle of the device.

Item identifier

  • ContextType.HINGE

State information

  • HingeAngle: The angle between the screen and the keyboard
  • ScreenAngle: The angle of the screen, relative to the ground
  • KeyboardAngle: The angle of the base, relative to the ground
  • Enum HingeAccuracy: Accuracy of the angle.
    •         HINGE_ACCURACY_PERFECT: When GPIO notification is available
    •         HINGE_ACCURACY_HIGH : When the device is not moving
    •         HINGE_ACCURACY_MED : When the device is moving
    •         HINGE_ACCURACY_LOW : When the device is on book mode
    •         HINGE_ACCURACY_BAD : When some error occurs

Options (CustomSensorWin7Options)

  • SensingType: The sensing can be performed in an EVENT_BASED manner or a TIME_BASED manner. Report interval can be configured.
  • ReportInterval: For TIME_BASED sensing, the polling interval can be configured
  • LUID: The serial number of the sensor should be passed using this option. Use information from Device_Information provider to get the serial number of the sensor.
  • CategoryID:  This represents the categoryID of the sensor. By default it is set to category all.
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not

Required Device Capabilities

  • The device needs to have a firmware with Hinge sensor as a part of the BOM.

Accelerometer

Provides the x, y and z axis accelerometer sensor readings as well as the sensor model.

Item identifier

  • ContextType.ACCELEROMETER

State information

  • String SensorModel - the model of the sensor
  • String SensorManufacturer - the sensor manufacturer
  • AccelerometerValue - the X, Y and Z axis sensor data

Options (CustomSensorWin7Options)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not
  • LUID - the sensor identification number use to read data from the sensor

Required Device Capabilities

  • Requires system to have an accelerometer sensor as well as the sensor firmware available.

Gyrometer (Classic only)

Provides the x, y and z axes gyrometer sensor readings as well as the sensor model.

Item identifier

  • ContextType.GYROMETER

State information

  • String SensorModel - the model of the sensor
  • String SensorManufacturer - the sensor manufacturer
  • GyrometerValue - the X, Y and Z axis sensor data

Options (CustomSensorWin7Options)

  • SensingType - N/A
  • boolean LocalStorage - boolean to save information in SQL database or not
  • boolean CloudStorage  - boolean to save information in cloud or not
  • LUID - the sensor identification number use to read data from the sensor

Required Device Capabilities

  • Requires system to have a gyrometer sensor as well as the sensor firmware available.
For more complete information about compiler optimizations, see our Optimization Notice.