├── .gitignore ├── images ├── device_coordinate_system.png ├── screen_coordinate_system.png ├── accelerometer_coordinate_system.png ├── accelerometer_coordinate_system.svg ├── screen_coordinate_system.svg └── device_coordinate_system.svg ├── .pr-preview.json ├── releases ├── accelerometer_coordinate_system.png ├── accelerometer_coordinate_system.svg └── WD-accelerometer-20160913.html ├── LICENSE.md ├── w3c.json ├── CODE_OF_CONDUCT.md ├── README.md ├── .github └── workflows │ └── auto-publish.yml ├── CONTRIBUTING.md ├── security-questionnaire.md └── index.bs /.gitignore: -------------------------------------------------------------------------------- 1 | deploy_key 2 | -------------------------------------------------------------------------------- /images/device_coordinate_system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/accelerometer/main/images/device_coordinate_system.png -------------------------------------------------------------------------------- /images/screen_coordinate_system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/accelerometer/main/images/screen_coordinate_system.png -------------------------------------------------------------------------------- /images/accelerometer_coordinate_system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/accelerometer/main/images/accelerometer_coordinate_system.png -------------------------------------------------------------------------------- /.pr-preview.json: -------------------------------------------------------------------------------- 1 | { 2 | "src_file": "index.bs", 3 | "type": "bikeshed", 4 | "params": { 5 | "force": 1 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /releases/accelerometer_coordinate_system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/w3c/accelerometer/main/releases/accelerometer_coordinate_system.png -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | All documents in this Repository are licensed by contributors 2 | under the 3 | [W3C Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software). 4 | 5 | -------------------------------------------------------------------------------- /w3c.json: -------------------------------------------------------------------------------- 1 | { 2 | "group": 43696, 3 | "contacts": [ 4 | "himorin" 5 | ], 6 | "shortName": "accelerometer", 7 | "repo-type": "rec-track", 8 | "policy": "open" 9 | } 10 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/). 4 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Accelerometer 2 | 3 | This repository contains the 4 | [Accelerometer](https://w3c.github.io/accelerometer/) 5 | specification that is being worked on in the 6 | [W3C Device and Sensors Working Group](http://www.w3.org/2009/dap/). 7 | -------------------------------------------------------------------------------- /.github/workflows/auto-publish.yml: -------------------------------------------------------------------------------- 1 | # Workflow based on the w3c/spec-prod action example to deploy to W3C using Echidna: 2 | # https://github.com/w3c/spec-prod/blob/main/docs/examples.md#deploy-to-w3c-using-echidna 3 | 4 | name: CI 5 | 6 | on: 7 | pull_request: {} 8 | push: 9 | branches: [main] 10 | 11 | jobs: 12 | main: 13 | name: Build, Validate and Deploy 14 | runs-on: ubuntu-latest 15 | steps: 16 | - uses: actions/checkout@v2 17 | - uses: w3c/spec-prod@v2 18 | with: 19 | GH_PAGES_BRANCH: gh-pages 20 | W3C_ECHIDNA_TOKEN: ${{ secrets.ECHIDNA_TOKEN }} 21 | # Replace following with appropriate value. See options.md for details. 22 | W3C_WG_DECISION_URL: https://lists.w3.org/Archives/Public/public-device-apis/2021May/0008.html 23 | W3C_BUILD_OVERRIDE: | 24 | status: CRD 25 | shortname: accelerometer 26 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Contributions to this repository are intended to become part of Recommendation-track documents governed by the 2 | [W3C Patent Policy](https://www.w3.org/Consortium/Patent-Policy/) and 3 | [Software and Document License](https://www.w3.org/Consortium/Legal/copyright- 4 | software). To make substantive contributions to specifications, you must either participate 5 | in the relevant W3C Working Group or make a non-member patent licensing commitment. 6 | 7 | If you are not the sole contributor to a contribution (pull request), please identify all 8 | contributors in the pull request comment. 9 | 10 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows: 11 | 12 | ``` 13 | +@github_username 14 | ``` 15 | 16 | If you added a contributor by mistake, you can remove them in a comment with: 17 | 18 | ``` 19 | -@github_username 20 | ``` 21 | 22 | If you are making a pull request on behalf of someone else but you had no part in designing the 23 | feature, you can remove yourself with the above syntax. 24 | 25 | # Tests 26 | 27 | For normative changes, a corresponding 28 | [web-platform-tests](https://github.com/web-platform-tests/wpt) PR is highly appreciated. Typically, 29 | both PRs will be merged at the same time. Note that a test change that contradicts the spec should 30 | not be merged before the corresponding spec change. If testing is not practical, please explain why 31 | and if appropriate [file a web-platform-tests issue](https://github.com/web-platform-tests/wpt/issues/new) 32 | to follow up later. Add the `type:untestable` or `type:missing-coverage` label as appropriate. 33 | -------------------------------------------------------------------------------- /images/accelerometer_coordinate_system.svg: -------------------------------------------------------------------------------- 1 | accelerometer_coordinate_systemZ-ZY-YX-X -------------------------------------------------------------------------------- /security-questionnaire.md: -------------------------------------------------------------------------------- 1 | # [Security and Privacy Self-Review Questionnaire] for [Accelerometer] 2 | 3 | Answers to the [questionnaire][Security and Privacy Self-Review Questionnaire] for 4 | [Generic Sensor API] can be found [here](https://github.com/w3c/sensors/blob/main/security-questionnaire.md). 5 | 6 | ## [3.1 Does this specification deal with personally-identifiable information?] 7 | 8 | Yes, but not directly. [Accelerometer] specification requires user [permission] and implementation 9 | of applicable [mitigation strategies] to address [potential risks][user-identification]. 10 | For more information, please see: [Security and Privacy section][security-and-privacy]. 11 | 12 | ## [3.2 Does this specification deal with high-value data?] 13 | 14 | Yes, but not directly. 15 | 16 | >Sensor readings are explicitly flagged by the Secure Contexts specification 17 | [[POWERFUL-FEATURES]] as a high-value target for network attackers. Thus all interfaces defined by 18 | this specification or extension specifications are only available within a secure context. 19 | 20 | Indirectly, accelerometer sensor readings can be used to [infer user input]. 21 | 22 | ## [3.3 Does this specification introduce new state for an origin that persists across browsing sessions?] 23 | 24 | No. 25 | 26 | ## [3.4 Does this specification expose persistent, cross-origin state to the web?] 27 | 28 | No. 29 | 30 | ## [3.5 Does this specification expose any other data to an origin that it doesn’t currently have access to?] 31 | 32 | No. 33 | 34 | ## [3.6 Does this specification enable new script execution/loading mechanisms?] 35 | 36 | No. 37 | 38 | ## [3.7 Does this specification allow an origin access to a user’s location?] 39 | 40 | Not directly; However, accelerometer data can be used in combination with other sensors to 41 | calculate, things like speed, how many steps were taken, etc., therefore, infer new position 42 | of the end user. [Accelerometer] requires [user permission][permission] 43 | and implementation of applicable [mitigation strategies] to avoid [potential risks][location-tracking]. 44 | 45 | ## [3.8 Does this specification allow an origin access to sensors on a user’s device?] 46 | 47 | Yes. 48 | 49 | ## [3.9 Does this specification allow an origin access to aspects of a user’s local computing environment?] 50 | 51 | Yes. If user agent has [permission] to access accelerometer, the API provides means to check if sensor is available within user’s local computing environment. 52 | 53 | ## [3.10 Does this specification allow an origin access to other devices?] 54 | 55 | No. 56 | 57 | ## [3.11 Does this specification allow an origin some measure of control over a user agent’s native UI?] 58 | 59 | No. 60 | 61 | ## [3.12 Does this specification expose temporary identifiers to the web?] 62 | 63 | No. 64 | 65 | ## [3.13 Does this specification distinguish between behavior in first-party and third-party contexts?] 66 | 67 | No. 68 | 69 | ## [3.14 How should this specification work in the context of a user agent’s "incognito" mode?] 70 | 71 | Specification does not restrict access to a particular mode, nor work differently. However, this 72 | can be revisited when [privacy mode] would be formally specified. 73 | 74 | ## [3.15 Does this specification persist data to a user’s local device?] 75 | 76 | No. 77 | 78 | ## [3.16 Does this specification have a "Security Considerations" and "Privacy Considerations" section?] 79 | 80 | Yes. 81 | 82 | See: [Security & Privacy][security-and-privacy] section. 83 | 84 | ## [3.17 Does this specification allow downgrading default security characteristics?] 85 | 86 | No. 87 | 88 | 89 | [mitigation strategies]: https://w3c.github.io/sensors/#mitigation-strategies 90 | [user-identification]: https://w3c.github.io/sensors/#user-identifying 91 | [security-and-privacy]: https://w3c.github.io/accelerometer/#security-and-privacy 92 | [permission]: https://w3c.github.io/permissions/#dom-permissionname-accelerometer 93 | [POWERFUL-FEATURES]: https://w3c.github.io/webappsec-secure-contexts/ 94 | [infer user input]: https://w3c.github.io/sensors/#keystroke-monitoring 95 | [location-tracking]: https://w3c.github.io/sensors/#location-tracking 96 | [privacy mode]: https://gist.github.com/mnot/96440a5ca74fcf328d23#privacy-mode 97 | [Security and Privacy Self-Review Questionnaire]: https://w3ctag.github.io/security-questionnaire/ 98 | 99 | [3.1 Does this specification deal with personally-identifiable information?]: https://w3ctag.github.io/security-questionnaire/#pii 100 | [3.2 Does this specification deal with high-value data?]: https://w3ctag.github.io/security-questionnaire/#credentials 101 | [3.3 Does this specification introduce new state for an origin that persists across browsing sessions?]: https://w3ctag.github.io/security-questionnaire/#persistent-origin-specific-state 102 | [3.4 Does this specification expose persistent, cross-origin state to the web?]: https://w3ctag.github.io/security-questionnaire/#persistent-identifiers 103 | [3.5 Does this specification expose any other data to an origin that it doesn’t currently have access to?]: https://w3ctag.github.io/security-questionnaire/#other-data 104 | [3.6 Does this specification enable new script execution/loading mechanisms?]: https://w3ctag.github.io/security-questionnaire/#string-to-script 105 | [3.7 Does this specification allow an origin access to a user’s location?]: https://w3ctag.github.io/security-questionnaire/#location 106 | [3.8 Does this specification allow an origin access to sensors on a user’s device?]: https://w3ctag.github.io/security-questionnaire/#sensors 107 | [3.9 Does this specification allow an origin access to aspects of a user’s local computing environment?]: https://w3ctag.github.io/security-questionnaire/#local-device 108 | [3.10 Does this specification allow an origin access to other devices?]: https://w3ctag.github.io/security-questionnaire/#remote-device 109 | [3.11 Does this specification allow an origin some measure of control over a user agent’s native UI?]: https://w3ctag.github.io/security-questionnaire/#native-ui 110 | [3.12 Does this specification expose temporary identifiers to the web?]: https://w3ctag.github.io/security-questionnaire/#temporary-id 111 | [3.13 Does this specification distinguish between behavior in first-party and third-party contexts?]: https://w3ctag.github.io/security-questionnaire/#first-third-party 112 | [3.14 How should this specification work in the context of a user agent’s "incognito" mode?]: https://w3ctag.github.io/security-questionnaire/#incognito 113 | [3.15 Does this specification persist data to a user’s local device?]: https://w3ctag.github.io/security-questionnaire/#storage 114 | [3.16 Does this specification have a "Security Considerations" and "Privacy Considerations" section?]: https://w3ctag.github.io/security-questionnaire/#considerations 115 | [3.17 Does this specification allow downgrading default security characteristics?]: https://w3ctag.github.io/security-questionnaire/#relaxed-sop 116 | 117 | [Generic Sensor API]: https://w3c.github.io/sensors 118 | [Accelerometer]: https://w3c.github.io/accelerometer 119 | 120 | -------------------------------------------------------------------------------- /releases/accelerometer_coordinate_system.svg: -------------------------------------------------------------------------------- 1 | Z-ZY-YX-X -------------------------------------------------------------------------------- /images/screen_coordinate_system.svg: -------------------------------------------------------------------------------- 1 | screen_coordinate_systemYXZXYZ -------------------------------------------------------------------------------- /images/device_coordinate_system.svg: -------------------------------------------------------------------------------- 1 | device_coordinate_systemYXZYXZ -------------------------------------------------------------------------------- /index.bs: -------------------------------------------------------------------------------- 1 | 
  2 | Title: Accelerometer
  3 | Level: none
  4 | Status: ED
  5 | ED: https://w3c.github.io/accelerometer/
  6 | Shortname: accelerometer
  7 | TR: https://www.w3.org/TR/accelerometer/
  8 | Editor: Anssi Kostiainen 41974, Intel Corporation, http://intel.com/
  9 | Former Editor: Alexander Shalamov 78335, Intel Corporation, http://intel.com/
 10 | Group: dap
 11 | Abstract:
 12 |   This specification defines {{Accelerometer}}, {{LinearAccelerationSensor}} and {{GravitySensor}} interfaces for
 13 |   obtaining information about [=acceleration=] applied to the X, Y and Z axis
 14 |   of a device that hosts the sensor.
 15 | Version History: https://github.com/w3c/accelerometer/commits/main/index.bs
 16 | Indent: 2
 17 | Repository: w3c/accelerometer
 18 | Markup Shorthands: markdown on
 19 | Inline Github Issues: true
 20 | Test Suite: https://github.com/web-platform-tests/wpt/tree/main/accelerometer
 21 | Include MDN Panels: if possible
 22 | Implementation Report: https://www.w3.org/wiki/DAS/Implementations
 23 | Default Biblio Status: current
 24 | Status Text: This document is maintained and updated at any time. Some parts of this document are work in progress.
 25 |
26 | 
 27 | urlPrefix: https://w3c.github.io/sensors/; spec: GENERIC-SENSOR
 28 |   type: dfn
 29 |     text: high-level
 30 |     text: sensor
 31 |     text: latest reading
 32 |     text: default sensor
 33 |     text: sensor type
 34 |     text: local coordinate system
 35 |     text: location tracking; url: location-tracking
 36 |     text: keylogging; url: keystroke-monitoring
 37 |     text: fingerprinting; url: device-fingerprinting
 38 |     text: user identifying; url: user-identifying
 39 |     text: generic mitigations; url: mitigation-strategies
 40 |     text: supported sensor options
 41 | urlPrefix: https://www.w3.org/TR/screen-orientation/; spec: SCREEN-ORIENTATION
 42 |   type: dfn
 43 |     text: current orientation type;  url: dfn-current-orientation-type
 44 |     text: dom screen; url: dom-screen
 45 |
46 | 47 | 
 48 | {
 49 |     "KEYSTROKEDEFENSE": {
 50 |         "authors": [
 51 |             "Song, Yihang, et al"
 52 |         ],
 53 |         "id": "KEYSTROKEDEFENSE",
 54 |         "href": "https://arxiv.org/abs/1410.7746",
 55 |         "title": "Two novel defenses against motion-based keystroke inference attacks",
 56 |         "date": "2014",
 57 |         "status": "Informational",
 58 |         "publisher": "arXiv"
 59 |      },
 60 |     "TOUCHSIGNATURES": {
 61 |         "authors": [
 62 |             "Mehrnezhad, Maryam, et al"
 63 |         ],
 64 |         "id": "TOUCHSIGNATURES",
 65 |         "href": "https://arxiv.org/abs/1602.04115",
 66 |         "title": "Touchsignatures: identification of user touch actions and pins based on mobile sensor data via javascript",
 67 |         "date": "2016",
 68 |         "status": "Informational",
 69 |         "publisher": "Journal of Information Security and Applications"
 70 |      },
 71 |     "ACCESSORY": {
 72 |         "authors": [
 73 |             "Owusu, Emmanuel, et al"
 74 |         ],
 75 |         "id": "ACCESSORY",
 76 |         "href": "https://dl.acm.org/citation.cfm?id=2162095",
 77 |         "title": "ACCessory: password inference using accelerometers on smartphones",
 78 |         "date": "2012",
 79 |         "status": "Informational",
 80 |         "publisher": "Proceedings of the Twelfth Workshop on Mobile Computing Systems & Applications"
 81 |      },
 82 |     "SENSORID": {
 83 |         "href": "https://doi.org/10.1109/SP.2019.00072",
 84 |         "title": "SensorID: Sensor Calibration Fingerprinting for Smartphones",
 85 |         "date": "2019",
 86 |         "authors": [
 87 |             "Zhang, Jiexin",
 88 |             "Beresford, Alastair R.",
 89 |             "Sheret, Ian"
 90 |         ],
 91 |         "publisher": "IEEE Symposium on Security and Privacy"
 92 |     }
 93 | }
 94 |
95 | 96 | Introduction {#intro} 97 | ============ 98 | 99 | The {{Accelerometer}}, {{LinearAccelerationSensor}} and {{GravitySensor}} APIs extends the Generic Sensor API [[GENERIC-SENSOR]] 100 | interface to provide information about [=acceleration=] applied to device's 101 | X, Y and Z axis in [=local coordinate system=] defined by device. 102 | 103 | Examples {#examples} 104 | ======== 105 | 106 |
107 | 
108 |     let sensor = new Accelerometer();
109 |     sensor.start();
110 | 
111 |     sensor.onreading = () => {
112 |         console.log("Acceleration along X-axis: " + sensor.x);
113 |         console.log("Acceleration along Y-axis: " + sensor.y);
114 |         console.log("Acceleration along Z-axis: " + sensor.z);
115 |     }
116 | 
117 |     sensor.onerror = event => console.log(event.error.name, event.error.message);
118 |
119 |
120 | 121 |
122 | The following example shows how to use gravity sensor that provides 123 | readings in the [=screen coordinate system=]. The snippet will print message to the 124 | console when the [=dom screen=] is perpendicular to the ground and bottom of the 125 | rendered web page is pointing downwards. 126 | 
127 |     let sensor = new GravitySensor({frequency: 5, referenceFrame: "screen"});
128 | 
129 |     sensor.onreading = () => {
130 |       if (sensor.y >= 9.8) {
131 |         console.log("Web page is perpendicular to the ground.");
132 |       }
133 |     }
134 | 
135 |     sensor.start();
136 |
137 |
138 | 139 |
140 | The following example detects shake gesture along x axis of the device, regardless 141 | of the orientation of the [=dom screen=]. 142 | 
143 |     const shakeThreshold = 25;
144 | 
145 |     let sensor = new LinearAccelerationSensor({frequency: 60});
146 | 
147 |     sensor.addEventListener('reading', () => {
148 |       if (sensor.x > shakeThreshold) {
149 |         console.log("Shake detected.");
150 |       }
151 |     });
152 | 
153 |     sensor.start();
154 |
155 |
156 | 157 | Use Cases and Requirements {#usecases-requirements} 158 | ============================== 159 | 160 | The use cases and requirements are listed in the 161 | Motion Sensors Explainer and 162 | Sensor use cases documents. 163 | 164 | Security and Privacy Considerations {#security-and-privacy} 165 | =================================== 166 | 167 | [=Sensor readings=] provided by inertial sensors, such as accelerometer, could be used by adversaries 168 | to exploit various security threats, for example, [=keylogging=], [=location tracking=], 169 | [=fingerprinting=] and [=user identifying=]. 170 | 171 | Research papers published by security community, for instance, [[KEYSTROKEDEFENSE]], indicate that 172 | by throttling the frequency, risks of successful attacks are not fully eliminated, while throttling 173 | may greatly affect usefulness of a web application with legitimate reasons to use the sensors. 174 | 175 | The [[TOUCHSIGNATURES]] and [[ACCESSORY]] research papers propose that implementations can 176 | provide visual indication when inertial sensors are in use and/or require explicit user consent to 177 | access [=sensor readings=]. These mitigation strategies complement the [=generic mitigations=] defined 178 | in the Generic Sensor API [[!GENERIC-SENSOR]]. 179 | 180 | This specification defines an [=accelerometer reading quantization algorithm=] (called from the 181 | [=get value from latest reading=] operation) to mitigate sensor calibration fingerprinting [[SENSORID]] 182 | and attacks that rely on high precision sensor readings. The details of the quantization algorithm 183 | follow W3C Privacy Interest Group's recommendation. 184 | 185 | Permissions Policy integration {#permissions-policy-integration} 186 | ============================== 187 | 188 | This specification utilizes the [=policy-controlled feature=] identified by the string "accelerometer" defined in [[DEVICE-ORIENTATION]]. 189 | 190 | Model {#model} 191 | ===== 192 | 193 | Accelerometer {#accelerometer-model} 194 | ------------- 195 | 196 | The Accelerometer sensor type has the following associated data: 197 | 198 | : [=Extension sensor interface=] 199 | :: {{Accelerometer}} 200 | : [=Sensor permission names=] 201 | :: "accelerometer" 202 | : [=Sensor feature names=] 203 | :: "accelerometer" 204 | : [=powerful feature/Permission revocation algorithm=] 205 | :: Invoke the [=generic sensor permission revocation algorithm=] with "accelerometer". 206 | : [=Default sensor=] 207 | :: The device's main accelerometer sensor. 208 | : [=Virtual sensor type=] 209 | :: "accelerometer" 210 | 211 | A [=latest reading=] for a {{Sensor}} of Accelerometer sensor type includes three [=map/entries=] 212 | whose [=map/keys=] are "x", "y", "z" and whose [=map/values=] contain device's [=acceleration=] 213 | about the corresponding axes. 214 | 215 | The acceleration is the rate of change of velocity of a device with respect to time. Its 216 | unit is the metre per second squared (m/s2) [[SI]]. 217 | 218 | The frame of reference for the [=acceleration=] measurement must be inertial, such as, the device in free fall would 219 | provide 0 (m/s2) [=acceleration=] value for each axis. 220 | 221 | The sign of the [=acceleration=] values must be according to the right-hand convention in a [=local coordinate 222 | system=] (see figure below). 223 | 224 | Accelerometer coordinate system. 225 | 226 | Linear Acceleration Sensor {#linear-acceleration-sensor-model} 227 | -------------------------- 228 | 229 | The Linear Acceleration Sensor sensor type has the following associated data: 230 | 231 | : [=Extension sensor interface=] 232 | :: {{LinearAccelerationSensor}} 233 | : [=Sensor permission names=] 234 | :: "accelerometer" 235 | : [=Sensor feature names=] 236 | :: "accelerometer" 237 | : [=powerful feature/Permission revocation algorithm=] 238 | :: Invoke the [=generic sensor permission revocation algorithm=] with "accelerometer". 239 | : [=Virtual sensor type=] 240 | :: "linear-acceleration" 241 | 242 | A [=latest reading=] for a {{Sensor}} of Linear Acceleration Sensor sensor type includes three [=map/entries=] 243 | whose [=map/keys=] are "x", "y", "z" and whose [=map/values=] contain device's [=linear acceleration=] 244 | about the corresponding axes. 245 | 246 | The linear acceleration is an [=acceleration=] that is applied to the device that hosts 247 | the sensor, without the contribution of a [=gravity=] force. 248 | 249 | Note: The relationship between [=gravity=] and [=linear acceleration=] is discussed in [[MOTION-SENSORS#gravity-and-linear-acceleration]]. 250 | 251 | Gravity Sensor {#gravity-sensor-model} 252 | -------------- 253 | 254 | The Gravity Sensor sensor type has the following associated data: 255 | 256 | : [=Extension sensor interface=] 257 | :: {{GravitySensor}} 258 | : [=Sensor permission names=] 259 | :: "accelerometer" 260 | : [=Sensor feature names=] 261 | :: "accelerometer" 262 | : [=powerful feature/Permission revocation algorithm=] 263 | :: Invoke the [=generic sensor permission revocation algorithm=] with "accelerometer". 264 | : [=Virtual sensor type=] 265 | :: "gravity" 266 | 267 | A [=latest reading=] for a {{Sensor}} of Gravity Sensor sensor type includes three [=map/entries=] 268 | whose [=map/keys=] are "x", "y", "z" and whose [=map/values=] contain the acceleration due to [=gravity=] 269 | about the corresponding axes. 270 | 271 | The gravity is the component of the device's acceleration that prevents its velocity from increasing toward nearby masses. Devices in free fall for more than a short period of time may compute incorrect values for the gravity. 272 | 273 | Note: The relationship between [=gravity=] and [=linear acceleration=] is discussed in [[MOTION-SENSORS#gravity-and-linear-acceleration]]. 274 | 275 | Reference Frame {#reference-frame} 276 | ---------------- 277 | 278 | The [=local coordinate system=] represents the reference frame for the 279 | {{Accelerometer}}, {{LinearAccelerationSensor}}, and the {{GravitySensor}} 280 | [=sensor readings|readings=]. It can be either the [=device coordinate system=] 281 | or the [=screen coordinate system=]. 282 | 283 | The device coordinate system is defined as a three dimensional 284 | Cartesian coordinate system (x, y, z), which is bound to the physical device. 285 | For devices with a display, the origin of the [=device coordinate system=] is 286 | the center of the device display. If the device is held in its default position, 287 | the Y-axis points towards the top of the display, the X-axis points towards the right of 288 | the display and Z-axis is the vector product of X and Y axes and it points outwards from 289 | the display, and towards the viewer. The [=device coordinate system=] remains stationary 290 | regardless of the [=dom screen=] orientation (see figure below). 291 | 292 | Device coordinate system. 293 | 294 | The screen coordinate system is defined as a three dimensional 295 | Cartesian coordinate system (x, y, z), which is bound to the [=dom screen=]. 296 | The origin of the [=screen coordinate system=] in the center 297 | of the [=dom screen=]. The Y-axis always points towards the top of the [=dom screen=], 298 | the X-axis points towards the right of the [=dom screen=] and Z-axis is the 299 | vector product of X and Y axes and it and it points outwards from the [=dom screen=], 300 | and towards the viewer (see figure below). 301 | 302 | Screen coordinate system. 303 | 304 | The main difference between the [=device coordinate system=] and the [=screen coordinate system=], 305 | is that the [=screen coordinate system=] always follows the [=dom screen=] orientation, 306 | i.e. it will swap X and Y axes in relation to the device if the [=current orientation type=] 307 | changes. In contrast, the [=device coordinate system=] will always remain stationary relative to 308 | the device. 309 | 310 | API {#api} 311 | === 312 | 313 | The Accelerometer Interface {#accelerometer-interface} 314 | -------------------------------- 315 | 316 | 
317 |   [SecureContext, Exposed=Window]
318 |   interface Accelerometer : Sensor {
319 |     constructor(optional AccelerometerSensorOptions options = {});
320 |     readonly attribute double? x;
321 |     readonly attribute double? y;
322 |     readonly attribute double? z;
323 |   };
324 | 
325 |   enum AccelerometerLocalCoordinateSystem { "device", "screen" };
326 | 
327 |   dictionary AccelerometerSensorOptions : SensorOptions {
328 |     AccelerometerLocalCoordinateSystem referenceFrame = "device";
329 |   };
330 |
331 | 332 |
333 | The new Accelerometer(|options|) constructor steps are to invoke the [=construct an accelerometer object=] abstract operation with [=this=] and |options|. 334 |
335 | 336 | [=Supported sensor options=] for {{Accelerometer}} are "frequency" and "referenceFrame". 337 | 338 | ### Accelerometer.x ### {#accelerometer-x} 339 | 340 | The {{Accelerometer/x!!attribute}} attribute of the {{Accelerometer}} 341 | interface returns the result of invoking [=get value from latest reading=] with 342 | `this` and "x" as arguments. It represents the [=acceleration=] along x-axis. 343 | 344 | ### Accelerometer.y ### {#accelerometer-y} 345 | 346 | The {{Accelerometer/y!!attribute}} attribute of the {{Accelerometer}} 347 | interface returns the result of invoking [=get value from latest reading=] with 348 | `this` and "y" as arguments. It represents the [=acceleration=] along y-axis. 349 | 350 | ### Accelerometer.z ### {#accelerometer-z} 351 | 352 | The {{Accelerometer/z!!attribute}} attribute of the {{Accelerometer}} 353 | interface returns the result of invoking [=get value from latest reading=] with 354 | `this` and "z" as arguments. It represents the [=acceleration=] along z-axis. 355 | 356 | The LinearAccelerationSensor Interface {#linearaccelerationsensor-interface} 357 | -------------------------------- 358 | 359 | 
360 |   [SecureContext, Exposed=Window]
361 |   interface LinearAccelerationSensor : Accelerometer {
362 |     constructor(optional AccelerometerSensorOptions options = {});
363 |   };
364 |
365 | 366 |
367 | The new LinearAccelerationSensor(|options|) constructor steps are to invoke the [=construct an accelerometer object=] abstract operation with [=this=] and |options|. 368 |
369 | 370 | [=Supported sensor options=] for {{LinearAccelerationSensor}} are "frequency" and "referenceFrame". 371 | 372 | ### LinearAccelerationSensor.x ### {#linearaccelerationsensor-x} 373 | 374 | The {{Accelerometer/x!!attribute}} attribute of the {{LinearAccelerationSensor}} 375 | interface returns the result of invoking [=get value from latest reading=] with 376 | `this` and "x" as arguments. It represents the [=linear acceleration=] along x-axis. 377 | 378 | ### LinearAccelerationSensor.y ### {#linearaccelerationsensor-y} 379 | 380 | The {{Accelerometer/y!!attribute}} attribute of the {{LinearAccelerationSensor}} 381 | interface returns the result of invoking [=get value from latest reading=] with 382 | `this` and "y" as arguments. It represents the [=linear acceleration=] along y-axis. 383 | 384 | ### LinearAccelerationSensor.z ### {#linearaccelerationsensor-z} 385 | 386 | The {{Accelerometer/z!!attribute}} attribute of the {{LinearAccelerationSensor}} 387 | interface returns the result of invoking [=get value from latest reading=] with 388 | `this` and "z" as arguments. It represents the [=linear acceleration=] along z-axis. 389 | 390 | The GravitySensor Interface {#gravitysensor-interface} 391 | -------------------------------- 392 | 393 | 
394 |   [SecureContext, Exposed=Window]
395 |   interface GravitySensor : Accelerometer {
396 |     constructor(optional AccelerometerSensorOptions options = {});
397 |   };
398 |
399 | 400 |
401 | The new GravitySensor(|options|) constructor steps are to invoke the [=construct an accelerometer object=] abstract operation with [=this=] and |options|. 402 |
403 | 404 | [=Supported sensor options=] for {{GravitySensor}} are "frequency" and "referenceFrame". 405 | 406 | ### GravitySensor.x ### {#gravitysensor-x} 407 | 408 | The {{Accelerometer/x!!attribute}} attribute of the {{GravitySensor}} 409 | interface returns the result of invoking [=get value from latest reading=] with 410 | `this` and "x" as arguments. It represents the effect of [=acceleration=] along x-axis due to 411 | [=gravity=]. 412 | 413 | ### GravitySensor.y ### {#gravitysensor-y} 414 | 415 | The {{Accelerometer/y!!attribute}} attribute of the {{GravitySensor}} 416 | interface returns the result of invoking [=get value from latest reading=] with 417 | `this` and "y" as arguments. It represents the effect of [=acceleration=] along y-axis due to 418 | [=gravity=]. 419 | 420 | ### GravitySensor.z ### {#gravitysensor-z} 421 | 422 | The {{Accelerometer/z!!attribute}} attribute of the {{GravitySensor}} 423 | interface returns the result of invoking [=get value from latest reading=] with 424 | `this` and "z" as arguments. It represents the effect of [=acceleration=] along z-axis due to 425 | [=gravity=]. 426 | 427 | Abstract Operations {#abstract-opertaions} 428 | ============== 429 | 430 |

Construct an accelerometer object

431 | 432 |
433 | 434 | : input 435 | :: |object|, an {{Accelerometer}}, {{LinearAccelerationSensor}} or {{GravitySensor}} object. 436 | :: |options|, a {{AccelerometerSensorOptions}} object. 437 | 438 | 1. Let |allowed| be the result of invoking [=check sensor policy-controlled features=] 439 | with |object|'s [=sensor type=]. 440 | 1. If |allowed| is false, then: 441 | 1. [=Throw=] a {{SecurityError}} {{DOMException}}. 442 | 1. Invoke [=initialize a sensor object=] with |object| and |options|. 443 | 1. If |options|.{{referenceFrame!!dict-member}} is "screen", then: 444 | 1. Set |object|'s [=local coordinate system=] to the [=screen coordinate system=]. 445 | 1. Otherwise, define |object|'s [=local coordinate system=] to the [=device coordinate system=]. 446 |
447 | 448 |

Accelerometer reading quantization algorithm

449 | 450 | The [=Accelerometer=] [=sensor type=] defines the following [=reading quantization algorithm=]: 451 | 452 |
453 | : input 454 | :: |reading|, a [=sensor reading=] 455 | : output 456 | :: A [=sensor reading=] 457 | 458 | 1. Let |quantizedReading| be |reading|. 459 | 1. If |quantizedReading|["x"] is not null, set |quantizedReading|["x"] to the nearest 0.1 m/s2. 460 | 1. If |quantizedReading|["y"] is not null, set |quantizedReading|["y"] to the nearest 0.1 m/s2. 461 | 1. If |quantizedReading|["z"] is not null, set |quantizedReading|["z"] to the nearest 0.1 m/s2. 462 | 1. Return |quantizedReading|. 463 |
464 | 465 | Automation {#automation} 466 | ========== 467 | 468 | This section extends [[GENERIC-SENSOR#automation]] by providing [=Accelerometer=]-specific virtual sensor metadata. Some of the [=virtual sensor types=] used by this specification are defined in [[DEVICE-ORIENTATION]]. 469 | 470 | Accelerometer automation {#accelerometer-automation} 471 | ----------------------- 472 | 473 | The [=accelerometer virtual sensor type=] and its corresponding entry in the [=per-type virtual sensor metadata=] [=map=] are defined in [[DEVICE-ORIENTATION#automation]]. 474 | 475 | Linear Accelerometer automation {#linear-accelerometer-automation} 476 | ----------------------- 477 | 478 | The [=linear-acceleration virtual sensor type=] and its corresponding entry in the [=per-type virtual sensor metadata=] [=map=] are defined in [[DEVICE-ORIENTATION#automation]]. 479 | 480 | Gravity automation {#gravity-automation} 481 | ----------------------- 482 | 483 | The [=per-type virtual sensor metadata=] [=map=] must have the following [=map/entry=]: 484 | : [=map/key=] 485 | :: "[=gravity virtual sensor type|gravity=]" 486 | : [=map/value=] 487 | :: A [=virtual sensor metadata=] whose [=virtual sensor metadata/reading parsing algorithm=] is [=parse xyz reading=]. 488 | 489 | Acknowledgements {#acknowledgements} 490 | ================ 491 | 492 | Tobie Langel for the work on Generic Sensor API. 493 | 494 | W3C Privacy Interest Group and Paul Jensen for the sensor calibration fingerprinting mitigation proposal and discussion. 495 | -------------------------------------------------------------------------------- /releases/WD-accelerometer-20160913.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Accelerometer Sensor 6 | 7 | 8 | 9 | 10 | 20 | 66 | 95 | 157 | 194 | 252 | 253 |
254 |

255 |

Accelerometer Sensor

256 |

W3C First Public Working Draft,

257 |
258 |
259 |
This version: 260 |
https://www.w3.org/TR/2016/WD-accelerometer-20160913/ 261 |
Latest published version: 262 |
https://www.w3.org/TR/accelerometer/ 263 |
Editor's Draft: 264 |
https://w3c.github.io/accelerometer/ 265 |
Version History: 266 |
https://github.com/w3c/accelerometer/commits/gh-pages/index.bs 267 |
Feedback: 268 |
public-device-apis@w3.org with subject line “[accelerometer] … message topic …” (archives) 269 |
Issue Tracking: 270 |
GitHub 271 |
Editors: 272 |
Anssi Kostiainen (Intel Corporation) 273 |
Alexander Shalamov (Intel Corporation) 274 |
Bug Reports: 275 |
via the w3c/accelerometer repository on GitHub 276 |
Test Suite: 277 |
web-platform-tests on GitHub 278 |
279 |
280 |
281 |

Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

282 |
283 |
284 |

Abstract

285 |
286 |

This specification defines accelerometer sensor interface for 287 | 288 | obtaining information about acceleration applied to the X, Y and Z axis 289 | of a device that hosts the sensor.

290 |
291 |

Status of this document

292 |
293 |

This section describes the status of this document at the time of 294 | its publication. Other documents may supersede this document. A list of 295 | current W3C publications and the latest revision of this technical report 296 | can be found in the W3C technical reports 297 | index at https://www.w3.org/TR/.

298 |

This document was published by the Device and Sensors Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

299 |

If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). 300 | When sending e-mail, 301 | please put the text “accelerometer” in the subject, 302 | preferably like this: 303 | “[accelerometer] …summary of comment…”. 304 | All comments are welcome.

305 |

This document is a First Public Working Draft.

306 |

Publication as a First Public Working Draft does not imply endorsement by the W3C 307 | Membership. This is a draft document and may be updated, replaced or 308 | obsoleted by other documents at any time. It is inappropriate to cite this 309 | document as other than work in progress.

310 |

This document was produced by a group operating under 311 | the 5 February 2004 W3C Patent Policy. 312 | W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; 313 | that page also includes instructions for disclosing a patent. 314 | An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

315 |

This document is governed by the 1 September 2015 W3C Process Document.

316 |

317 |
318 |
319 | 356 |
357 |

1. Introduction

358 |

The Accelerometer Sensor extends the Generic Sensor API [GENERIC-SENSOR] interface to provide information about acceleration applied to device’s 359 | X, Y and Z axis in local coordinate system defined by device.

360 |

2. Examples

361 |
362 | 363 | 
let sensor = new AccelerometerSensor({includeGravity: false, frequency: 60});
364 | sensor.start();
365 | 
366 | sensor.onchange = event => {
367 |     console.log("Linear acceleration for an X-axis: " + event.reading.accelerationX);
368 |     console.log("Linear acceleration for an Y-axis: " + event.reading.accelerationY);
369 |     console.log("Linear acceleration for an Z-axis: " + event.reading.accelerationZ);
370 | }
371 | 
372 | sensor.onerror = event => console.log(event.error.name, event.error.message);
373 |
374 |
375 |

3. Security and Privacy Considerations

376 |

There are no specific security and privacy considerations 377 | beyond those described in the Generic Sensor API [GENERIC-SENSOR].

378 |

4. Model

379 |

The Accelerometer Sensor’s associated Sensor subclass is the AccelerometerSensor class.

380 |

The Accelerometer Sensor’s associated SensorReading subclass is the AccelerometerSensorReading class.

381 |

The Accelerometer Sensor has a default sensor, 382 | which is the device’s main accelerometer sensor.

383 |

The Accelerometer Sensor has a single supported reporting mode which is "auto".

384 |

The Accelerometer Sensor’s permission name is "accelerometer". 385 | It has no associated PermissionDescriptor.

386 |

The Accelerometer Sensor has an associated abstract operation 387 | to retrieve the sensor permission which 388 | must simply return a permission whose name is "accelerometer".

389 |

The Accelerometer Sensor has an associated abstract operation 390 | to construct a SensorReading object which creates a new AccelerometerSensorReading object and sets its accelerationX, accelerationY and accelerationZ attributes 391 | to zero.

392 |

The linear acceleration is an acceleration that is applied to the device that hosts 393 | the sensor, without the contribution of a gravity force.

394 |

The AccelerometerSensorReading's attribute values must be in [SI] units for acceleration, metre 395 | per second squared (m/s^2), expressed in a three-dimentional Cartesian local coordinate system defined by the device.

396 |

The frame of reference for the acceleration measurement must be inertial, such as device in free fall would 397 | provide 0 (m/s^2) acceleration value for each axis.

398 |

The sign of the acceleration values must be according to the right-hand convention in a local coordinate 399 | system defined by the device.

400 |

Note: The local coordinate system of a mobile device is usually defined relative to 401 | the device’s screen when the device in its default orientation (see figure below).

402 |

Accelerometer coordinate system.

403 |

5. API

404 |

5.1. The AccelerometerSensor Interface

405 | 
[Constructor(optional AccelerometerSensorOptions accelerometerSensorOptions)]
406 | interface AccelerometerSensor : Sensor {
407 |   readonly attribute AccelerometerSensorReading? reading;
408 |   readonly attribute boolean includesGravity;
409 | };
410 |
411 |

To Construct an AccelerometerSensor Object the user agent must invoke 412 | the construct a Sensor object abstract operation.

413 |

5.2. The AccelerometerSensorOptions Dictionary

414 | 
dictionary AccelerometerSensorOptions :  SensorOptions  {
415 |   boolean includeGravity = true;
416 | };
417 |
418 |

By default, the Accelerometer sensor would provide acceleration information including 419 | the effect of the gravity force. In cases, when linear acceleration information is 420 | required, AccelerometerSensorOptions dictionary with and dictionary member includeGravity that is set to false, 421 | must be provided to AccelerometerSensor constructor.

422 |

5.3. The AccelerometerSensorReading Interface

423 | 
[Constructor(AccelerometerSensorReadingInit AccelerometerSensorReadingInit)]
424 | interface AccelerometerSensorReading : SensorReading {
425 |     readonly attribute double accelerationX;
426 |     readonly attribute double accelerationY;
427 |     readonly attribute double accelerationZ;
428 | };
429 | 
430 | dictionary AccelerometerSensorReadingInit {
431 |     double accelerationX = 0;
432 |     double accelerationY = 0;
433 |     double accelerationZ = 0;
434 | };
435 |
436 |

5.3.1. The AccelerometerSensor attributes

437 |

The includesGravity attribute of the AccelerometerSensor interface represents whether the acceleration information provided by the sensor includes effect of the gravity 438 | force. In case when includesGravity equals to false, AccelerometerSensor will provide linear acceleration information.

439 |

5.3.2. The AccelerometerSensorReading constructor

440 |

The AccelerometerSensorReading constructor accepts AccelerometerSensorReadingInit dictionary that is used 441 | for initialization of AccelerometerSensorReading attributes.

442 |

5.3.3. The AccelerometerSensorReading attributes

443 |

The accelerationX attribute of the AccelerometerSensorReading interface represents the acceleration along X-axis.

444 |

The accelerationY attribute of the AccelerometerSensorReading interface represents the acceleration along Y-axis.

445 |

The accelerationZ attribute of the AccelerometerSensorReading interface represents the acceleration along Z-axis.

446 |

6. Acknowledgements

447 |

Tobie Langel for the work on Generic Sensor API.

448 |

7. Conformance

449 |

Conformance requirements are expressed with a combination of 450 | descriptive assertions and RFC 2119 terminology. The key words "MUST", 451 | "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", 452 | "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this 453 | document are to be interpreted as described in RFC 2119. 454 | However, for readability, these words do not appear in all uppercase 455 | letters in this specification.

456 |

All of the text of this specification is normative except sections 457 | explicitly marked as non-normative, examples, and notes. [RFC2119]

458 |

A conformant user agent must implement all the requirements 459 | listed in this specification that are applicable to user agents.

460 |

The IDL fragments in this specification must be interpreted as required for 461 | conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

462 |
463 | 464 |

Index

465 |

Terms defined by this specification

466 | 502 |

Terms defined by reference

503 | 528 |

References

529 |

Normative References

530 |
531 |
[GENERIC-SENSOR] 532 |
Tobie Langel; Rick Waldron. Generic Sensor API. 24 March 2016. WD. URL: https://www.w3.org/TR/generic-sensor/ 533 |
[PERMISSIONS] 534 |
Mounir Lamouri; Marcos Caceres. The Permissions API. 7 April 2015. WD. URL: https://www.w3.org/TR/permissions/ 535 |
[RFC2119] 536 |
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 537 |
[WEBIDL] 538 |
Cameron McCormack; Boris Zbarsky. WebIDL Level 1. 8 March 2016. CR. URL: https://www.w3.org/TR/WebIDL-1/ 539 |
540 |

Informative References

541 |
542 |
[SI] 543 |
SI Brochure: The International System of Units (SI), 8th edition. 2014. URL: http://www.bipm.org/en/publications/si-brochure/ 544 |
545 |

IDL Index

546 | 
[Constructor(optional AccelerometerSensorOptions accelerometerSensorOptions)]
547 | interface AccelerometerSensor : Sensor {
548 |   readonly attribute AccelerometerSensorReading? reading;
549 |   readonly attribute boolean includesGravity;
550 | };
551 | 
552 | dictionary AccelerometerSensorOptions :  SensorOptions  {
553 |   boolean includeGravity = true;
554 | };
555 | 
556 | [Constructor(AccelerometerSensorReadingInit AccelerometerSensorReadingInit)]
557 | interface AccelerometerSensorReading : SensorReading {
558 |     readonly attribute double accelerationX;
559 |     readonly attribute double accelerationY;
560 |     readonly attribute double accelerationZ;
561 | };
562 | 
563 | dictionary AccelerometerSensorReadingInit {
564 |     double accelerationX = 0;
565 |     double accelerationY = 0;
566 |     double accelerationZ = 0;
567 | };
568 | 
569 |
570 | 577 | 584 | 592 | 598 | 605 | 611 | 620 | 627 | 634 | 641 | 647 | --------------------------------------------------------------------------------