diff options
Diffstat (limited to 'chre_api/legacy/v1_4/chre/sensor.h')
| -rw-r--r-- | chre_api/legacy/v1_4/chre/sensor.h | 1018 |
1 files changed, 0 insertions, 1018 deletions
diff --git a/chre_api/legacy/v1_4/chre/sensor.h b/chre_api/legacy/v1_4/chre/sensor.h deleted file mode 100644 index 88cfce8e..00000000 --- a/chre_api/legacy/v1_4/chre/sensor.h +++ /dev/null @@ -1,1018 +0,0 @@ -/* - * Copyright (C) 2016 The Android Open Source Project - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -#ifndef _CHRE_SENSOR_H_ -#define _CHRE_SENSOR_H_ - -/** - * @file - * API dealing with sensor interaction in the Context Hub Runtime - * Environment. - * - * This includes the definition of our sensor types and the ability to - * configure them for receiving events. - */ - -#include <stdbool.h> -#include <stdint.h> - -#include <chre/common.h> -#include <chre/event.h> -#include <chre/sensor_types.h> - -#ifdef __cplusplus -extern "C" { -#endif - - -/** - * Base value for all of the data events for sensors. - * - * The value for a data event FOO is - * CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_FOO - * - * This allows for easy mapping, and also explains why there are gaps - * in our values since we don't have all possible sensor types assigned. - */ -#define CHRE_EVENT_SENSOR_DATA_EVENT_BASE CHRE_EVENT_SENSOR_FIRST_EVENT - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x', 'y', and 'z' fields within - * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). - * - * All values are in SI units (m/s^2) and measure the acceleration applied to - * the device. - */ -#define CHRE_EVENT_SENSOR_ACCELEROMETER_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_ACCELEROMETER) - -/** - * nanoappHandleEvent argument: struct chreSensorOccurrenceData - * - * Since this is a one-shot sensor, after this event is delivered to the - * nanoapp, the sensor automatically goes into DONE mode. Sensors of this - * type must be configured with a ONE_SHOT mode. - */ -#define CHRE_EVENT_SENSOR_INSTANT_MOTION_DETECT_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_INSTANT_MOTION_DETECT) - -/** - * nanoappHandleEvent argument: struct chreSensorOccurrenceData - * - * Since this is a one-shot sensor, after this event is delivered to the - * nanoapp, the sensor automatically goes into DONE mode. Sensors of this - * type must be configured with a ONE_SHOT mode. - */ -#define CHRE_EVENT_SENSOR_STATIONARY_DETECT_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_STATIONARY_DETECT) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x', 'y', and 'z' fields within - * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). - * - * All values are in radians/second and measure the rate of rotation - * around the X, Y and Z axis. - */ -#define CHRE_EVENT_SENSOR_GYROSCOPE_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GYROSCOPE) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x', 'y', and 'z' fields within - * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). - * - * All values are in micro-Tesla (uT) and measure the geomagnetic - * field in the X, Y and Z axis. - */ -#define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD) - -/** - * nanoappHandleEvent argument: struct chreSensorFloatData - * - * The data can be interpreted using the 'pressure' field within 'readings'. - * This value is in hectopascals (hPa). - */ -#define CHRE_EVENT_SENSOR_PRESSURE_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_PRESSURE) - -/** - * nanoappHandleEvent argument: struct chreSensorFloatData - * - * The data can be interpreted using the 'light' field within 'readings'. - * This value is in SI lux units. - */ -#define CHRE_EVENT_SENSOR_LIGHT_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_LIGHT) - -/** - * nanoappHandleEvent argument: struct chreSensorByteData - * - * The data is interpreted from the following fields in 'readings': - * o 'isNear': If set to 1, we are nearby (on the order of centimeters); - * if set to 0, we are far. The meaning of near/far in this field must be - * consistent with the Android definition. - * o 'invalid': If set to 1, this is not a valid reading of this data. - * As of CHRE API v1.2, this field is deprecated and must always be set to - * 0. If an invalid reading is generated by the sensor hardware, it must - * be dropped and not delivered to any nanoapp. - * - * In prior versions of the CHRE API, there can be an invalid event generated - * upon configuring this sensor. Thus, the 'invalid' field must be checked on - * the first event before interpreting 'isNear'. - */ -#define CHRE_EVENT_SENSOR_PROXIMITY_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_PROXIMITY) - -/** - * nanoappHandleEvent argument: struct chreSensorOccurrenceData - * - * This data is generated every time a step is taken by the user. - * - * @since v1.3 - */ -#define CHRE_EVENT_SENSOR_STEP_DETECT_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_STEP_DETECT) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x', 'y', and 'z' fields within - * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). - * - * All values are in SI units (m/s^2) and measure the acceleration applied to - * the device. - */ -#define CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x', 'y', and 'z' fields within - * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). - * - * All values are in radians/second and measure the rate of rotation - * around the X, Y and Z axis. - */ -#define CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x', 'y', and 'z' fields within - * 'readings', or by the 3D array 'v' (v[0] == x; v[1] == y; v[2] == z). - * - * All values are in micro-Tesla (uT) and measure the geomagnetic - * field in the X, Y and Z axis. - */ -#define CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD) - -/** - * nanoappHandleEvent argument: struct chreSensorFloatData - * - * The data can be interpreted using the 'temperature' field within 'readings'. - * This value is in degrees Celsius. - */ -#define CHRE_EVENT_SENSOR_ACCELEROMETER_TEMPERATURE_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_ACCELEROMETER_TEMPERATURE) - -/** - * nanoappHandleEvent argument: struct chreSensorFloatData - * - * The data can be interpreted using the 'temperature' field within 'readings'. - * This value is in degrees Celsius. - */ -#define CHRE_EVENT_SENSOR_GYROSCOPE_TEMPERATURE_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GYROSCOPE_TEMPERATURE) - -/** - * nanoappHandleEvent argument: struct chreSensorFloatData - * - * The data can be interpreted using the 'temperature' field within 'readings'. - * This value is in degrees Celsius. - */ -#define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_TEMPERATURE_DATA \ - (CHRE_EVENT_SENSOR_DATA_EVENT_BASE + CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD_TEMPERATURE) - -/** - * First value for sensor events which are not data from the sensor. - * - * Unlike the data event values, these other event values don't have any - * mapping to sensor types. - */ -#define CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE \ - (CHRE_EVENT_SENSOR_FIRST_EVENT + 0x0100) - -/** - * nanoappHandleEvent argument: struct chreSensorSamplingStatusEvent - * - * Indicates that the interval and/or the latency which this sensor is - * sampling at has changed. - */ -#define CHRE_EVENT_SENSOR_SAMPLING_CHANGE \ - (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 0) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias' - * field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias; - * bias[1] == y_bias; bias[2] == z_bias). Bias is subtracted from uncalibrated - * data to generate calibrated data. - * - * All values are in radians/second and measure the rate of rotation - * around the X, Y and Z axis. - * - * If bias delivery is supported, this event is generated by default when - * chreSensorConfigure is called to enable for the sensor of type - * CHRE_SENSOR_TYPE_GYROSCOPE, or if bias delivery is explicitly enabled - * through chreSensorConfigureBiasEvents() for the sensor. - */ -#define CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO \ - (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 1) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias' - * field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias; - * bias[1] == y_bias; bias[2] == z_bias). Bias is subtracted from uncalibrated - * data to generate calibrated data. - * - * All values are in micro-Tesla (uT) and measure the geomagnetic - * field in the X, Y and Z axis. - * - * If bias delivery is supported, this event is generated by default when - * chreSensorConfigure is called to enable for the sensor of type - * CHRE_SENSOR_TYPE_GEOMAGNETIC_FIELD, or if bias delivery is explicitly enabled - * through chreSensorConfigureBiasEvents() for the sensor. - */ -#define CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO \ - (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 2) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data can be interpreted using the 'x_bias', 'y_bias', and 'z_bias' - * field within 'readings', or by the 3D array 'bias' (bias[0] == x_bias; - * bias[1] == y_bias; bias[2] == z_bias). Bias is subtracted from uncalibrated - * data to generate calibrated data. - * - * All values are in SI units (m/s^2) and measure the acceleration applied to - * the device. - * - * If bias delivery is supported, this event is generated by default when - * chreSensorConfigure is called to enable for the sensor of type - * CHRE_SENSOR_TYPE_ACCELEROMETER, or if bias delivery is explicitly enabled - * through chreSensorConfigureBiasEvents() for the sensor. - * - * @since v1.3 - */ -#define CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO \ - (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 3) - -/** - * nanoappHandleEvent argument: struct chreSensorFlushCompleteEvent - * - * An event indicating that a flush request made by chreSensorFlushAsync has - * completed. - * - * @see chreSensorFlushAsync - * - * @since v1.3 - */ -#define CHRE_EVENT_SENSOR_FLUSH_COMPLETE \ - (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 4) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data of this event is the same as that of - * CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO, except the sensorHandle field of - * chreSensorDataHeader contains the handle of the sensor of type - * CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE. - * - * This event is only generated if the bias reporting is explicitly enabled - * for a nanoapp through chreSensorConfigureBiasEvents() for the sensor of type - * CHRE_SENSOR_TYPE_UNCALIBRATED_GYROSCOPE. - * - * @see CHRE_EVENT_SENSOR_GYROSCOPE_BIAS_INFO - * - * @since v1.3 - */ -#define CHRE_EVENT_SENSOR_UNCALIBRATED_GYROSCOPE_BIAS_INFO \ - (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 5) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data of this event is the same as that of - * CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO, except the sensorHandle field - * of chreSensorDataHeader contains the handle of the sensor of type - * CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD. - * - * This event is only generated if the bias reporting is explicitly enabled - * for a nanoapp through chreSensorConfigureBiasEvents() for the sensor of type - * CHRE_SENSOR_TYPE_UNCALIBRATED_GEOMAGNETIC_FIELD. - * - * @see CHRE_EVENT_SENSOR_GEOMAGNETIC_FIELD_BIAS_INFO - * - * @since v1.3 - */ -#define CHRE_EVENT_SENSOR_UNCALIBRATED_GEOMAGNETIC_FIELD_BIAS_INFO \ - (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 6) - -/** - * nanoappHandleEvent argument: struct chreSensorThreeAxisData - * - * The data of this event is the same as that of - * CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO, except the sensorHandle field - * of chreSensorDataHeader contains the handle of the sensor of type - * CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER. - * - * This event is only generated if the bias reporting is explicitly enabled - * for a nanoapp through chreSensorConfigureBiasEvents for the sensor of type - * CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER. - * - * @see CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO - * - * @since v1.3 - */ -#define CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_BIAS_INFO \ - (CHRE_EVENT_SENSOR_OTHER_EVENTS_BASE + 7) - -#if CHRE_EVENT_SENSOR_UNCALIBRATED_ACCELEROMETER_BIAS_INFO > \ - CHRE_EVENT_SENSOR_LAST_EVENT -#error Too many sensor events. -#endif - -/** - * Value indicating we want the smallest possible latency for a sensor. - * - * This literally translates to 0 nanoseconds for the chreSensorConfigure() - * argument. While we won't get exactly 0 nanoseconds, the CHRE will - * queue up this event As Soon As Possible. - */ -#define CHRE_SENSOR_LATENCY_ASAP UINT64_C(0) - -/** - * Special value indicating non-importance, or non-applicability of the sampling - * interval. - * - * @see chreSensorConfigure - * @see chreSensorSamplingStatus - */ -#define CHRE_SENSOR_INTERVAL_DEFAULT UINT64_C(-1) - -/** - * Special value indicating non-importance of the latency. - * - * @see chreSensorConfigure - * @see chreSensorSamplingStatus - */ -#define CHRE_SENSOR_LATENCY_DEFAULT UINT64_C(-1) - -/** - * Special value indicating non-importance of the batch interval. - * - * @see chreSensorConfigureWithBatchInterval - */ -#define CHRE_SENSOR_BATCH_INTERVAL_DEFAULT UINT64_C(-1) - -// This is used to define elements of enum chreSensorConfigureMode. -#define CHRE_SENSOR_CONFIGURE_RAW_POWER_ON (1 << 0) - -// This is used to define elements of enum chreSensorConfigureMode. -#define CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS (1 << 1) - -// This is used to define elements of enum chreSensorConfigureMode. -#define CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT (2 << 1) - -/** - * The maximum amount of time allowed to elapse between the call to - * chreSensorFlushAsync() and when CHRE_EVENT_SENSOR_FLUSH_COMPLETE is delivered - * to the nanoapp on a successful flush. - */ -#define CHRE_SENSOR_FLUSH_COMPLETE_TIMEOUT_NS (5 * CHRE_NSEC_PER_SEC) - -/** - * Modes we can configure a sensor to use. - * - * Our mode will affect not only how/if we receive events, but - * also whether or not the sensor will be powered on our behalf. - * - * @see chreSensorConfigure - */ -enum chreSensorConfigureMode { - /** - * Get events from the sensor. - * - * Power: Turn on if not already on. - * Reporting: Continuous. Send each new event as it comes (subject to - * batching and latency). - */ - CHRE_SENSOR_CONFIGURE_MODE_CONTINUOUS = - (CHRE_SENSOR_CONFIGURE_RAW_POWER_ON | - CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS), - - /** - * Get a single event from the sensor and then become DONE. - * - * Once the event is sent, the sensor automatically - * changes to CHRE_SENSOR_CONFIGURE_MODE_DONE mode. - * - * Power: Turn on if not already on. - * Reporting: One shot. Send the next event and then be DONE. - */ - CHRE_SENSOR_CONFIGURE_MODE_ONE_SHOT = - (CHRE_SENSOR_CONFIGURE_RAW_POWER_ON | - CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT), - - /** - * Get events from a sensor that are generated for any client in the system. - * - * This is considered passive because the sensor will not be powered on for - * the sake of our nanoapp. If and only if another client in the system has - * requested this sensor power on will we get events. - * - * This can be useful for something which is interested in seeing data, but - * not interested enough to be responsible for powering on the sensor. - * - * Power: Do not power the sensor on our behalf. - * Reporting: Continuous. Send each event as it comes. - */ - CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_CONTINUOUS = - CHRE_SENSOR_CONFIGURE_RAW_REPORT_CONTINUOUS, - - /** - * Get a single event from a sensor that is generated for any client in the - * system. - * - * See CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_CONTINUOUS for more details on - * what the "passive" means. - * - * Power: Do not power the sensor on our behalf. - * Reporting: One shot. Send only the next event and then be DONE. - */ - CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_ONE_SHOT = - CHRE_SENSOR_CONFIGURE_RAW_REPORT_ONE_SHOT, - - /** - * Indicate we are done using this sensor and no longer interested in it. - * - * See chreSensorConfigure for more details on expressing interest or - * lack of interest in a sensor. - * - * Power: Do not power the sensor on our behalf. - * Reporting: None. - */ - CHRE_SENSOR_CONFIGURE_MODE_DONE = 0, -}; - -/** - * A structure containing information about a Sensor. - * - * See documentation of individual fields below. - */ -struct chreSensorInfo { - /** - * The name of the sensor. - * - * A text name, useful for logging/debugging, describing the Sensor. This - * is not assured to be unique (i.e. there could be multiple sensors with - * the name "Temperature"). - * - * CHRE implementations may not set this as NULL. An empty - * string, while discouraged, is legal. - */ - const char *sensorName; - - /** - * One of the CHRE_SENSOR_TYPE_* defines above. - */ - uint8_t sensorType; - - /** - * Flag indicating if this sensor is on-change. - * - * An on-change sensor only generates events when underlying state - * changes. This has the same meaning as on-change does in the Android - * Sensors HAL. See sensors.h for much more details. - * - * A value of 1 indicates this is on-change. 0 indicates this is not - * on-change. - */ - uint8_t isOnChange : 1; - - /** - * Flag indicating if this sensor is one-shot. - * - * A one-shot sensor only triggers a single event, and then automatically - * disables itself. - * - * A value of 1 indicates this is one-shot. 0 indicates this is not - * on-change. - */ - uint8_t isOneShot : 1; - - /** - * Flag indicating if this sensor supports reporting bias info events. - * - * This field will be set to 0 when running on CHRE API versions prior to - * v1.3, but must be ignored (i.e. does not mean bias info event is not - * supported). - * - * @see chreSensorConfigureBiasEvents - * - * @since v1.3 - */ - uint8_t reportsBiasEvents : 1; - - /** - * Flag indicating if this sensor supports passive mode requests. - * - * This field will be set to 0 when running on CHRE API versions prior to - * v1.4, and must be ignored (i.e. does not mean passive mode requests are - * not supported). - * - * @see chreSensorConfigure - * - * @since v1.4 - */ - uint8_t supportsPassiveMode : 1; - - uint8_t unusedFlags : 4; - - /** - * The minimum sampling interval supported by this sensor, in nanoseconds. - * - * Requests to chreSensorConfigure with a lower interval than this will - * fail. If the sampling interval is not applicable to this sensor, this - * will be set to CHRE_SENSOR_INTERVAL_DEFAULT. - * - * This field will be set to 0 when running on CHRE API versions prior to - * v1.1, indicating that the minimum interval is not known. - * - * @since v1.1 - */ - uint64_t minInterval; -}; - -/** - * The status of a sensor's sampling configuration. - */ -struct chreSensorSamplingStatus { - /** - * The interval, in nanoseconds, at which the sensor is now sampling. - * - * If this is CHRE_SENSOR_INTERVAL_DEFAULT, then a sampling interval - * isn't meaningful for this sensor. - * - * Note that if 'enabled' is false, this value is not meaningful. - */ - uint64_t interval; - - /** - * The latency, in nanoseconds, at which the senor is now reporting. - * - * If this is CHRE_SENSOR_LATENCY_DEFAULT, then a latency - * isn't meaningful for this sensor. - * - * The effective batch interval can be derived from this value by - * adding the current sampling interval. - * - * Note that if 'enabled' is false, this value is not meaningful. - */ - uint64_t latency; - - /** - * True if the sensor is actively powered and sampling; false otherwise. - */ - bool enabled; -}; - -/** - * The nanoappHandleEvent argument for CHRE_EVENT_SENSOR_SAMPLING_CHANGE. - * - * Note that only at least one of 'interval' or 'latency' must be - * different than it was prior to this event. Thus, one of these - * fields may be (but doesn't need to be) the same as before. - */ -struct chreSensorSamplingStatusEvent { - /** - * The handle of the sensor which has experienced a change in sampling. - */ - uint32_t sensorHandle; - - /** - * The new sampling status. - * - * At least one of the field in this struct will be different from - * the previous sampling status event. - */ - struct chreSensorSamplingStatus status; -}; - -/** - * The nanoappHandleEvent argument for CHRE_EVENT_SENSOR_FLUSH_COMPLETE. - * - * @see chreSensorFlushAsync - * - * @since v1.3 - */ -struct chreSensorFlushCompleteEvent { - /** - * The handle of the sensor which a flush was completed. - */ - uint32_t sensorHandle; - - /** - * Populated with a value from enum {@link #chreError}, indicating whether - * the flush failed, and if so, provides the cause of the failure. - */ - uint8_t errorCode; - - /** - * Reserved for future use. Set to 0. - */ - uint8_t reserved[3]; - - /** - * Set to the cookie parameter given to chreSensorFlushAsync. - */ - const void *cookie; -}; - -/** - * Find the default sensor for a given sensor type. - * - * @param sensorType One of the CHRE_SENSOR_TYPE_* constants. - * @param handle If a sensor is found, then the memory will be filled with - * the value for the sensor's handle. This argument must be non-NULL. - * @return true if a sensor was found, false otherwise. - */ -bool chreSensorFindDefault(uint8_t sensorType, uint32_t *handle); - -/** - * Get the chreSensorInfo struct for a given sensor. - * - * @param sensorHandle The sensor handle, as obtained from - * chreSensorFindDefault() or passed to nanoappHandleEvent(). - * @param info If the sensor is valid, then this memory will be filled with - * the SensorInfo contents for this sensor. This argument must be - * non-NULL. - * @return true if the senor handle is valid and 'info' was filled in; - * false otherwise. - */ -bool chreGetSensorInfo(uint32_t sensorHandle, struct chreSensorInfo *info); - -/** - * Get the chreSensorSamplingStatus struct for a given sensor. - * - * Note that this may be different from what was requested in - * chreSensorConfigure(), for multiple reasons. It's possible that the sensor - * does not exactly support the interval requested in chreSensorConfigure(), so - * a faster one was chosen. - * - * It's also possible that there is another user of this sensor who has - * requested a faster interval and/or lower latency. This latter scenario - * should be noted, because it means the sensor rate can change due to no - * interaction from this nanoapp. Note that the - * CHRE_EVENT_SENSOR_SAMPLING_CHANGE event will trigger in this case, so it's - * not necessary to poll for such a change. - * - * @param sensorHandle The sensor handle, as obtained from - * chreSensorFindDefault() or passed to nanoappHandleEvent(). - * @param status If the sensor is valid, then this memory will be filled with - * the sampling status contents for this sensor. This argument must be - * non-NULL. - * @return true if the senor handle is valid and 'status' was filled in; - * false otherwise. - */ -bool chreGetSensorSamplingStatus(uint32_t sensorHandle, - struct chreSensorSamplingStatus *status); - -/** - * Configures a given sensor at a specific interval and latency and mode. - * - * If this sensor's chreSensorInfo has isOneShot set to 1, - * then the mode must be one of the ONE_SHOT modes, or this method will fail. - * - * The CHRE wants to power as few sensors as possible, in keeping with its - * low power design. As such, it only turns on sensors when there are clients - * actively interested in that sensor data, and turns off sensors as soon as - * there are no clients interested in them. Calling this method generally - * indicates an interest, and using CHRE_SENSOR_CONFIGURE_MODE_DONE shows - * when we are no longer interested. - * - * Thus, each initial Configure of a sensor (per nanoapp) needs to eventually - * have a DONE call made, either directly or on its behalf. Subsequent calls - * to a Configure method within the same nanoapp, when there has been no DONE - * in between, still only require a single DONE call. - * - * For example, the following is valid usage: - * <code> - * chreSensorConfigure(myHandle, mode, interval0, latency0); - * [...] - * chreSensorConfigure(myHandle, mode, interval1, latency0); - * [...] - * chreSensorConfigure(myHandle, mode, interval1, latency1); - * [...] - * chreSensorConfigureModeOnly(myHandle, CHRE_SENSOR_CONFIGURE_MODE_DONE); - * </code> - * - * The first call to Configure is the one which creates the requirement - * to eventually call with DONE. The subsequent calls are just changing the - * interval/latency. They have not changed the fact that this nanoapp is - * still interested in output from the sensor 'myHandle'. Thus, only one - * single call for DONE is needed. - * - * There is a special case. One-shot sensors, sensors which - * just trigger a single event and never trigger again, implicitly go into - * DONE mode after that single event triggers. Thus, the - * following are legitimate usages: - * <code> - * chreSensorConfigure(myHandle, MODE_ONE_SHOT, interval, latency); - * [...] - * [myHandle triggers an event] - * [no need to configure to DONE]. - * </code> - * - * And: - * <code> - * chreSensorConfigure(myHandle, MODE_ONE_SHOT, interval, latency); - * [...] - * chreSensorConfigureModeOnly(myHandle, MODE_DONE); - * [we cancelled myHandle before it ever triggered an event] - * </code> - * - * Note that while PASSIVE modes, by definition, don't express an interest in - * powering the sensor, DONE is still necessary to silence the event reporting. - * Starting with CHRE API v1.4, for sensors that do not support passive mode, a - * request with mode set to CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_CONTINUOUS or - * CHRE_SENSOR_CONFIGURE_MODE_PASSIVE_ONE_SHOT will be rejected. CHRE API - * versions 1.3 and older implicitly assume that passive mode is supported - * across all sensors, however this is not necessarily the case. Clients can - * call chreSensorInfo to identify whether a sensor supports passive mode. - * - * When a calibrated sensor (e.g. CHRE_SENSOR_TYPE_ACCELEROMETER) is - * successfully enabled through this method and if bias delivery is supported, - * by default CHRE will start delivering bias events for the sensor - * (e.g. CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO) to the nanoapp. If the - * nanoapp does not wish to receive these events, they can be disabled through - * chreSensorConfigureBiasEvents after enabling the sensor. - * - * @param sensorHandle The handle to the sensor, as obtained from - * chreSensorFindDefault(). - * @param mode The mode to use. See descriptions within the - * chreSensorConfigureMode enum. - * @param interval The interval, in nanoseconds, at which we want events from - * the sensor. On success, the sensor will be set to 'interval', or a value - * less than 'interval'. There is a special value - * CHRE_SENSOR_INTERVAL_DEFAULT, in which we don't express a preference for - * the interval, and allow the sensor to choose what it wants. Note that - * due to batching, we may receive events less frequently than - * 'interval'. - * @param latency The maximum latency, in nanoseconds, allowed before the - * CHRE begins delivery of an event. This will control how many events - * can be queued by the sensor before requiring a delivery event. - * Latency is defined as the "timestamp when event is queued by the CHRE" - * minus "timestamp of oldest unsent data reading". - * There is a special value CHRE_SENSOR_LATENCY_DEFAULT, in which we don't - * express a preference for the latency, and allow the sensor to choose what - * it wants. - * Note that there is no assurance of how long it will take an event to - * get through a CHRE's queueing system, and thus there is no ability to - * request a minimum time from the occurrence of a phenomenon to when the - * nanoapp receives the information. The current CHRE API has no - * real-time elements, although future versions may introduce some to - * help with this issue. - * @return true if the configuration succeeded, false otherwise. - * - * @see chreSensorConfigureMode - * @see chreSensorFindDefault - * @see chreSensorInfo - * @see chreSensorConfigureBiasEvents - */ -bool chreSensorConfigure(uint32_t sensorHandle, - enum chreSensorConfigureMode mode, - uint64_t interval, uint64_t latency); - -/** - * Short cut for chreSensorConfigure where we only want to configure the mode - * and do not care about interval/latency. - * - * @see chreSensorConfigure - */ -static inline bool chreSensorConfigureModeOnly( - uint32_t sensorHandle, enum chreSensorConfigureMode mode) { - return chreSensorConfigure(sensorHandle, - mode, - CHRE_SENSOR_INTERVAL_DEFAULT, - CHRE_SENSOR_LATENCY_DEFAULT); -} - -/** - * Convenience function that wraps chreSensorConfigure but enables batching to - * be controlled by specifying the desired maximum batch interval rather - * than maximum sample latency. Users may find the batch interval to be a more - * intuitive method of expressing the desired batching behavior. - * - * Batch interval is different from latency as the batch interval time is - * counted starting when the prior event containing a batch of sensor samples is - * delivered, while latency starts counting when the first sample is deferred to - * start collecting a batch. In other words, latency ignores the time between - * the last sample in a batch to the first sample of the next batch, while it's - * included in the batch interval, as illustrated below. - * - * Time 0 1 2 3 4 5 6 7 8 - * Batch A B C - * Sample a1 a2 a3 b1 b2 b3 c1 c2 c3 - * Latency [ ] [ ] [ ] - * BatchInt | | | - * - * In the diagram, the effective sample interval is 1 time unit, latency is 2 - * time units, and batch interval is 3 time units. - * - * @param sensorHandle See chreSensorConfigure#sensorHandle - * @param mode See chreSensorConfigure#mode - * @param sampleInterval See chreSensorConfigure#interval, but note that - * CHRE_SENSOR_INTERVAL_DEFAULT is not a supported input to this method. - * @param batchInterval The desired maximum interval, in nanoseconds, between - * CHRE enqueuing each batch of sensor samples. - * @return Same as chreSensorConfigure - * - * @see chreSensorConfigure - * - * @since v1.1 - */ -static inline bool chreSensorConfigureWithBatchInterval( - uint32_t sensorHandle, enum chreSensorConfigureMode mode, - uint64_t sampleInterval, uint64_t batchInterval) { - bool result = false; - - if (sampleInterval != CHRE_SENSOR_INTERVAL_DEFAULT) { - uint64_t latency; - if (batchInterval == CHRE_SENSOR_BATCH_INTERVAL_DEFAULT) { - latency = CHRE_SENSOR_LATENCY_DEFAULT; - } else if (batchInterval > sampleInterval) { - latency = batchInterval - sampleInterval; - } else { - latency = CHRE_SENSOR_LATENCY_ASAP; - } - result = chreSensorConfigure(sensorHandle, mode, sampleInterval, - latency); - } - - return result; -} - -/** - * Configures the reception of bias events for a specific sensor. - * - * If bias event delivery is supported for a sensor, the sensor's chreSensorInfo - * has reportsBiasEvents set to 1. If supported, it must be supported for both - * calibrated and uncalibrated versions of the sensor. If supported, CHRE must - * provide bias events to the nanoapp by default when chreSensorConfigure is - * called to enable the calibrated version of the sensor (for backwards - * compatibility reasons, as this is the defined behavior for CHRE API v1.0). - * When configuring uncalibrated sensors, nanoapps must explicitly configure an - * enable request through this method to receive bias events. If bias event - * delivery is not supported for the sensor, this method will return false and - * no bias events will be generated. - * - * To enable bias event delivery (enable=true), the nanoapp must be registered - * to the sensor through chreSensorConfigure, and bias events will only be - * generated when the sensor is powered on. To disable the bias event delivery, - * this method can be invoked with enable=false. - * - * If an enable configuration is successful, the calling nanoapp will receive - * bias info events, e.g. CHRE_EVENT_SENSOR_ACCELEROMETER_BIAS_INFO, when the - * bias status changes (or first becomes available). Calibrated data - * (e.g. CHRE_SENSOR_TYPE_ACCELEROMETER) is generated by subracting bias from - * uncalibrated data (e.g. CHRE_SENSOR_TYPE_UNCALIBRATED_ACCELEROMETER). - * Calibrated sensor events are generated by applying the most recent bias - * available (i.e. timestamp of calibrated data are greater than or equal to the - * timestamp of the bias data that has been applied to it). The configuration of - * bias event delivery persists until the sensor is unregistered by the nanoapp - * through chreSensorConfigure or modified through this method. - * - * To get an initial bias before new bias events, the nanoapp should get the - * bias synchronously after this method is invoked, e.g.: - * - * if (chreSensorConfigure(handle, ...)) { - * chreSensorConfigureBiasEvents(handle, true); - * chreSensorGetThreeAxisBias(handle, &bias); - * } - * - * Note that chreSensorGetThreeAxisBias() should be called after - * chreSensorConfigureBiasEvents() to ensure that no bias events are lost. - * - * If called while running on a CHRE API version below v1.3, this function - * returns false and has no effect. The default behavior regarding bias events - * is unchanged, meaning that the implementation may still send bias events - * when a calibrated sensor is registered (if supported), and will not send bias - * events when an uncalibrated sensor is registered. - * - * @param sensorHandle The handle to the sensor, as obtained from - * chreSensorFindDefault(). - * @param enable true to receive bias events, false otherwise - * - * @return true if the configuration succeeded, false otherwise - * - * @since v1.3 - */ -bool chreSensorConfigureBiasEvents(uint32_t sensorHandle, bool enable); - -/** - * Synchronously provides the most recent bias info available for a sensor. The - * bias will only be provided for a sensor that supports bias event delivery - * using the chreSensorThreeAxisData type. If the bias is not yet available - * (but is supported), this method will store data with a bias of 0 and the - * accuracy field in chreSensorDataHeader set to CHRE_SENSOR_ACCURACY_UNKNOWN. - * - * If called while running on a CHRE API version below v1.3, this function - * returns false. - * - * @param sensorHandle The handle to the sensor, as obtained from - * chreSensorFindDefault(). - * @param bias A pointer to where the bias will be stored. - * - * @return true if the bias was successfully stored, false if sensorHandle was - * invalid or the sensor does not support three axis bias delivery - * - * @since v1.3 - * - * @see chreSensorConfigureBiasEvents - */ -bool chreSensorGetThreeAxisBias(uint32_t sensorHandle, - struct chreSensorThreeAxisData *bias); - -/** - * Makes a request to flush all samples stored for batching. The nanoapp must be - * registered to the sensor through chreSensorConfigure, and the sensor must be - * powered on. If the request is accepted, all batched samples of the sensor - * are sent to nanoapps registered to the sensor. During a flush, it is treated - * as though the latency as given in chreSensorConfigure has expired. When all - * batched samples have been flushed (or the flush fails), the nanoapp will - * receive a unicast CHRE_EVENT_SENSOR_FLUSH_COMPLETE event. The time to deliver - * this event must not exceed CHRE_SENSOR_FLUSH_COMPLETE_TIMEOUT_NS after this - * method is invoked. If there are no samples in the batch buffer (either in - * hardware FIFO or software), then this method will return true and a - * CHRE_EVENT_SENSOR_FLUSH_COMPLETE event is delivered immediately. - * - * If a flush request is invalid (e.g. the sensor refers to a one-shot sensor, - * or the sensor was not enabled), and this API will return false and no - * CHRE_EVENT_SENSOR_FLUSH_COMPLETE event will be delivered. - * - * If multiple flush requests are made for a sensor prior to flush completion, - * then the requesting nanoapp will receive all batched samples existing at the - * time of the latest flush request. In this case, the number of - * CHRE_EVENT_SENSOR_FLUSH_COMPLETE events received must equal the number of - * flush requests made. - * - * If a sensor request is disabled after a flush request is made through this - * method but before the flush operation is completed, the nanoapp will receive - * a CHRE_EVENT_SENSOR_FLUSH_COMPLETE with the error code - * CHRE_ERROR_FUNCTION_DISABLED for any pending flush requests. - * - * Starting with CHRE API v1.3, implementations must support this capability - * across all exposed sensor types. - * - * @param sensorHandle The handle to the sensor, as obtained from - * chreSensorFindDefault(). - * @param cookie An opaque value that will be included in the - * chreSensorFlushCompleteEvent sent in relation to this request. - * - * @return true if the request was accepted for processing, false otherwise - * - * @since v1.3 - */ -bool chreSensorFlushAsync(uint32_t sensorHandle, const void *cookie); - -#ifdef __cplusplus -} -#endif - -#endif /* _CHRE_SENSOR_H_ */ |