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