Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 1 | page.title=HAL interface |
| 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 | |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 27 | <p>The HAL interface, declared in <a href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a>, represents the interface between the Android <a href="sensor-stack.html#framework">framework</a> and the hardware-specific software. A HAL implementation must define each |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 28 | function declared in sensors.h. The main functions are:</p> |
| 29 | <ul> |
| 30 | <li><code>get_sensors_list</code> - Returns the list of all sensors. </li> |
| 31 | <li><code>activate</code> - Starts or stops a sensor. </li> |
| 32 | <li><code>batch</code> - Sets a sensor’s parameters such as sampling frequency and maximum |
| 33 | reporting latency. </li> |
| 34 | <li><code>setDelay</code> - Used only in HAL version 1.0. Sets the sampling frequency for a |
| 35 | given sensor. </li> |
| 36 | <li><code>flush</code> - Flushes the FIFO of the specified sensor and reports a flush complete |
| 37 | event when this is done. </li> |
| 38 | <li><code>poll</code> - Returns available sensor events. </li> |
| 39 | </ul> |
| 40 | <p>The implementation must be thread safe and allow these functions to be called |
| 41 | from different threads.</p> |
| 42 | <p>The interface also defines several types used by those functions. The main |
| 43 | types are:</p> |
| 44 | <ul> |
| 45 | <li><code>sensors_module_t</code></li> |
| 46 | <li><code>sensors_poll_device_t</code></li> |
| 47 | <li><code>sensor_t</code></li> |
| 48 | <li><code>sensors_event_t</code></li> |
| 49 | </ul> |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 50 | <p>In addition to the sections below, see <a href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> for more information on those types.</p> |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 51 | <h2 id="get_sensors_list_list">get_sensors_list(list)</h2> |
| 52 | <pre>int (*get_sensors_list)(struct sensors_module_t* module, struct sensor_t |
| 53 | const** list);</pre> |
| 54 | <p>Provides the list of sensors implemented by the HAL. See <a href="#sensor_t">sensor_t</a> for details on how the sensors are defined.</p> |
| 55 | <p>The order in which the sensors appear in the list is the order in which the |
| 56 | sensors will be reported to the applications. Usually, the base sensors appear |
| 57 | first, followed by the composite sensors.</p> |
| 58 | <p>If several sensors share the same sensor type and wake-up property, the first |
| 59 | one in the list is called the “default” sensor. It is the one returned by |
| 60 | <code>getDefaultSensor(int sensorType, bool wakeUp)</code>.</p> |
| 61 | <p>This function returns the number of sensors in the list.</p> |
| 62 | <h2 id="activate_sensor_true_false">activate(sensor, true/false)</h2> |
| 63 | <pre>int (*activate)(struct sensors_poll_device_t *dev, int sensor_handle, int |
| 64 | enabled);</pre> |
| 65 | <p>Activates or deactivates a sensor.</p> |
| 66 | <p><code>sensor_handle</code> is the handle of the sensor to activate/deactivate. A sensor’s |
| 67 | handle is defined by the <code>handle</code> field of its <a href="#sensor_t">sensor_t</a> structure.</p> |
| 68 | <p><code>enabled</code> is set to 1 to enable or 0 to disable the sensor.</p> |
| 69 | <p>One-shot sensors deactivate themselves automatically upon receiving an event, |
| 70 | and they must still accept to be deactivated through a call to <code>activate(..., |
| 71 | enabled=0)</code>.</p> |
| 72 | <p>Non-wake-up sensors never prevent the SoC from going into suspend mode; that |
| 73 | is, the HAL shall not hold a partial wake-lock on behalf of applications.</p> |
| 74 | <p>Wake-up sensors, when delivering events continuously, can prevent the SoC from |
| 75 | going into suspend mode, but if no event needs to be delivered, the partial |
| 76 | wake-lock must be released.</p> |
| 77 | <p>If <code>enabled</code> is 1 and the sensor is already activated, this function is a no-op |
| 78 | and succeeds.</p> |
| 79 | <p>If <code>enabled</code> is 0 and the sensor is already deactivated, this function is a no-op |
| 80 | and succeeds.</p> |
| 81 | <p>This function returns 0 on success and a negative error number otherwise.</p> |
| 82 | <h2 id="batch_sensor_flags_sampling_period_maximum_report_latency">batch(sensor, flags, sampling period, maximum report latency)</h2> |
| 83 | <pre> |
| 84 | int (*batch)( |
| 85 | struct sensors_poll_device_1* dev, |
| 86 | int sensor_handle, |
| 87 | int flags, |
| 88 | int64_t sampling_period_ns, |
| 89 | int64_t max_report_latency_ns); |
| 90 | </pre> |
| 91 | <p>Sets a sensor’s parameters, including <a href="#sampling_period_ns">sampling frequency</a> and <a href="#max_report_latency_ns">maximum report latency</a>. This function can be called while the sensor is activated, in which case it |
| 92 | must not cause any sensor measurements to be lost: Transitioning from one |
| 93 | sampling rate to the other cannot cause lost events, nor can transitioning from |
| 94 | a high maximum report latency to a low maximum report latency.</p> |
| 95 | <p><code>sensor_handle</code> is the handle of the sensor to configure.</p> |
| 96 | <p><code>flags</code> is currently unused.</p> |
| 97 | <p><code>sampling_period_ns</code> is the sampling period at which the sensor should run, in |
| 98 | nanoseconds. See <a href="#sampling_period_ns">sampling_period_ns</a> for more details.</p> |
| 99 | <p><code>max_report_latency_ns</code> is the maximum time by which events can be delayed before |
| 100 | being reported through the HAL, in nanoseconds. See the <a href="#max_report_latency_ns">max_report_latency_ns</a> paragraph for more details.</p> |
| 101 | <p>This function returns 0 on success and a negative error number otherwise.</p> |
| 102 | <h3 id="sampling_period_ns">sampling_period_ns</h3> |
| 103 | <p>What the <code>sampling_period_ns</code> parameter means depends on the specified sensor's |
| 104 | reporting mode:</p> |
| 105 | <ul> |
| 106 | <li> Continuous: <code>sampling_period_ns</code> is the sampling rate, meaning the rate at which |
| 107 | events are generated. </li> |
| 108 | <li> On-change: <code>sampling_period_ns</code> limits the sampling rate of events, meaning |
| 109 | events are generated no faster than every <code>sampling_period_ns</code> nanoseconds. There |
| 110 | might be periods longer than <code>sampling_period_ns</code> where no event is generated if |
| 111 | the measured values do not change for long periods. See <a |
| 112 | href="report-modes.html#on-change">on-change</a> reporting mode for more |
| 113 | details. </li> |
| 114 | <li> One-shot: <code>sampling_period_ns</code> is ignored. It has no effect. </li> |
| 115 | <li> Special: See the specific <a href="sensor-types.html">sensor type |
| 116 | descriptions</a> for details on how <code>sampling_period_ns</code> is used |
| 117 | for special sensors. </li> |
| 118 | </ul> |
| 119 | <p>See <a href="report-modes.html">Reporting modes</a> for more information |
| 120 | about the impact of <code>sampling_period_ns</code> in the different modes.</p> |
| 121 | <p>For continuous and on-change sensors,</p> |
| 122 | <ul> |
| 123 | <li> if <code>sampling_period_ns</code> is less than |
| 124 | <code>sensor_t.minDelay</code>, then the HAL implementation must silently |
| 125 | clamp it to <code>max(sensor_t.minDelay, 1ms)</code>. Android |
| 126 | does not support the generation of events at more than 1000Hz. </li> |
| 127 | <li> if <code>sampling_period_ns</code> is greater than |
| 128 | <code>sensor_t.maxDelay</code>, then the HAL |
| 129 | implementation must silently truncate it to <code>sensor_t.maxDelay</code>. </li> |
| 130 | </ul> |
| 131 | <p>Physical sensors sometimes have limitations on the rates at which they can run |
| 132 | and the accuracy of their clocks. To account for this, we allow the actual |
| 133 | sampling frequency to differ from the requested frequency, as long as it |
| 134 | satisfies the requirements in the table below.</p> |
| 135 | <table> |
| 136 | <tr> |
| 137 | <th><p>If the requested frequency is</p></th> |
| 138 | <th><p>Then the actual frequency must be</p></th> |
| 139 | </tr> |
| 140 | <tr> |
| 141 | <td><p>below min frequency (<1/maxDelay)</p></td> |
| 142 | <td><p>between 90% and 110% of the min frequency</p></td> |
| 143 | </tr> |
| 144 | <tr> |
| 145 | <td><p>between min and max frequency</p></td> |
| 146 | <td><p>between 90% and 220% of the requested frequency</p></td> |
| 147 | </tr> |
| 148 | <tr> |
| 149 | <td><p>above max frequency (>1/minDelay)</p></td> |
| 150 | <td><p>between 90% and 110% of the max frequency</p> |
| 151 | <p>and below 1100Hz</p></td> |
| 152 | </tr> |
| 153 | </table> |
| 154 | <p>Note that this contract is valid only at the HAL level, where there is always a |
| 155 | single client. At the SDK level, applications might get different rates, due to |
| 156 | the multiplexing happening in the Framework. See <a |
| 157 | href="sensor-stack.html#framework">Framework</a> for more details.</p> |
| 158 | <h3 id="max_report_latency_ns">max_report_latency_ns</h3> |
| 159 | <p><code>max_report_latency_ns</code> sets the maximum time in nanoseconds, by which events can |
| 160 | be delayed and stored in the hardware FIFO before being reported through the |
| 161 | HAL while the SoC is awake.</p> |
| 162 | <p>A value of zero signifies that the events must be reported as soon as they are |
| 163 | measured, either skipping the FIFO altogether, or emptying the FIFO as soon as |
| 164 | one event from this sensor is present in it.</p> |
| 165 | <p>For example, an accelerometer activated at 50Hz with <code>max_report_latency_ns=0</code> |
| 166 | will trigger interrupts 50 times per second when the SoC is awake.</p> |
| 167 | <p>When <code>max_report_latency_ns>0</code>, sensor events do not need to be reported as soon |
| 168 | as they are detected. They can be temporarily stored in the hardware FIFO and |
| 169 | reported in batches, as long as no event is delayed by more than |
| 170 | max_report_latency_ns nanoseconds. That is, all events since the previous batch |
| 171 | are recorded and returned at once. This reduces the amount of interrupts sent |
| 172 | to the SoC and allows the SoC to switch to a lower power mode (idle) while the |
| 173 | sensor is capturing and batching data.</p> |
| 174 | <p>Each event has a timestamp associated with it. Delaying the time at which an |
| 175 | event is reported does not impact the event timestamp. The timestamp must be |
| 176 | accurate and correspond to the time at which the event physically happened, not |
| 177 | the time it is being reported. </p> |
| 178 | <p>Allowing sensor events to be stored temporarily in the hardware FIFO does not |
| 179 | modify the behavior of <code>poll</code>: events from different sensors can be interleaved, |
| 180 | and as usual, all events from the same sensor are time-ordered.</p> |
| 181 | <p>See <a href="batching.html">Batching</a> for more details on sensor |
| 182 | batching, including behaviors in suspend mode and out of suspend mode.</p> |
| 183 | <h2 id="setdelay_sensor_sampling_period">setDelay(sensor, sampling period)</h2> |
| 184 | <pre> |
| 185 | int (*setDelay)( |
| 186 | struct sensors_poll_device_t *dev, |
| 187 | int sensor_handle, |
| 188 | int64_t sampling_period_ns); |
| 189 | </pre> |
| 190 | <p>After HAL version 1.0, this function is deprecated and is never called. |
| 191 | Instead, the <code>batch</code> function is called to set the |
| 192 | <code>sampling_period_ns</code> parameter.</p> |
| 193 | <p>In HAL version 1.0, setDelay was used instead of batch to set <a href="#sampling_period_ns">sampling_period_ns</a>.</p> |
| 194 | <h2 id="flush_sensor">flush(sensor)</h2> |
| 195 | <pre>int (*flush)(struct sensors_poll_device_1* dev, int sensor_handle);</pre> |
| 196 | <p>Add a <a href="#metadata_flush_complete_events">flush complete event</a> to the end of the hardware FIFO for the specified sensor and flushes the FIFO; |
| 197 | those events are delivered as usual (i.e.: as if the maximum reporting latency |
| 198 | had expired) and removed from the FIFO.</p> |
| 199 | <p>The flush happens asynchronously (i.e.: this function must return immediately). |
| 200 | If the implementation uses a single FIFO for several sensors, that FIFO is |
| 201 | flushed and the flush complete event is added only for the specified sensor.</p> |
| 202 | <p>If the specified sensor has no FIFO (no buffering possible), or if the FIFO, |
| 203 | was empty at the time of the call, <code>flush</code> must still succeed and send a flush |
| 204 | complete event for that sensor. This applies to all sensors other than one-shot |
| 205 | sensors.</p> |
| 206 | <p>When <code>flush</code> is called, even if a flush event is already in the FIFO for that |
| 207 | sensor, an additional one must be created and added to the end of the FIFO, and |
| 208 | the FIFO must be flushed. The number of <code>flush</code> calls must be |
| 209 | equal to the number of flush complete events created.</p> |
| 210 | <p><code>flush</code> does not apply to <a href="report-modes.html#one-shot">one-shot</a> |
| 211 | sensors; if <code>sensor_handle</code> refers to a one-shot sensor, |
| 212 | <code>flush</code> must return <code>-EINVAL</code> and not generate any |
| 213 | flush complete metadata event.</p> |
| 214 | <p>This function returns 0 on success, <code>-EINVAL</code> if the specified sensor is a |
| 215 | one-shot sensor or wasn’t enabled, and a negative error number otherwise.</p> |
| 216 | <h2 id="poll">poll()</h2> |
| 217 | <pre>int (*poll)(struct sensors_poll_device_t *dev, sensors_event_t* data, int |
| 218 | count);</pre> |
| 219 | <p>Returns an array of sensor data by filling the <code>data</code> argument. This function |
| 220 | must block until events are available. It will return the number of events read |
| 221 | on success, or a negative error number in case of an error.</p> |
| 222 | <p>The number of events returned in <code>data</code> must be less or equal to |
| 223 | the <code>count</code> argument. This function shall never return 0 (no event).</p> |
| 224 | <h2 id="sequence_of_calls">Sequence of calls</h2> |
| 225 | <p>When the device boots, <code>get_sensors_list</code> is called.</p> |
| 226 | <p>When a sensor gets activated, the <code>batch</code> function will be called with the |
| 227 | requested parameters, followed by <code>activate(..., enable=1)</code>.</p> |
| 228 | <p>Note that in HAL version 1_0, the order was the opposite: <code>activate</code> was called |
| 229 | first, followed by <code>set_delay</code>.</p> |
| 230 | <p>When the requested characteristics of a sensor are changing while it is |
| 231 | activated, the <code>batch</code> function is called.</p> |
| 232 | <p><code>flush</code> can be called at any time, even on non-activated sensors (in which case |
| 233 | it must return <code>-EINVAL</code>)</p> |
| 234 | <p>When a sensor gets deactivated, <code>activate(..., enable=0)</code> will be called.</p> |
| 235 | <p>In parallel to those calls, the <code>poll</code> function will be called repeatedly to |
| 236 | request data. <code>poll</code> can be called even when no sensors are activated.</p> |
| 237 | <h2 id="sensors_module_t">sensors_module_t</h2> |
| 238 | <p><code>sensors_module_t</code> is the type used to create the Android hardware module for the |
| 239 | sensors. The implementation of the HAL must define an object |
| 240 | <code>HAL_MODULE_INFO_SYM</code> of this type to expose the <a |
| 241 | href="#get_sensors_list_list">get_sensors_list</a> function. See the definition |
| 242 | of <code>sensors_module_t</code> in <a |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 243 | href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> and the |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 244 | definition of <code>hw_module_t</code> for more information.</p> |
| 245 | <h2 id="sensors_poll_device_t_sensors_poll_device_1_t">sensors_poll_device_t / sensors_poll_device_1_t</h2> |
| 246 | <p><code>sensors_poll_device_1_t</code> contains the rest of the methods defined above: |
| 247 | <code>activate</code>, <code>batch</code>, <code>flush</code> and |
| 248 | <code>poll</code>. Its <code>common</code> field (of type <a |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 249 | href="{@docRoot}devices/halref/structhw__device__t.html">hw_device_t</a>) |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 250 | defines the version number of the HAL.</p> |
| 251 | <h2 id="sensor_t">sensor_t</h2> |
| 252 | <p><code>sensor_t</code> represents an <a href="index.html">Android sensor</a>. Here are some of its important fields:</p> |
| 253 | <p><strong>name:</strong> A user-visible string that represents the sensor. This string often |
| 254 | contains the part name of the underlying sensor, the type of the sensor, and |
| 255 | whether it is a wake-up sensor. For example, “LIS2HH12 Accelerometer”, |
| 256 | “MAX21000 Uncalibrated Gyroscope”, “BMP280 Wake-up Barometer”, “MPU6515 Game |
| 257 | Rotation Vector”</p> |
| 258 | <p><strong>handle:</strong> The integer used to refer to the sensor when registering to it or |
| 259 | generating events from it.</p> |
| 260 | <p><strong>type:</strong> The type of the sensor. See the explanation of sensor |
| 261 | type in <a href="index.html">What are Android sensors?</a> for more details, and see <a |
| 262 | href="sensor-types.html">Sensor types</a> for official sensor types. For |
| 263 | non-official sensor types, <code>type</code> must start with <code>SENSOR_TYPE_DEVICE_PRIVATE_BASE</code></p> |
| 264 | <p><strong>stringType:</strong> The type of the sensor as a string. When the sensor has an official |
| 265 | type, set to <code>SENSOR_STRING_TYPE_*</code>. When the sensor has a manufacturer specific |
| 266 | type, <code>stringType</code> must start with the manufacturer reverse domain name. For |
| 267 | example, a sensor (say a unicorn detector) defined by the |
| 268 | <em>Cool-product</em> team at Fictional-Company could use |
| 269 | <code>stringType=”com.fictional_company.cool_product.unicorn_detector”</code>. |
| 270 | The <code>stringType</code> is used to uniquely identify non-official sensors types. See <a |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 271 | href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> for more |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 272 | information on types and string types.</p> |
| 273 | <p><strong>requiredPermission:</strong> A string representing the permission that applications must |
| 274 | possess to see the sensor, register to it and receive its data. An empty string |
| 275 | means applications do not require any permission to access this sensor. Some |
| 276 | sensor types like the <a href="sensor-types.html#heart_rate">heart rate |
| 277 | monitor</a> have a mandatory <code>requiredPermission</code>. All sensors |
| 278 | providing sensitive user information (such as the heart rate) must be protected by a permission.</p> |
| 279 | <p><strong>flags:</strong> Flags for this sensor, defining the sensor’s reporting mode and whether |
| 280 | the sensor is a wake-up sensor or not. For example, a one-shot wake-up sensor |
| 281 | will have <code>flags = SENSOR_FLAG_ONE_SHOT_MODE | SENSOR_FLAG_WAKE_UP</code>. The bits of |
| 282 | the flag that are not used in the current HAL version must be left equal to 0.</p> |
| 283 | <p><strong>maxRange:</strong> The maximum value the sensor can report, in the same unit as the |
| 284 | reported values. The sensor must be able to report values without saturating |
| 285 | within <code>[-maxRange; maxRange]</code>. Note that this means the total range of the |
| 286 | sensor in the generic sense is <code>2*maxRange</code>. When the sensor reports values over |
| 287 | several axes, the range applies to each axis. For example, a “+/- 2g” |
| 288 | accelerometer will report <code>maxRange = 2*9.81 = 2g</code>.</p> |
| 289 | <p><strong>resolution:</strong> The smallest difference in value that the sensor can measure. |
| 290 | Usually computed based on <code>maxRange</code> and the number of bits in the measurement.</p> |
| 291 | <p><strong>power:</strong> The power cost of enabling the sensor, in milliAmps. This is nearly |
| 292 | always more that the power consumption reported in the datasheet of the |
| 293 | underlying sensor. See <a |
| 294 | href="sensor-types.html#base_sensors_=_not_equal_to_physical_sensors">Base |
| 295 | sensors != physical sensors</a> for more details and see <a |
| 296 | href="power-use.html#power_measurement_process">Power measurement process</a> for details on |
| 297 | how to measure the power consumption of a sensor. If the |
| 298 | sensor’s power consumption depends on whether the device is moving, the power |
| 299 | consumption while moving is the one reported in the <code>power</code> field.</p> |
| 300 | <p><strong>minDelay:</strong> For continuous sensors, the sampling period, in microseconds, |
| 301 | corresponding to the fastest rate the sensor supports. See <a href="#sampling_period_ns">sampling_period_ns</a> for details on how this value is used. Beware that <code>minDelay</code> is expressed in |
| 302 | microseconds while <code>sampling_period_ns</code> is in nanoseconds. For on-change and |
| 303 | special reporting mode sensors, unless otherwise specified, <code>minDelay</code> must be 0. |
| 304 | For one-shot sensors, it must be -1.</p> |
| 305 | <p><strong>maxDelay:</strong> For continuous and on-change sensors, the sampling period, in |
| 306 | microseconds, corresponding to the slowest rate the sensor supports. See <a href="#sampling_period_ns">sampling_period_ns</a> for details on how this value is used. Beware that <code>maxDelay</code> is expressed in |
| 307 | microseconds while <code>sampling_period_ns</code> is in nanoseconds. For special and |
| 308 | one-shot sensors, <code>maxDelay</code> must be 0.</p> |
| 309 | <p><strong>fifoReservedEventCount:</strong> The number of events reserved for this sensor in the |
| 310 | hardware FIFO. If there is a dedicated FIFO for this sensor, then |
| 311 | <code>fifoReservedEventCount</code> is the size of this dedicated FIFO. If the FIFO is |
| 312 | shared with other sensors, <code>fifoReservedEventCount</code> is the size of the part of |
| 313 | the FIFO that is reserved for that sensor. On most shared-FIFO systems, and on |
| 314 | systems that do not have a hardware FIFO this value is 0.</p> |
| 315 | <p><strong>fifoMaxEventCount:</strong> The maximum number of events that could be stored in the |
| 316 | FIFOs for this sensor. This is always greater or equal to |
| 317 | <code>fifoReservedEventCount</code>. This value is used to estimate how quickly the FIFO |
| 318 | will get full when registering to the sensor at a specific rate, supposing no |
| 319 | other sensors are activated. On systems that do not have a hardware FIFO, |
| 320 | <code>fifoMaxEventCount</code> is 0. See <a href="batching.html">Batching</a> for more details.</p> |
| 321 | <p>For sensors with an official sensor type, some of the fields are overwritten by |
| 322 | the framework. For example, <a |
| 323 | href="sensor-types.html#accelerometer">accelerometer</a> sensors are forced to |
| 324 | have a continuous reporting mode, and <a |
| 325 | href="sensor-types.html#heart_rate">heart rate</a> monitors are forced to be |
| 326 | protected by the <code>SENSOR_PERMISSION_BODY_SENSORS</code> permission.</p> |
| 327 | <h2 id="sensors_event_t">sensors_event_t</h2> |
| 328 | <p>Sensor events generated by Android sensors and reported through the <a |
| 329 | href="#poll">poll</a> function are of <code>type sensors_event_t</code>. Here are some |
| 330 | important fields of <code>sensors_event_t</code>:</p> |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 331 | <p><strong>version:</strong> Must be <code>sizeof(struct sensors_event_t)</code></p> |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 332 | <p><strong>sensor:</strong> The handle of the sensor that generated the event, as defined by |
| 333 | <code>sensor_t.handle</code>.</p> |
| 334 | <p><strong>type:</strong> The sensor type of the sensor that generated the event, as defined by |
| 335 | <code>sensor_t.type</code>.</p> |
| 336 | <p><strong>timestamp:</strong> The timestamp of the event in nanoseconds. This is the time the |
| 337 | event happened (a step was taken, or an accelerometer measurement was made), |
| 338 | not the time the event was reported. <code>timestamp</code> must be synchronized with the |
| 339 | <code>elapsedRealtimeNano</code> clock, and in the case of continuous sensors, the jitter |
| 340 | must be small. Timestamp filtering is sometimes necessary to satisfy the CDD |
| 341 | requirements, as using only the SoC interrupt time to set the timestamps |
| 342 | causes too high jitter, and using only the sensor chip time to set the |
| 343 | timestamps can cause de-synchronization from the |
| 344 | <code>elapsedRealtimeNano</code> clock, as the sensor clock drifts.</p> |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 345 | <p><strong>data and overlapping fields:</strong> The values measured by the sensor. The meaning and |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 346 | units of those fields are specific to each sensor type. See <a |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 347 | href="{@docRoot}devices/halref/sensors_8h.html">sensors.h</a> and the |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 348 | definition of the different <a href="sensor-types.html">Sensor types</a> for a |
| 349 | description of the data fields. For some sensors, the accuracy of the |
| 350 | readings is also reported as part of the data, through a <code>status</code> field. This |
| 351 | field is only piped through for those select sensor types, appearing at the SDK |
| 352 | layer as an accuracy value. For those sensors, the fact that the status field |
| 353 | must be set is mentioned in their <a href="sensor-types.html">sensor type</a> definition.</p> |
| 354 | <h3 id="metadata_flush_complete_events">Metadata flush complete events</h3> |
| 355 | <p>Metadata events have the same type as normal sensor events: |
| 356 | <code>sensors_event_meta_data_t = sensors_event_t</code>. They are returned together with |
| 357 | other sensor events through poll. They possess the following fields:</p> |
Clay Murphy | 92c38f9 | 2014-10-30 18:19:30 -0700 | [diff] [blame] | 358 | <p><strong>version:</strong> Must be <code>META_DATA_VERSION</code></p> |
| 359 | <p><strong>type:</strong> Must be <code>SENSOR_TYPE_META_DATA</code></p> |
| 360 | <p><strong>sensor, reserved, and timestamp</strong>: Must be 0</p> |
| 361 | <p><strong>meta_data.what:</strong> Contains the metadata type for this event. There is currently a |
Clay Murphy | d01c551 | 2014-09-18 18:28:04 -0700 | [diff] [blame] | 362 | single valid metadata type: <code>META_DATA_FLUSH_COMPLETE</code>.</p> |
| 363 | <p><code>META_DATA_FLUSH_COMPLETE</code> events represent the completion of the flush of a |
| 364 | sensor FIFO. When <code>meta_data.what=META_DATA_FLUSH_COMPLETE</code>, <code>meta_data.sensor</code> |
| 365 | must be set to the handle of the sensor that has been flushed. They are |
| 366 | generated when and only when <code>flush</code> is called on a sensor. See the section on |
| 367 | the <a href="#flush_sensor">flush</a> function for more information.</p> |