Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 1 | page.title=Reporting modes |
| 2 | @jd:body |
| 3 | |
| 4 | <!-- |
| 5 | Copyright 2014 The Android Open Source Project |
| 6 | |
| 7 | Licensed under the Apache License, Version 2.0 (the "License"); |
| 8 | you may not use this file except in compliance with the License. |
| 9 | You may obtain a copy of the License at |
| 10 | |
| 11 | http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | |
| 13 | Unless required by applicable law or agreed to in writing, software |
| 14 | distributed under the License is distributed on an "AS IS" BASIS, |
| 15 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 16 | See the License for the specific language governing permissions and |
| 17 | limitations under the License. |
| 18 | --> |
| 19 | <div id="qv-wrapper"> |
| 20 | <div id="qv"> |
| 21 | <h2>In this document</h2> |
| 22 | <ol id="auto-toc"> |
| 23 | </ol> |
| 24 | </div> |
| 25 | </div> |
| 26 | |
| 27 | <p>Sensors can generate events in different ways called reporting modes; each |
| 28 | sensor type has one and only one reporting mode associated with it. Four |
| 29 | reporting modes exist.</p> |
| 30 | <h2 id="continuous">Continuous</h2> |
| 31 | <p>Events are generated at a constant rate defined by the <a href="hal-interface.html#sampling_period_ns">sampling_period_ns</a> parameter passed to the <code>batch</code> function. Example sensors using the continuous |
| 32 | reporting mode are <a href="sensor-types.html#accelerometer">accelerometers</a> and <a href="sensor-types.html#gyroscope">gyroscopes</a>.</p> |
| 33 | <h2 id="on-change">On-change</h2> |
| 34 | <p>Events are generated only if the measured values have changed. Activating the |
| 35 | sensor at the HAL level (calling <code>activate(..., enable=1)</code> on it) also triggers |
| 36 | an event, meaning the HAL must return an event immediately when an on-change |
| 37 | sensor is activated. Example sensors using the on-change reporting mode are the |
| 38 | step counter, proximity, and heart rate sensor types.</p> |
| 39 | <p>The <a href="hal-interface.html#sampling_period_ns">sampling_period_ns</a> |
| 40 | parameter passed to the <code>batch</code> function is used to set the minimum |
| 41 | time between consecutive events, meaning an event should not be generated until |
| 42 | sampling_period_ns nanoseconds elapsed since the last event, even if the value |
| 43 | changed since then. If the value changed, an event must be generated as soon as |
| 44 | <code>sampling_period_ns</code> has elapsed since the last event.</p> |
| 45 | <p>For example, suppose:</p> |
| 46 | <ul> |
| 47 | <li> We activate the step counter with <code>sampling_period_ns = 10 * 10^9</code> (10 seconds). </li> |
| 48 | <li> And walk for 55 seconds, then stand still for one minute. </li> |
| 49 | <li> Then the events will be generated about every 10 seconds during the first |
| 50 | minute (including at time t=0 because of the activation of the sensor, and t=60 |
| 51 | seconds), for a total of seven events, and no event will be generated in the second |
| 52 | minute because the value of the step count didn’t change after t=60 seconds. </li> |
| 53 | </ul> |
| 54 | <h2 id="one-shot">One-shot</h2> |
| 55 | <p>Upon detection of an event, the sensor deactivates itself and then sends a |
| 56 | single event through the HAL. Order matters to avoid race conditions. (The |
| 57 | sensor must be deactivated before the event is reported through the HAL). No |
| 58 | other event is sent until the sensor is reactivated. <a href="sensor-types.html#significant_motion">Significant motion</a> is an example of this kind of sensor.</p> |
| 59 | <p>One-shot sensors are sometimes referred to as trigger sensors.</p> |
| 60 | <p>The <code>sampling_period_ns</code> and <code>max_report_latency_ns</code> |
| 61 | parameters passed to the <code>batch</code> function are ignored. Events from |
| 62 | one-shot events cannot be stored in hardware FIFOs; the events must be |
| 63 | reported as soon as they are generated.</p> |
| 64 | <h2 id="special">Special</h2> |
| 65 | <p>See the individual <a href="sensor-types.html">sensor type descriptions</a> |
| 66 | for details on when the events are generated.</p> |