We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Device Sensors API Specification (PRELIMINARY) - FIWARE Forge Wiki

Device Sensors API Specification (PRELIMINARY)

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Device Sensors API Introduction

This section covers all the APIs related to Device Sensors. This includes the following functional blocks:

  • Geo-Location
  • Device Orientation & Accelerometer
  • Sensor Discovery

Connected Devices often offer additional hardware or sensors which can offer a range of additional data and functionality to application developers. The Device Sensors API makes this additional hardware available to an application developer.

Please check the following Legal Notice (essential patents license) to understand the rights to use these specifications.

How to Read This Document

Each of the functional blocks covered above are described in WebIDL. Where a Functional Block's API is simply a realisation of an existing standards based specification, this document will link directly to the relevent standards bodies WebIDL specification document. This is a prudent step as FI-WARE is an integration project, and will by necessity combine already existing API specifications.

Non RESTfull API

This specification outlines an API which is JavaScript based. This is because the API is intended to be used by applications running on a device. In this situation we are invoking local services and a RESTful interface would add a layer of complicity which is overly complicated and ultimately unnecessary.

API Change History

Version Date Author Comment
1.0 8th November 2012 Brian Egan (Intel) Initial API Version
1.1 21st May 2013 Chris Woods (Intel) Content update, and formatting changes. API remains the same

Intended Audience

This specification is intended for software developers who will use the API, and for those who will implement the specification. It is assumed that the reader is familiar with WebIDL.

Introduction to Geo-Location

The Geolocation API provides a method to locate and watch the user’s position. This is useful in a number of ways from providing a user with location information to providing navigation.

Developer Usage

The API provides two methods

  • getCurrentPosition - get current position
  • watchPosition - notify of any changes to the position


Not all devices support geoLocation, so it is wise to check whether the device supports it before using any of the methods:


if ($cdi.sensors.availability.geolocation==true)
{
    //deviceOrientation supported
}
else
{
    //not supported – handle this
}

Now that we know the device supports geolocation we can request our current location

if ($cdi.sensors.availability.geolocation==true)
{
    //deviceOrientation supported
    var cdiGeolocation= $cdi.sensors.geolocation;
 
    function successsCallback(position)
    {
        var longitude = position.coords.longitude;
        var latitude = position.coords.latitude;
 
        //do something with the co-ordinates!
 
     }
 
    function errorCallback(error)
    {
      Alert("Error");
    }
 
    cdiGeolocation.getCurrentPosition(successsCallback,errorCallback);
}
else
{
    //not supported – handle this
}

In the case where our requirements call for us to be notified every time our position gets updated (a navigation app for example) we will need to register for notification:

var watcherID;
if ($cdi.sensors.availability.geolocation==true)
{
    //deviceOrientation supported
    var cdiGeolocation= $cdi.sensors.geolocation;
 
    function successsCallback(position)
    {
        var longitude = position.coords.longitude;
        var latitude = position.coords.latitude;
 
        //position has changed - do something with the co-ordinates!
 
     }
 
    function errorCallback(error)
    {
      Alert("Error");
    }
 
    watcherID=cdiGeolocation.watchPosition(successsCallback,errorCallback, { enableHighAccuracy: true, timeout: timeoutVal, maximumAge: 0 });
}
else
{
    //not supported – handle this
}

watchPosition returns an ID which is used to identify the watcher. This ID can be used later when we wish to cancel the watcher.

$cdi.Geolocation.clearWatch(watcherID);

Both getCurrentPosition and watchPosition return immediately and asynchronously return the current location. Both take the same argument list two of which are optional:

  • successCallback - called if the method returns successfully
  • errorCallback – called if the method returns with an error
  • options – a number of options are available:
  • enableHighAccuracy – This Boolean Indicates that the caller would like the most accurate result possible. This may cause a slower response time and in the case of a mobile device, greater power consumption. Defaults to false.
  • timeout – the maximum length of time to wait for a response. Time is supplied in milliseconds.
  • maximumAge – the maximum age of a cached position that the application is willing to accept. Measured in milliseconds. Defaults to 0 which indicates that a new position must be obtained.


A call to watchPosition will callback immediately with the current position and every time after that the position changes.

When the position is successfully returned the position object contains a range of useful information:

  • coords.latitude - degrees of latitude
  • coords.longitude - degress of longitude
  • coords.altitude - Height in metres of the position above the reference ellipsoid
  • coords.accuracy - accuracy in metres of the returned result
  • coords.altitudeAccuracy - accuracy in metres of the returned altitude
  • coords.heading - Direction of travel of the device clockwise from true north
  • coords.speed - current ground speed of the hosting device in metres per second
  • timestamp - Timestamp of when the position was acquired

Authentication

This API should only be available to applications (web applications / webapps) which have been installed on the device. The installation procedure should verify an applications request to access the CDI geolocation API and obtain user consent before installing the application. Following this, at runtime it can be assumed that the user has granted access for this application to access the geolocation API.


