![\"iphone](\"https:\/\/mobiforge.com\/wp-content\/uploads\/2018\/07\/iphone-compass-300x223.jpg\")
<\/p>\n<\/p>\n
Today’s devices pack in a vast array of sensors that gather data about the device and the world around it. For web applications, access to these sensors has grown over time through the addition to the browser of various sensor APIs such as the Geolocation API, and the DeviceOrientation Events API.<\/p>\n
Such APIs have been instrumental in evolving the web platform to feature-parity with native apps, while at the same time still offering all the advantages the web has over native.<\/p>\n
In this article we take a look at a new API for device sensors: the Generic Sensor API.<\/p>\n
Since we already have APIs to access sensor data in the browser, you might be wondering why we need a new API. <\/p>\n
The existing sensor APIs have little in common, especially considering that, broadly, they offer similar types of functionality: reading sensor data, and doing something with that data.<\/p>\n
The Generic Sensor API aims to address this by providing a set of consistent APIs to access sensors. The goals of the API are outlined in its spec (recommendation status)<\/a>:<\/p>\n The goal of the Generic Sensor API is to promote consistency across sensor APIs, enable advanced use cases thanks to performant low-level APIs, and increase the pace at which new sensors can be exposed to the Web by simplifying the specification and implementation processes.<\/p>\n<\/blockquote>\n The Generic Sensor API achieves this by defining a set of interfaces that expose sensors, consisting of the base An interesting aspect of the API is Fusion sensors<\/em>. You can think of these as virtual sensors that combine or fuse the data of multiple real<\/em> sensors into a new sensor that is reliable and robust, or that has filtered and combined the data in such as way that is appropriate for a certain goal.<\/p>\n We’ll see the benefit of this later when we first build a simple compass app using the The API has specifications for a number of sensors, such as Accelerometer<\/a>, Ambient Light Sensor<\/a>, Magnetometer<\/a>, Gyroscope<\/a>, OrientationSensor<\/a> as well as drafts for future sensors, such as Geolocation Sensor<\/a> and Proximity Sensor<\/a>.<\/p>\n Chrome is leading the way with respect to implementation. The following motion sensors<\/em> are enabled by default since Chrome 67:<\/p>\n And the following environmental sensors<\/em> are not enabled by default, but can be enabled in Chrome flag settings (visit Edge and Firefox have partial implementations of the Support for individual sensor implementations are listed separately on caniuse.com<\/a>.<\/p>\n W3C invites implementations of the Sensor APIs here<\/a>.<\/p>\n Let’s run through a couple of examples. Before we begin, note that this API can only be used on secure (HTTPS) contexts<\/em>. <\/p>\n The general pattern of use is:<\/p>\n We create a sensor like this: <\/p>\n replacing or<\/p>\n You get the idea. We could do the same for any of the sensors listed earlier.<\/p>\n Don’t forget to check for sensor support. There are a couple of ways to check for support for a sensor. First, you can check for support with something like this:<\/p>\n Alternatively, you can wrap your code within a try-catch block:<\/p>\n We can also set the data sampling frequency, in Hz:<\/p>\n Note that, for security reasons, the browser implementation of any particular sensor may impose limits on various sensor properties. For example, if you try to set the frequency of the What kind of security concerns might there be around the ambient light sensor? Reflected ambient light levels from a device’s screen can be exploited to determine pixel values of the screen. Limiting the sampling frequency can mitigate threats like this.<\/p>\n Defining a sensor callback is straightforward:<\/p>\n This needs no explanation:<\/p>\n When you’re done with the sensor, you can stop using it with:<\/p>\n This pattern will be repeated for all the sensors we use in the following sections.<\/p>\n The Gyroscope sensor measures angular velocity around device’s local X, Y, Z axes, in radians per second. The sensor’s readings are stored in the View example<\/a>.<\/p>\n There are actually three sensors defined in the Accelerometer spec<\/a>: The accelerometer provides acceleration information on the device’s X, Y, Z axes. Similar to the Gyroscope, we can output this data to the browser with:<\/p>\n View example<\/a>.<\/p>\n This is a subclass of Another subclass of Next, let’s look at the Ambient Light Sensor. This sensor reports the environmental light level as detected by the device’s light sensor. Use cases could include accessibility, smart lighting, and camera settings based on ambient light.<\/p>\n Note that at the time of writing, environmental sensors (the Ambient Light Sensor, and Magnetometer) must be manually enabled in Chrome browser by visiting The Ambient light sensor reports the detected light level in lux units, between 0 and around 30000 (the upper limit appears to be device-dependent: some devices tested maxed out at 32768, while others at 30000).<\/p>\n First we create the sensor:<\/p>\n Next let’s consider the callback function. To read the value from this sensor, we check the Now let’s do something else with the data, apart from just outputting the raw values to the browser.<\/p>\n A use-case for the ambient light sensor could be to automatically adjust screen brightness based on the ambient light. When the environment is bright, we crank up the screen brightness; when it’s dark, then we crank it down. However, the web browser can’t control the actual raw screen levels. One thing we can do however is adjust the colours on the page to show darker or lighter colours based on the ambient light readings, so we could have a dark theme and a light theme.<\/p>\n The example below shows how to set the background colour of the page based on the ambient light level. We just map the lux value to a value in range 0 to 255, and then set the background colour of the page body to the corresponding grey level:<\/p>\n View example<\/a>.<\/p>\n An alternative example, and perhaps more useful, could be to toggle a CSS class, On the Intel github pages there is a pretty nice map demonstration that takes this idea a bit further: when the ambient light level drops below a threshold a Google Map is switched to a dark theme. https:\/\/intel.github.io\/generic-sensor-demos\/ambient-map\/build\/bundled\/<\/a><\/p>\n Next let’s take a look at the Magnetometer sensor<\/a>. As it’s name suggests, it measures magnetic fields, in three axes ( With a little bit of trigonometry on the (Multiplying by View example<\/a>.<\/p>\n Based on the heading, a simple compass image or a map could be rotated to that heading (we did something similar to this using the DeviceOrientation Events API<\/a> previously):<\/p>\n View example<\/a>.<\/p>\n There are limitations to this approach though, as outlined in the Magnetometer interface description<\/a>. The main problem is that the device needs to be level with the Earth’s surface, or else tilt compensation should be applied. We can improve on this using the Orientation sensor, which is a fusion sensor combining accelerometer, magnetometer, and gyroscope data.<\/p>\n We briefly mentioned fusion sensors<\/em> earlier, and how they are a benefit of the Generic Sensor API. By combining data from multiple real sensors, new virtual<\/em> sensors can be implemented that combine and filter the data so that it’s easier to use, or so that it can be more useful in a particular problem domain.<\/p>\n We can see this by improving on our initial The A nice feature of the The Using the these sensors follows the same Generic Sensor API pattern as before:<\/p>\n We can get the quaternion representing the device motion by reading the Each rotation data event from these sensors is returned as a quaternion A real benefit of using quaternion data can be seen through 3D examples with WebGL, or third party 3D libraries such as Three.js. We won’t go into these here, but there are several excellent examples on Intel’s Generic Sensor API Demos github project<\/a> that demonstrate some of the possibilities, including 360 degree panorama and VR demos. I recommend checking these out.<\/p>\n We’ll update our previous compass example to make use of the We can start by modifying our previous This time to compute the heading we need to calculate the Euler angle<\/em> for the x<\/em> axis. After a quick quaternion-to-Euler-angles crash course on Wikipedia<\/a>, and a bit of experimentation to figure out which sensor properties represented the real world axes we are interested in, we can separate out the compass rotation from the rotations represented in the quaternion with the following:<\/p>\n As before, we’ll multiply by The rest of the example code is the same as before.<\/p>\n View example<\/a>.<\/p>\n The advantage of the fusion sensor can be seen in this example: the compass is more stable, and not affected by tilting.<\/p>\n (Note, this has only been tested on a couple of Android devices, so your mileage may vary)<\/p>\n There is a request for implementation of a Geolocation Sensor<\/a> for the Generic Sensor API, but at time of writing no such sensor has been implemented in any of the main browsers. Notably, there has been a discussion on the merits of high-level vs low-level access to underlying sensors<\/a>.<\/p>\n Geolocation Sensor Issues tracker: https:\/\/github.com\/wicg\/geolocation-sensor\/issues<\/a><\/p>\n The Generic Sensor API is integrated with the Permissions API<\/a>. However, the spec states<\/a> that access can be granted without prompting the user<\/em>, and it depends on the browser and the sensor in question.<\/p>\n While access to accelerometer and gyro sensors might not seem as important to require permission for, as, say a Geolocation sensor, there can be unforeseen and undesirable uses of seemingly innocuous sensors. Felix Krause<\/a>, a developer at Google, demonstrated a proof of concept of how a user’s activity can be determined<\/a> based on the data coming from acceleration and gyro sensors, using the older APIs.<\/p>\n Some of the activities that can be determined are:<\/p>\n \nAccording to Felix, it would likely be possible to determine if a user was impaired due to alcohol too!\n<\/p>\n<\/p>\n The Generic Sensor API team were quick to point out that security and privacy were central considerations in the API, intimating that this should<\/em> not be possible with the Generic Sensor API. <\/p>\n Within 2 hours @kennethrohde<\/a> and @darktears<\/a>, who both work on Chromium & W3C specs, send me links to where this is being discussed \u2764\ufe0f pic.twitter.com\/cWfuvZeyTy<\/a><\/p>\n — Felix Krause (@KrauseFx) September 7, 2017<\/a><\/p><\/blockquote>\n\n
Sensor<\/code> interface, and concrete sensor classes that extend this, making it easy to add new sensors, and providing a consistent way to use them.<\/p>\nFusion sensors<\/h3>\n
Magnetometer<\/code> sensor directly, and then see how we can improve this based on the AbsoluteOrientationSensor<\/code>, a fusion sensor which combines data from real magnetometer, accelerometer, and gyroscope sensors.<\/p>\nSensors supported by the Generic Sensor API<\/h2>\n
\n
Accelerometer<\/code><\/li>\nGyroscope<\/code><\/li>\nLinearAccelerationSensor<\/code><\/li>\nAbsoluteOrientationSensor<\/code><\/li>\nRelativeOrientationSensor<\/code><\/li>\n<\/ul>\nchrome:\/\/flags<\/code> and enable Generic Sensor Extra Classes<\/em>)<\/p>\n\n
AmbientLightSensor<\/code><\/li>\nMagnetometer<\/code><\/li>\n<\/ul>\nAmbientLightSensor<\/code>, and Firefox has an open issue<\/a> to implement the Generic Sensor API, but there is no ETA on this yet. <\/p>\nHow to use the Generic Sensor API<\/h2>\n
\n
1. Create sensor<\/h3>\n
\r\n sensor = new <SensorName>();\r\n<\/pre>\n
\r\n sensor = new Accelerometer();\r\n<\/pre>\n
\r\n sensor = new AbsoluteOrientationSensor();\r\n<\/pre>\n<\/p>\n
Checking for sensor support<\/h4>\n
\r\n if(AmbientLightSensor in window) {\r\n \/\/ Create Sensor\r\n }\r\n<\/pre>\n\r\n try {\r\n \/\/ Create Sensor\r\n } catch(error) {\r\n console.log('Error creating sensor')\r\n \/\/Fallback, do something else etc.\r\n }\r\n<\/pre>\nSetting sampling frequency<\/h4>\n
\r\n \/\/Read once per second\r\n sensor = new AmbientLightSensor({frequency: 1});\r\n<\/pre>\nAmbientLightSensor<\/code> in Chrome to a value greater than 10, you will see a console message:<\/p>\nMaximum allowed frequency value for this sensor type is 10 Hz.
\n<\/code><\/p>\n2. Define callback function<\/h3>\n
\r\n sensor.addEventListener('reading', listener);\r\n\r\n function listener() {\r\n \/\/ Do something with the sensor data\r\n }\r\n<\/pre>\n3. Start the sensor<\/h3>\n
\r\n \/\/Start the sensor\r\n sensor.start()\r\n<\/pre>\n
4. Stop the sensor<\/h3>\n
\r\n \/\/Stop the sensor\r\n sensor.stop()\r\n<\/pre>\n<\/p>\n
Gyroscope<\/h2>\n
x<\/code>, y<\/code>, z<\/code> properties, so we can output the data to the browser with the following code:<\/p>\n\r\n <div id='status'><\/div>\r\n <script>\r\n if ( 'Gyroscope' in window ) {\r\n let sensor = new Gyroscope();\r\n sensor.addEventListener('reading', function(e) {\r\n document.getElementById('status').innerHTML = 'x: ' + e.target.x + ' y: ' + e.target.y + ' z: ' + e.target.z;\r\n });\r\n sensor.start();\r\n }\r\n <\/script>\r\n<\/pre>\nAccelerometer<\/h2>\n
Accelerometer<\/code>, LinearAccelerationSensor<\/code>, and GravitySensor<\/code>. Each of them provides some information about the accelerations applied to the device’s X, Y, and Z axes. <\/p>\nAccelerometer Sensor<\/h3>\n
\r\n let sensor = new Accelerometer();\r\n sensor.addEventListener('reading', function(e) {\r\n document.getElementById('status').innerHTML = 'x: ' + e.target.x + ' y: ' + e.target.y + ' z: ' + e.target.z;\r\n console.log(e.target);\r\n });\r\n sensor.start();\r\n<\/pre>\nLinearAcceleration Sensor<\/h3>\n
Accelerometer<\/code>, and measures acceleration applied to the device excluding<\/em> the acceleration contributed by gravity. It uses x<\/code>, y<\/code>, and z<\/code> properties as above.<\/p>\nGravity Sensor<\/h3>\n
Accelerometer<\/code>. This time the data represents acceleration due to the effect of gravity on each of the devices axes. (Note that this sensor is not currently available in Chrome).<\/p>\nAmbient Light Sensor<\/h2>\n
chrome:\/\/flags<\/code> and enabling the Generic Sensor Extra Classes<\/em> option, so do this first before trying to run any demo code.<\/p>\n\r\n sensor = new AmbientLightSensor();\r\n<\/pre>\n
illuminance<\/code> property. So we could output the raw data to the browser with:<\/p>\n\r\n <div id='status'><\/div>\r\n\r\n <script>\r\n sensor.addEventListener('reading', function(e) {\r\n document.getElementById('status').innerHTML = e.target.illuminance;\r\n }\r\n <\/script>\r\n<\/pre>\n\r\n sensor.addEventListener('reading', function(e) {\r\n document.getElementById('status').innerHTML = e.target.illuminance;\r\n console.log(e.target.illuminance);\r\n\r\n var lux = e.target.illuminance;\r\n console.log('L:', lux.map(0,500,0,255));\r\n var val = lux.map(0,500,0,255);\r\n document.body.style.backgroundColor = 'rgb('+val+','+val+','+val+')';\r\n\r\n });\r\n<\/pre>\nlight<\/code>, or dark<\/code> whenever the light level crosses some threshold.<\/p>\nMagnetometer<\/h2>\n
x, y, z<\/code>) around the device. We can get the raw data by querying the x<\/code>, y<\/code>, and z<\/code> properties like this:<\/p>\n\r\n var sensor = new Magnetometer();\r\n sensor.addEventListener('reading', function(e) {\r\n document.getElementById('status').innerHTML = 'x: ' + e.target.x + ' y: ' + e.target.y + ' z: ' + e.target.z;\r\n });\r\n sensor.start();\r\n<\/pre>\nx<\/code> and y<\/code> axes (courtesy of the MagnetomerSensor spec<\/a>), we can compute a compass heading, and display that instead:<\/p>\n\r\n var sensor = new Magnetometer();\r\n sensor.addEventListener('reading', function(e) {\r\n let heading = Math.atan2(e.target.y, e.target.x) * (180 \/ Math.PI);\r\n document.getElementById('status').innerHTML = 'Heading in degrees: ' + heading;\r\n });\r\n sensor.start();\r\n<\/pre>\n180\/Math.PI<\/code> converts from radians to degrees)<\/p>\n\r\n sensor.addEventListener('reading', function(e) {\r\n let heading = Math.atan2(e.target.y, e.target.x) * (180 \/ Math.PI);\r\n \/\/Adjust heading\r\n heading = heading-180;\r\n if(heading < 0) heading = 360 + heading;\r\n document.getElementById('status').innerHTML = 'Heading in degrees: ' + heading;\r\n compass.style.Transform = 'rotate(-' + heading + 'deg)';\r\n });\r\n sensor.start();\r\n<\/pre>\nFusion sensors: combining real sensors<\/h2>\n
Magnetometer<\/code> compass example with the OrientationSensor<\/code>.<\/p>\nThe OrientationSensor<\/h2>\n
OrientationSensor<\/code> has two subclasses:<\/p>\n\n
AbsoluteOrientationSensor<\/code>: reports rotation of device in world coordinates<\/em>, based on real accelerometer, gyroscope, and magnetometer sensors<\/li>\nRelativeOrientationSensor<\/code>: reports rotation of device relative to a stationary coordinate system, based on real accelerometer and gyroscope sensors<\/li>\n<\/ol>\nScreen coordinates syncing<\/h3>\n
OrientationSensor<\/code> is the automatic mapping of sensor readings to screen coordinates, taking screen orientation into account. Previously this mapping would have to be implemented in the application logic, requiring the developer to write JavaScript code to watch out for orientation change events.<\/p>\nreferenceFrame<\/code> parameter is used to specify whether readings should be relative to the device or the screen orientation:<\/p>\n\r\n \/\/ This is the default (i.e. referenceFrame could be omitted here)\r\n let sensor = new RelativeOrientationSensor({referenceFrame: \"device\"});\r\n\r\n \/\/ Use screen coordinate system\r\n let sensor = new RelativeOrientationSensor({referenceFrame: \"screen\"});\r\n<\/pre>\nUsing the OrientationSensor<\/h2>\n
\r\n let sensor = new AbsoluteOrientationSensor({frequency: 60});\r\n ...\r\n sensor.start();\r\n<\/pre>\n\r\n let sensor = new RelativeOrientationSensor({frequency: 60});\r\n ...\r\n sensor.start();\r\n<\/pre>\nquaternion<\/code> property of the sensor event:<\/p>\n\r\n e.target.quaternion\r\n<\/pre>\n
Quaternion sensor data<\/h2>\n
[x,y,z,w]<\/code> that represents a rotation in 3D space relative to the coordinate system. The components representing the vector part of the quaternion go first, and the scalar component comes after. Returning data in this format makes more compatible with graphics environments such as WebGL.<\/p>\nOrientationSensor<\/code>. Since we’re concerned with the orientation of the device with respect to the real world<\/em>, this sounds like a job for AbsoluteOrientationSensor<\/code>.<\/p>\nA compass with AbsoluteOrientationSensor<\/h2>\n
MagnetometerSensor<\/code> compass example to retrieve the quaternion<\/code> property, instead of the magnetometer axial rotation values:<\/p>\n\r\n let compass = document.getElementById('compass');\r\n let sensor = new AbsoluteOrientationSensor();\r\n sensor.addEventListener('reading', function(e) {\r\n var q = e.target.quaternion;\r\n ...\r\n }\r\n<\/pre>\n\r\n Math.atan2(2*q[0]*q[1] + 2*q[2]*q[3], 1 - 2*q[1]*q[1] - 2*q[2]*q[2])\r\n<\/pre>\n
180\/Math.PI<\/code> to convert from radians to degrees, and now we have a heading.<\/p>\n\r\n let compass = document.getElementById('compass');\r\n let sensor = new AbsoluteOrientationSensor();\r\n sensor.addEventListener('reading', function(e) {\r\n var q = e.target.quaternion;\r\n heading = Math.atan2(2*q[0]*q[1] + 2*q[2]*q[3], 1 - 2*q[1]*q[1] - 2*q[2]*q[2])*(180\/Math.PI);\r\n if(heading < 0) heading = 360+heading;\r\n compass.style.Transform = 'rotate(' + heading + 'deg)';\r\n }\r\n sensor.start();\r\n<\/pre>\n![\"\"](\"https:\/\/mobiforge.com\/wp-content\/uploads\/2018\/07\/fusion-compass.jpg\")
<\/a><\/p>\nGeolocation Sensor<\/h3>\n
Privacy and permissions<\/h2>\n
\n
\n