1 |
|
2 | # license: Licensed to the Apache Software Foundation (ASF) under one
|
3 | # or more contributor license agreements. See the NOTICE file
|
4 | # distributed with this work for additional information
|
5 | # regarding copyright ownership. The ASF licenses this file
|
6 | # to you under the Apache License, Version 2.0 (the
|
7 | # "License"); you may not use this file except in compliance
|
8 | # with the License. You may obtain a copy of the License at
|
9 | #
|
10 | # http://www.apache.org/licenses/LICENSE-2.0
|
11 | #
|
12 | # Unless required by applicable law or agreed to in writing,
|
13 | # software distributed under the License is distributed on an
|
14 | # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
15 | # KIND, either express or implied. See the License for the
|
16 | # specific language governing permissions and limitations
|
17 | # under the License.
|
18 | -->
|
19 |
|
20 | [![Build Status](https://travis-ci.org/apache/cordova-plugin-device-motion.svg?branch=master)](https://travis-ci.org/apache/cordova-plugin-device-motion)
|
21 |
|
22 | # cordova-plugin-device-motion
|
23 |
|
24 | This plugin provides access to the device's accelerometer. The accelerometer is
|
25 | a motion sensor that detects the change (_delta_) in movement relative to the
|
26 | current device orientation, in three dimensions along the _x_, _y_, and _z_
|
27 | axis.
|
28 |
|
29 | Access is via a global `navigator.accelerometer` object.
|
30 |
|
31 | Although the object is attached to the global scoped `navigator`, it is not available until after the `deviceready` event.
|
32 |
|
33 | document.addEventListener("deviceready", onDeviceReady, false);
|
34 | function onDeviceReady() {
|
35 | console.log(navigator.accelerometer);
|
36 | }
|
37 |
|
38 | Report issues with this plugin on the [Apache Cordova issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Device%20Motion%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC)
|
39 |
|
40 | ## Installation
|
41 |
|
42 | cordova plugin add cordova-plugin-device-motion
|
43 |
|
44 | ## Supported Platforms
|
45 |
|
46 | - Amazon Fire OS
|
47 | - Android
|
48 | - BlackBerry 10
|
49 | - Browser
|
50 | - Firefox OS
|
51 | - iOS
|
52 | - Tizen
|
53 | - Windows Phone 8
|
54 | - Windows
|
55 |
|
56 | ## Methods
|
57 |
|
58 | - navigator.accelerometer.getCurrentAcceleration
|
59 | - navigator.accelerometer.watchAcceleration
|
60 | - navigator.accelerometer.clearWatch
|
61 |
|
62 | ## Objects
|
63 |
|
64 | - Acceleration
|
65 |
|
66 | ## navigator.accelerometer.getCurrentAcceleration
|
67 |
|
68 | Get the current acceleration along the _x_, _y_, and _z_ axes.
|
69 |
|
70 | These acceleration values are returned to the `accelerometerSuccess`
|
71 | callback function.
|
72 |
|
73 | navigator.accelerometer.getCurrentAcceleration(accelerometerSuccess, accelerometerError);
|
74 |
|
75 |
|
76 | ### Example
|
77 |
|
78 | function onSuccess(acceleration) {
|
79 | alert('Acceleration X: ' + acceleration.x + '\n' +
|
80 | 'Acceleration Y: ' + acceleration.y + '\n' +
|
81 | 'Acceleration Z: ' + acceleration.z + '\n' +
|
82 | 'Timestamp: ' + acceleration.timestamp + '\n');
|
83 | }
|
84 |
|
85 | function onError() {
|
86 | alert('onError!');
|
87 | }
|
88 |
|
89 | navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);
|
90 |
|
91 | ### Browser Quirks
|
92 |
|
93 | Values for X, Y, Z motion are all randomly generated in order to simulate the accelerometer.
|
94 |
|
95 | ### Android Quirks
|
96 |
|
97 | The accelerometer is called with the `SENSOR_DELAY_UI` flag, which limits the maximum readout frequency to something between 20 and 60 Hz, depending on the device. Values for __period__ corresponding to higher frequencies will result in duplicate samples. More details can be found in the [Android API Guide](http://developer.android.com/guide/topics/sensors/sensors_overview.html#sensors-monitor).
|
98 |
|
99 |
|
100 | ### iOS Quirks
|
101 |
|
102 | - iOS doesn't recognize the concept of getting the current acceleration at any given point.
|
103 |
|
104 | - You must watch the acceleration and capture the data at given time intervals.
|
105 |
|
106 | - Thus, the `getCurrentAcceleration` function yields the last value reported from a `watchAccelerometer` call.
|
107 |
|
108 | ## navigator.accelerometer.watchAcceleration
|
109 |
|
110 | Retrieves the device's current `Acceleration` at a regular interval, executing
|
111 | the `accelerometerSuccess` callback function each time. Specify the interval in
|
112 | milliseconds via the `acceleratorOptions` object's `frequency` parameter.
|
113 |
|
114 | The returned watch ID references the accelerometer's watch interval,
|
115 | and can be used with `navigator.accelerometer.clearWatch` to stop watching the
|
116 | accelerometer.
|
117 |
|
118 | var watchID = navigator.accelerometer.watchAcceleration(accelerometerSuccess,
|
119 | accelerometerError,
|
120 | accelerometerOptions);
|
121 |
|
122 | - __accelerometerOptions__: An object with the following optional keys:
|
123 | - __period__: requested period of calls to accelerometerSuccess with acceleration data in Milliseconds. _(Number)_ (Default: 10000)
|
124 |
|
125 |
|
126 | ### Example
|
127 |
|
128 | function onSuccess(acceleration) {
|
129 | alert('Acceleration X: ' + acceleration.x + '\n' +
|
130 | 'Acceleration Y: ' + acceleration.y + '\n' +
|
131 | 'Acceleration Z: ' + acceleration.z + '\n' +
|
132 | 'Timestamp: ' + acceleration.timestamp + '\n');
|
133 | }
|
134 |
|
135 | function onError() {
|
136 | alert('onError!');
|
137 | }
|
138 |
|
139 | var options = { frequency: 3000 }; // Update every 3 seconds
|
140 |
|
141 | var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);
|
142 |
|
143 | ### iOS Quirks
|
144 |
|
145 | The API calls the success callback function at the interval requested,
|
146 | but restricts the range of requests to the device between 40ms and
|
147 | 1000ms. For example, if you request an interval of 3 seconds,
|
148 | (3000ms), the API requests data from the device every 1 second, but
|
149 | only executes the success callback every 3 seconds.
|
150 |
|
151 | ## navigator.accelerometer.clearWatch
|
152 |
|
153 | Stop watching the `Acceleration` referenced by the `watchID` parameter.
|
154 |
|
155 | navigator.accelerometer.clearWatch(watchID);
|
156 |
|
157 | - __watchID__: The ID returned by `navigator.accelerometer.watchAcceleration`.
|
158 |
|
159 | ### Example
|
160 |
|
161 | var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);
|
162 |
|
163 | // ... later on ...
|
164 |
|
165 | navigator.accelerometer.clearWatch(watchID);
|
166 |
|
167 | ## Acceleration
|
168 |
|
169 | Contains `Accelerometer` data captured at a specific point in time.
|
170 | Acceleration values include the effect of gravity (9.81 m/s^2), so that when a
|
171 | device lies flat and facing up, _x_, _y_, and _z_ values returned should be
|
172 | `0`, `0`, and `9.81`.
|
173 |
|
174 | ### Properties
|
175 |
|
176 | - __x__: Amount of acceleration on the x-axis. (in m/s^2) _(Number)_
|
177 | - __y__: Amount of acceleration on the y-axis. (in m/s^2) _(Number)_
|
178 | - __z__: Amount of acceleration on the z-axis. (in m/s^2) _(Number)_
|
179 | - __timestamp__: Creation timestamp in milliseconds. _(DOMTimeStamp)_
|