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 CONTEXTHUB_H_ 18 #define CONTEXTHUB_H_ 19 20 #include "nanomessage.h" 21 #include "noncopyable.h" 22 23 #include <bitset> 24 #include <functional> 25 #include <vector> 26 27 namespace android { 28 29 class AppToHostEvent; 30 class SensorEvent; 31 32 // Array length helper macro 33 #define ARRAY_LEN(arr) (sizeof(arr) / sizeof(arr[0])) 34 35 enum class SensorType { 36 Invalid_ = 0, 37 38 // The order of this enum must correspond to sensor types in nanohub's 39 // sensType.h 40 Accel, 41 AnyMotion, 42 NoMotion, 43 SignificantMotion, 44 Flat, 45 Gyro, 46 GyroUncal, 47 Magnetometer, 48 MagnetometerUncal, 49 Barometer, 50 Temperature, 51 AmbientLightSensor, 52 Proximity, 53 Orientation, 54 HeartRateECG, 55 HeartRatePPG, 56 Gravity, 57 LinearAccel, 58 RotationVector, 59 GeomagneticRotationVector, 60 GameRotationVector, 61 StepCount, 62 StepDetect, 63 Gesture, 64 Tilt, 65 DoubleTwist, 66 DoubleTap, 67 WindowOrientation, 68 Hall, 69 Activity, 70 Vsync, 71 CompressedAccel, 72 73 Max_ 74 }; 75 76 // Overloaded values of rate used in sensor enable request (see sensors.h) 77 enum class SensorSpecialRate : uint32_t { 78 None = 0, 79 OnDemand = 0xFFFFFF00, 80 OnChange = 0xFFFFFF01, 81 OneShot = 0xFFFFFF02, 82 }; 83 84 struct SensorSpec { 85 SensorType sensor_type = SensorType::Invalid_; 86 87 // When enabling a sensor, rate can be specified in Hz or as one of the 88 // special values 89 SensorSpecialRate special_rate = SensorSpecialRate::None; 90 float rate_hz = -1; 91 uint64_t latency_ns = 0; 92 93 // Reference value (ground truth) used for calibration 94 bool have_cal_ref = false; 95 float cal_ref; 96 }; 97 98 /* 99 * An interface for communicating with a ContextHub. 100 */ 101 class ContextHub : public NonCopyable { 102 public: ~ContextHub()103 virtual ~ContextHub() {}; 104 105 static std::string SensorTypeToAbbrevName(SensorType sensor_type); 106 static SensorType SensorAbbrevNameToType(const char *abbrev_name); 107 static SensorType SensorAbbrevNameToType(const std::string& abbrev_name); 108 static std::string ListAllSensorAbbrevNames(); 109 110 /* 111 * Performs initialization to allow commands to be sent to the context hub. 112 * Must be called before any other functions that send commands. Returns 113 * true on success, false on failure. 114 */ 115 virtual bool Initialize() = 0; 116 117 /* 118 * Configures the ContextHub to allow logs to be printed to stdout. 119 */ 120 virtual void SetLoggingEnabled(bool logging_enabled) = 0; 121 122 /* 123 * Loads a new firmware image to the ContextHub. The firmware image is 124 * specified by filename. Returns false if an error occurs. 125 */ 126 bool Flash(const std::string& filename); 127 128 /* 129 * Performs the sensor calibration routine and writes the resulting data to 130 * a file. 131 */ 132 bool CalibrateSensors(const std::vector<SensorSpec>& sensors); 133 134 /* 135 * Sends a sensor enable request to the context hub. 136 */ 137 bool EnableSensor(const SensorSpec& sensor); 138 bool EnableSensors(const std::vector<SensorSpec>& sensors); 139 140 /* 141 * Sends a disable sensor request to context hub. Note that this always 142 * results in sending a request, i.e. this does not check whether the sensor 143 * is currently enabled or not. 144 */ 145 bool DisableSensor(SensorType sensor_type); 146 bool DisableSensors(const std::vector<SensorSpec>& sensors); 147 148 /* 149 * Sends a disable sensor request for every sensor type we know about. 150 */ 151 bool DisableAllSensors(); 152 153 /* 154 * Calls DisableSensor() on all active sensors (i.e. those which have been 155 * enabled but not yet disabled). This should be called from the destructor 156 * of derived classes before tearing down communications to ensure we don't 157 * leave sensors enabled after exiting. 158 */ 159 bool DisableActiveSensors(); 160 161 /* 162 * Sends all data stored in the calibration file to the context hub. 163 */ 164 virtual bool LoadCalibration(); 165 166 /* 167 * Prints up to <limit> incoming events. If limit is 0, then continues 168 * indefinitely. 169 */ 170 void PrintAllEvents(unsigned int limit); 171 172 /* 173 * Prints up to <sample_limit> incoming sensor samples corresponding to the 174 * given SensorType, ignoring other events. If sample_limit is 0, then 175 * continues indefinitely. 176 */ 177 void PrintSensorEvents(SensorType sensor_type, int sample_limit); 178 void PrintSensorEvents(const std::vector<SensorSpec>& sensors, 179 int sample_limit); 180 181 protected: 182 enum class TransportResult { 183 Success, 184 GeneralFailure, 185 Timeout, 186 ParseFailure, 187 Canceled, 188 // Add more specific error reasons as needed 189 }; 190 191 // Performs the calibration routine, but does not call SaveCalibration() 192 bool CalibrateSingleSensor(const SensorSpec& sensor); 193 194 /* 195 * Iterates over sensors, invoking the given callback on each element. 196 * Returns true if all callbacks returned true. Exits early on failure. 197 */ 198 bool ForEachSensor(const std::vector<SensorSpec>& sensors, 199 std::function<bool(const SensorSpec&)> callback); 200 201 /* 202 * Parses a calibration result event and invokes the appropriate 203 * SetCalibration function with the calibration data. 204 */ 205 bool HandleCalibrationResult(const SensorSpec& sensor, 206 const AppToHostEvent &event); 207 208 /* 209 * Same as ReadSensorEvents, but filters on AppToHostEvent instead of 210 * SensorEvent. 211 */ 212 TransportResult ReadAppEvents(std::function<bool(const AppToHostEvent&)> callback, 213 int timeout_ms = 0); 214 215 /* 216 * Calls ReadEvent in a loop, handling errors and ignoring events that 217 * didn't originate from a sensor. Valid SensorEvents are passed to the 218 * callback for further processing. The callback should return a boolean 219 * indicating whether to continue (true) or exit the read loop (false). 220 */ 221 void ReadSensorEvents(std::function<bool(const SensorEvent&)> callback); 222 223 /* 224 * Sends the given calibration data down to the hub 225 */ 226 bool SendCalibrationData(SensorType sensor_type, 227 const std::vector<uint8_t>& cal_data); 228 229 /* 230 * Read an event from the sensor hub. Block until a event is successfully 231 * read, no event traffic is generated for the timeout period, or an error 232 * occurs, such as a CRC check failure. 233 */ 234 virtual TransportResult ReadEvent(std::vector<uint8_t>& response, 235 int timeout_ms) = 0; 236 virtual TransportResult WriteEvent(const std::vector<uint8_t>& request) = 0; 237 238 // Implements the firmware loading functionality for the sensor hub. Returns 239 // false if an error occurs while writing the firmware to the device. 240 virtual bool FlashSensorHub(const std::vector<uint8_t>& bytes) = 0; 241 242 // Convenience functions that build on top of the more generic byte-level 243 // interface 244 TransportResult ReadEvent(std::unique_ptr<ReadEventResponse>* response, 245 int timeout_ms = 0); 246 TransportResult WriteEvent(const WriteEventRequest& request); 247 248 // Override these if saving calibration data to persistent storage is 249 // supported on the platform 250 virtual bool SetCalibration(SensorType sensor_type, int32_t data); 251 virtual bool SetCalibration(SensorType sensor_type, float data); 252 virtual bool SetCalibration(SensorType sensor_type, int32_t x, 253 int32_t y, int32_t z); 254 virtual bool SetCalibration(SensorType sensor_type, int32_t x, 255 int32_t y, int32_t z, int32_t w); 256 virtual bool SaveCalibration(); 257 258 private: 259 std::bitset<static_cast<int>(SensorType::Max_)> sensor_is_active_; 260 }; 261 262 } // namespace android 263 264 #endif // CONTEXTHUB_H_ 265