Home | History | Annotate | Download | only in core 
      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 {
     42   Unknown,
     43   Accelerometer,
     44   InstantMotion,
     45   StationaryDetect,
     46   Gyroscope,
     47   GeomagneticField,
     48   Pressure,
     49   Light,
     50   Proximity,
     51   AccelerometerTemperature,
     52   GyroscopeTemperature,
     53   GeomagneticFieldTemperature,
     54   UncalibratedAccelerometer,
     55   UncalibratedGyroscope,
     56   UncalibratedGeomagneticField,
     57 
     58   VendorType0,
     59   VendorType1,
     60   VendorType2,
     61 
     62   // Note to future developers: don't forget to update the implementation of
     63   // 1) getSensorTypeName,
     64   // 2) getSensorTypeFromUnsignedInt,
     65   // 3) getUnsignedIntFromSensorType,
     66   // 4) getSensorSampleTypeFromSensorType
     67   // 5) sensorTypeIsOneShot
     68   // 6) sensorTypeIsOnChange
     69   // when adding or removing a new entry here :)
     70   // Have a nice day.
     71 
     72   //! The number of sensor types including unknown. This entry must be last.
     73   SENSOR_TYPE_COUNT,
     74 };
     75 
     76 /**
     77  * This SensorSampleType is designed to help classify SensorType's data type in
     78  * event handling.
     79  */
     80 enum class SensorSampleType {
     81   Byte,
     82   Float,
     83   Occurrence,
     84   ThreeAxis,
     85   Vendor0,
     86   Vendor1,
     87   Vendor2,
     88   Unknown,
     89 };
     90 
     91 /**
     92  * Returns a string representation of the given sensor type.
     93  *
     94  * @param sensorType The sensor type to obtain a string for.
     95  * @return A string representation of the sensor type.
     96  */
     97 const char *getSensorTypeName(SensorType sensorType);
     98 
     99 /**
    100  * Returns a sensor sample event type for a given sensor type. The sensor type
    101  * must not be SensorType::Unknown. This is a fatal error.
    102  *
    103  * @param sensorType The type of the sensor.
    104  * @return The event type for a sensor sample of the given sensor type.
    105  */
    106 uint16_t getSampleEventTypeForSensorType(SensorType sensorType);
    107 
    108 /**
    109  * Returns a sensor type for a given sensor sample event type.
    110  *
    111  * @param eventType The event type for a sensor sample.
    112  * @return The type of the sensor.
    113  */
    114 SensorType getSensorTypeForSampleEventType(uint16_t eventType);
    115 
    116 /**
    117  * @return An index into an array for a given sensor type. This is useful to map
    118  * sensor type to array index quickly. The range returned corresponds to any
    119  * SensorType except for Unknown starting from zero to the maximum value sensor
    120  * with no gaps.
    121  */
    122 constexpr size_t getSensorTypeArrayIndex(SensorType sensorType) {
    123   return static_cast<size_t>(sensorType) - 1;
    124 }
    125 
    126 /**
    127  * @return The number of valid sensor types in the SensorType enum.
    128  */
    129 constexpr size_t getSensorTypeCount() {
    130   // The number of valid entries in the SensorType enum (not including Unknown).
    131   return static_cast<size_t>(SensorType::SENSOR_TYPE_COUNT) - 1;
    132 }
    133 
    134 /**
    135  * Translates an unsigned integer as provided by a CHRE-compliant nanoapp to a
    136  * SensorType. If the integer sensor type does not match one of the internal
    137  * sensor types, SensorType::Unknown is returned.
    138  *
    139  * @param sensorType The integer sensor type.
    140  * @return The strongly-typed sensor if a match is found or SensorType::Unknown.
    141  */
    142 SensorType getSensorTypeFromUnsignedInt(uint8_t sensorType);
    143 
    144 /**
    145  * Translates a SensorType to an unsigned integer as provided by CHRE API. If
    146  * the sensor type is SensorType::Unknown, 0 is returned.
    147  *
    148  * @param sensorType The strongly-typed sensor.
    149  * @return The integer sensor type if sensorType is not SensorType::Unknown.
    150  */
    151 uint8_t getUnsignedIntFromSensorType(SensorType sensorType);
    152 
    153 /**
    154  * Provides a stable handle for a CHRE sensor type. This handle is exposed to
    155  * CHRE nanoapps as a way to refer to sensors that they are subscribing to. This
    156  * API is not expected to be called with SensorType::Unknown as nanoapps are not
    157  * able to subscribe to the Unknown sensor type.
    158  *
    159  * @param sensorType The type of the sensor to obtain a handle for.
    160  * @return The handle for a given sensor.
    161  */
    162 constexpr uint32_t getSensorHandleFromSensorType(SensorType sensorType) {
    163   return static_cast<uint32_t>(sensorType);
    164 }
    165 
    166 /**
    167  * Maps a sensor handle to a SensorType or returns SensorType::Unknown if the
    168  * provided handle is invalid.
    169  *
    170  * @param handle The sensor handle for a sensor.
    171  * @return The sensor type for a given handle.
    172  */
    173 constexpr SensorType getSensorTypeFromSensorHandle(uint32_t handle) {
    174   return (handle > static_cast<uint32_t>(SensorType::Unknown)
    175           && handle < static_cast<uint32_t>(SensorType::SENSOR_TYPE_COUNT))
    176       ? static_cast<SensorType>(handle) : SensorType::Unknown;
    177 }
    178 
    179 /**
    180  * Obtains the temperature sensor type of the specified sensor type.
    181  *
    182  * @param sensorType The sensor type to obtain its temperature sensor type for.
    183  * @return The temperature sensor type or SensorType::Unknown if not supported
    184  *         by CHRE.
    185  */
    186 SensorType getTempSensorType(SensorType sensorType);
    187 
    188 /**
    189  * Maps a sensorType to its SensorSampleType.
    190  *
    191  * @param sensorType The type of the sensor to obtain its SensorSampleType for.
    192  * @return The SensorSampleType of the sensorType.
    193  */
    194 SensorSampleType getSensorSampleTypeFromSensorType(SensorType sensorType);
    195 
    196 /**
    197  * This SensorMode is designed to wrap constants provided by the CHRE API to
    198  * imrpove type-safety. The details of these modes are left to the CHRE API mode
    199  * definitions contained in the chreSensorConfigureMode enum.
    200  */
    201 enum class SensorMode {
    202   Off,
    203   ActiveContinuous,
    204   ActiveOneShot,
    205   PassiveContinuous,
    206   PassiveOneShot,
    207 };
    208 
    209 /**
    210  * @return true if the sensor mode is considered to be active and would cause a
    211  *         sensor to be powered on in order to get sensor data.
    212  */
    213 constexpr bool sensorModeIsActive(SensorMode sensorMode) {
    214   return (sensorMode == SensorMode::ActiveContinuous
    215       || sensorMode == SensorMode::ActiveOneShot);
    216 }
    217 
    218 /**
    219  * @return true if the sensor mode is considered to be passive and would not
    220  *         cause a sensor to be powered on in order to get sensor data.
    221  */
    222 constexpr bool sensorModeIsPassive(SensorMode sensorMode) {
    223   return (sensorMode == SensorMode::PassiveContinuous
    224       || sensorMode == SensorMode::PassiveOneShot);
    225 }
    226 
    227 /**
    228  * @return true if the sensor mode is considered to be contunuous.
    229  */
    230 constexpr bool sensorModeIsContinuous(SensorMode sensorMode) {
    231   return (sensorMode == SensorMode::ActiveContinuous
    232       || sensorMode == SensorMode::PassiveContinuous);
    233 }
    234 
    235 /**
    236  * @return true if the sensor mode is considered to be one-shot.
    237  */
    238 constexpr bool sensorModeIsOneShot(SensorMode sensorMode) {
    239   return (sensorMode == SensorMode::ActiveOneShot
    240       || sensorMode == SensorMode::PassiveOneShot);
    241 }
    242 
    243 /**
    244  * Translates a CHRE API enum sensor mode to a SensorMode. This function also
    245  * performs input validation and will default to SensorMode::Off if the provided
    246  * value is not a valid enum value.
    247  *
    248  * @param enumSensorMode A potentially unsafe CHRE API enum sensor mode.
    249  * @return Returns a SensorMode given a CHRE API enum sensor mode.
    250  */
    251 SensorMode getSensorModeFromEnum(enum chreSensorConfigureMode enumSensorMode);
    252 
    253 /**
    254  * Indicates whether the sensor type is a one-shot sensor.
    255  *
    256  * @param sensorType The sensor type of the sensor.
    257  * @return true if the sensor is a one-shot sensor.
    258  */
    259 bool sensorTypeIsOneShot(SensorType sensorType);
    260 
    261 /**
    262  * Indicates whether the sensor type is an on-change sensor.
    263  *
    264  * @param sensorType The sensor type of the sensor.
    265  * @return true if the sensor is an on-change sensor.
    266  */
    267 bool sensorTypeIsOnChange(SensorType sensorType);
    268 
    269 /**
    270  * Indicates whether the sensor type is a continuous sensor.
    271  *
    272  * @param sensorType The sensor type of the sensor.
    273  * @return true if the sensor is a continuous sensor.
    274  */
    275 bool sensorTypeIsContinuous(SensorType sensorType);
    276 
    277 }  // namespace chre
    278 
    279 #endif  // CHRE_CORE_SENSOR_TYPE_H_
    280