1 /*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef CHRE_CORE_SENSOR_TYPE_H_
18 #define CHRE_CORE_SENSOR_TYPE_H_
19
20 #include <cstdint>
21
22 #include "chre_api/chre/sensor.h"
23
24 namespace chre {
25
26 //! The union of possible CHRE sensor data event type with one sample.
27 union ChreSensorData {
28 struct chreSensorThreeAxisData threeAxisData;
29 struct chreSensorOccurrenceData occurrenceData;
30 struct chreSensorFloatData floatData;
31 struct chreSensorByteData byteData;
32 };
33
34 /**
35 * This SensorType is designed to wrap constants provided by the CHRE API
36 * to improve type-safety. In addition, an unknown sensor type is provided
37 * for dealing with sensors that are not defined as per the CHRE API
38 * specification. The details of these sensors are left to the CHRE API
39 * sensor definitions.
40 */
41 enum class SensorType : uint8_t {
42 Unknown,
43 Accelerometer,
44 InstantMotion,
45 StationaryDetect,
46 Gyroscope,
47 GeomagneticField,
48 Pressure,
49 Light,
50 Proximity,
51 StepDetect,
52 AccelerometerTemperature,
53 GyroscopeTemperature,
54 GeomagneticFieldTemperature,
55 UncalibratedAccelerometer,
56 UncalibratedGyroscope,
57 UncalibratedGeomagneticField,
58
59 VendorType0,
60 VendorType1,
61 VendorType2,
62 VendorType3,
63 VendorType4,
64 VendorType5,
65 VendorType6,
66 VendorType7,
67 VendorType8,
68
69 // Note to future developers: don't forget to update the implementation of
70 // 1) getSensorTypeName,
71 // 2) getSensorTypeFromUnsignedInt,
72 // 3) getUnsignedIntFromSensorType,
73 // 4) getSensorSampleTypeFromSensorType
74 // 5) sensorTypeIsOneShot
75 // 6) sensorTypeIsOnChange
76 // when adding or removing a new entry here :)
77 // Have a nice day.
78
79 //! The number of sensor types including unknown. This entry must be last.
80 SENSOR_TYPE_COUNT,
81 };
82
83 /**
84 * This SensorSampleType is designed to help classify SensorType's data type in
85 * event handling.
86 */
87 enum class SensorSampleType {
88 Byte,
89 Float,
90 Occurrence,
91 ThreeAxis,
92 Vendor0,
93 Vendor1,
94 Vendor2,
95 Vendor3,
96 Vendor4,
97 Vendor5,
98 Vendor6,
99 Vendor7,
100 Vendor8,
101 Unknown,
102 };
103
104 /**
105 * Returns a string representation of the given sensor type.
106 *
107 * @param sensorType The sensor type to obtain a string for.
108 * @return A string representation of the sensor type.
109 */
110 const char *getSensorTypeName(SensorType sensorType);
111
112 /**
113 * Returns a sensor sample event type for a given sensor type. The sensor type
114 * must not be SensorType::Unknown. This is a fatal error.
115 *
116 * @param sensorType The type of the sensor.
117 * @return The event type for a sensor sample of the given sensor type.
118 */
119 uint16_t getSampleEventTypeForSensorType(SensorType sensorType);
120
121 /**
122 * Returns a sensor type for a given sensor sample event type.
123 *
124 * @param eventType The event type for a sensor sample.
125 * @return The type of the sensor.
126 */
127 SensorType getSensorTypeForSampleEventType(uint16_t eventType);
128
129 /**
130 * @return An index into an array for a given sensor type. This is useful to map
131 * sensor type to array index quickly. The range returned corresponds to any
132 * SensorType except for Unknown starting from zero to the maximum value sensor
133 * with no gaps.
134 */
getSensorTypeArrayIndex(SensorType sensorType)135 constexpr size_t getSensorTypeArrayIndex(SensorType sensorType) {
136 return static_cast<size_t>(sensorType) - 1;
137 }
138
139 /**
140 * @return The number of valid sensor types in the SensorType enum.
141 */
getSensorTypeCount()142 constexpr size_t getSensorTypeCount() {
143 // The number of valid entries in the SensorType enum (not including Unknown).
144 return static_cast<size_t>(SensorType::SENSOR_TYPE_COUNT) - 1;
145 }
146
147 /**
148 * Translates an unsigned integer as provided by a CHRE-compliant nanoapp to a
149 * SensorType. If the integer sensor type does not match one of the internal
150 * sensor types, SensorType::Unknown is returned.
151 *
152 * @param sensorType The integer sensor type.
153 * @return The strongly-typed sensor if a match is found or SensorType::Unknown.
154 */
155 SensorType getSensorTypeFromUnsignedInt(uint8_t sensorType);
156
157 /**
158 * Translates a SensorType to an unsigned integer as provided by CHRE API. If
159 * the sensor type is SensorType::Unknown, 0 is returned.
160 *
161 * @param sensorType The strongly-typed sensor.
162 * @return The integer sensor type if sensorType is not SensorType::Unknown.
163 */
164 uint8_t getUnsignedIntFromSensorType(SensorType sensorType);
165
166 /**
167 * Provides a stable handle for a CHRE sensor type. This handle is exposed to
168 * CHRE nanoapps as a way to refer to sensors that they are subscribing to. This
169 * API is not expected to be called with SensorType::Unknown as nanoapps are not
170 * able to subscribe to the Unknown sensor type.
171 *
172 * @param sensorType The type of the sensor to obtain a handle for.
173 * @return The handle for a given sensor.
174 */
getSensorHandleFromSensorType(SensorType sensorType)175 constexpr uint32_t getSensorHandleFromSensorType(SensorType sensorType) {
176 return static_cast<uint32_t>(sensorType);
177 }
178
179 /**
180 * Maps a sensor handle to a SensorType or returns SensorType::Unknown if the
181 * provided handle is invalid.
182 *
183 * @param handle The sensor handle for a sensor.
184 * @return The sensor type for a given handle.
185 */
getSensorTypeFromSensorHandle(uint32_t handle)186 constexpr SensorType getSensorTypeFromSensorHandle(uint32_t handle) {
187 return (handle > static_cast<uint32_t>(SensorType::Unknown)
188 && handle < static_cast<uint32_t>(SensorType::SENSOR_TYPE_COUNT))
189 ? static_cast<SensorType>(handle) : SensorType::Unknown;
190 }
191
192 /**
193 * Obtains the temperature sensor type of the specified sensor type.
194 *
195 * @param sensorType The sensor type to obtain its temperature sensor type for.
196 * @return The temperature sensor type or SensorType::Unknown if not supported
197 * by CHRE.
198 */
199 SensorType getTempSensorType(SensorType sensorType);
200
201 /**
202 * Maps a sensorType to its SensorSampleType.
203 *
204 * @param sensorType The type of the sensor to obtain its SensorSampleType for.
205 * @return The SensorSampleType of the sensorType.
206 */
207 SensorSampleType getSensorSampleTypeFromSensorType(SensorType sensorType);
208
209 /**
210 * This SensorMode is designed to wrap constants provided by the CHRE API to
211 * imrpove type-safety. The details of these modes are left to the CHRE API mode
212 * definitions contained in the chreSensorConfigureMode enum.
213 */
214 enum class SensorMode {
215 Off,
216 ActiveContinuous,
217 ActiveOneShot,
218 PassiveContinuous,
219 PassiveOneShot,
220 };
221
222 /**
223 * @return true if the sensor mode is considered to be active and would cause a
224 * sensor to be powered on in order to get sensor data.
225 */
sensorModeIsActive(SensorMode sensorMode)226 constexpr bool sensorModeIsActive(SensorMode sensorMode) {
227 return (sensorMode == SensorMode::ActiveContinuous
228 || sensorMode == SensorMode::ActiveOneShot);
229 }
230
231 /**
232 * @return true if the sensor mode is considered to be passive and would not
233 * cause a sensor to be powered on in order to get sensor data.
234 */
sensorModeIsPassive(SensorMode sensorMode)235 constexpr bool sensorModeIsPassive(SensorMode sensorMode) {
236 return (sensorMode == SensorMode::PassiveContinuous
237 || sensorMode == SensorMode::PassiveOneShot);
238 }
239
240 /**
241 * @return true if the sensor mode is considered to be contunuous.
242 */
sensorModeIsContinuous(SensorMode sensorMode)243 constexpr bool sensorModeIsContinuous(SensorMode sensorMode) {
244 return (sensorMode == SensorMode::ActiveContinuous
245 || sensorMode == SensorMode::PassiveContinuous);
246 }
247
248 /**
249 * @return true if the sensor mode is considered to be one-shot.
250 */
sensorModeIsOneShot(SensorMode sensorMode)251 constexpr bool sensorModeIsOneShot(SensorMode sensorMode) {
252 return (sensorMode == SensorMode::ActiveOneShot
253 || sensorMode == SensorMode::PassiveOneShot);
254 }
255
256 /**
257 * Translates a CHRE API enum sensor mode to a SensorMode. This function also
258 * performs input validation and will default to SensorMode::Off if the provided
259 * value is not a valid enum value.
260 *
261 * @param enumSensorMode A potentially unsafe CHRE API enum sensor mode.
262 * @return Returns a SensorMode given a CHRE API enum sensor mode.
263 */
264 SensorMode getSensorModeFromEnum(enum chreSensorConfigureMode enumSensorMode);
265
266 /**
267 * Indicates whether the sensor type is a one-shot sensor.
268 *
269 * @param sensorType The sensor type of the sensor.
270 * @return true if the sensor is a one-shot sensor.
271 */
272 bool sensorTypeIsOneShot(SensorType sensorType);
273
274 /**
275 * Indicates whether the sensor type is an on-change sensor.
276 *
277 * @param sensorType The sensor type of the sensor.
278 * @return true if the sensor is an on-change sensor.
279 */
280 bool sensorTypeIsOnChange(SensorType sensorType);
281
282 /**
283 * Indicates whether the sensor type is a continuous sensor.
284 *
285 * @param sensorType The sensor type of the sensor.
286 * @return true if the sensor is a continuous sensor.
287 */
288 bool sensorTypeIsContinuous(SensorType sensorType);
289
290 /**
291 * Indicates whether the sensor type reports bias events.
292 *
293 * @param sensorType The sensor type of the sensor.
294 * @return true if the sensor reports bias events.
295 */
296 bool sensorTypeReportsBias(SensorType sensorType);
297
298 /**
299 * @param sensorType The sensor type.
300 * @param eventType A non-null pointer to where the event type is stored.
301 *
302 * @return true if the sensor type reports bias events.
303 */
304 bool getSensorBiasEventType(SensorType sensorType, uint16_t *eventType);
305
306 /**
307 * @param sensorType The sensor type.
308 *
309 * @return true if the sensor is a runtime-calibrated sensor.
310 */
311 bool sensorTypeIsCalibrated(SensorType sensorType);
312
313 /**
314 * @param sensorType The sensor type.
315 *
316 * @return The corresponding runtime-calibrated sensor type. If the sensor does
317 * not have one, then the input sensorType is returned.
318 */
319 SensorType toCalibratedSensorType(SensorType sensorType);
320
321 /**
322 * @param sensorType The sensor type.
323 *
324 * @return The corresponding uncalibrated sensor type. If the sensor does not
325 * have one, then the input sensorType is returned.
326 */
327 SensorType toUncalibratedSensorType(SensorType sensorType);
328
329 } // namespace chre
330
331 #endif // CHRE_CORE_SENSOR_TYPE_H_
332