Geo-Location API

The Geolocation API implementation is directly modelled on the W3C Geolocation API Specification.


Design Goals

The design goals we to create an API which aligns with the W3C Geolocation API Specification.

  • On platforms which support this API directly it should work out of the box
  • On platforms where it is not supported directly the API structure will allow for an implementation that will allow this platform to support the W3C version.


Modification to W3C geoLocation API

The single modification that has been made to the geoLocation API has been the addition of the CDI Namespace. This involves replacing the call to navigator with the name-space cdi.sensors before calling any geoLocation APIs

Example

With W3C API you would call

navigator.geolocation.getCurrentPosition(....

With CDI API you call

$cdi.sensors.geolocation.getCurrentPosition(....

Introduction to Device Orientation & Accelerometer

The Device Orientation And Accelerometer API is used to determine the orientation of the device as well as gather information about its movement.

Developer Usage

The CDI deviceOrientation class provides information on:

  1. DeviceOrientation – the positioning of the device around its own axis
  2. DeviceMotion – the motion or acceleration of the device in a particular direction.

The Device Orientation is provided using a standard XYZ co-ordinate system.

Rotating the Device

Device Orientation defines three types of rotation:

  • Alpha: The amount of rotation around the Z axis is known as alpha. The device rotates along the Z-axis by 'alpha' degrees per microsecond. The range is from 0 to 360 degrees.
  • Beta: The amount of rotation around the X-axis is known as beta.. The device is turning along the X-axis. The range is from -180 to 180 degrees.
  • Gamma: The amount of rotation around the Y-Axis is known as gamma. The range is from -90 to 90 degrees.

DeviceOrientationEvent
Device Orientation specifies an event called the DeviceOrientationEvent. This will inform the developer of the devices alpha, beta and gamma. Not all devices support DeviceOrientation, so it is wise to check whether the device supports it:

var CDIDeviceOrientation= $cdi.sensors.deviceOrientation;
if ($cdi.sensors.availability.deviceOrientation.DeviceOrientationEvent==true)
{
    //deviceOrientation supported – register a listener
    CDIDeviceOrientation.addEventListener('deviceorientation', updateorientation, true);
}
else
{
    //not supported – handle this
}

We can now add an event listener, so that every time the device is rotated, it fires the event and we can process it using a function: In the above example once we established that the DeviceOrientationEvent was supported we then added a listener:

CDIDeviceOrientation.addEventListener('deviceorientation', updateorientation, true);

Inside the updateorientation function, we can now process the rotation of the device:

function updateorientation (event)
{
 var alpha = event.alpha;
 var beta = event.beta;
 var gamma = event.gamma;
}

DeviceMotionEvent
The DeviceMotionEvent tells us how fast the device is accelerating along its X, Y and Z axis. Not all devices support DeviceMotion so it is wise to check whether the device supports it:

var CDIDeviceOrientation= $cdi.sensors.deviceOrientation;
if ($cdi.sensors.availability.deviceOrientation.DeviceMotionEvent==true)
{
    //deviceMotion supported – register a listener
    CDIDeviceOrientation.addEventListener('devicemotion', updatemotion, true);
}
else
{
    //not supported – handle this
}

We can now add an event listener, so that every time the device is moved, it fires the event and we can process it using a function: In the above example once we established that the MotionEvent was supported we then added a listener:

CDIDeviceOrientation.addEventListener('devicemotion', updatemotion, true);

Inside the updatemotion function, we can now process the motion of the device:

function updatemotion(event)
{
    var accelerationX=event.acceleration.x;
    var accelerationY=event.acceleration.y;
    var accelerationZ=event.acceleration.Z;
};

The measurements are in meters per second squared (ms2) .


Authentication

This API should only be available to applications (web applications / webapps) which have been installed on the device. The installation procedure should verify an applications request to access the Device Orientation and Accelerometer APIs and obtain user consent before installing the application. Following this, at runtime it can be assumed that the user has granted access for this application to access the API.


Device Orientation & Accelerometer API

The Device Orientation & Accelerometer APIs implementations are directly modeled on the W3C's Device Orientation Event Specification.

Design Goals

The design goals we to create an API which aligns with the W3C's Device Orientation Event Specification.

  • On platforms which support this API directly it should work out of the box
  • On platforms where it is not supported directly the API structure will allow for an implementation that will allow this platform to support the W3C version.


Modification to W3C Device Orientation & Accelerometer API

The single modification that has been made to the devie orientation API has been the addition of the CDI Namespace. This involves pre-pending the name-space cdi.sensors.deviceOrientation before calling any device orientation APIs

Example

With W3C API you would call

window.addEventListener(....

With CDI API you call

$cdi.sensors.deviceOrientation.addEventListener(....
Personal tools
Create a book