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     WristTilt = 39,
73 
74     Max_
75 };
76 
77 // Overloaded values of rate used in sensor enable request (see sensors.h)
78 enum class SensorSpecialRate : uint32_t {
79     None     = 0,
80     OnDemand = 0xFFFFFF00,
81     OnChange = 0xFFFFFF01,
82     OneShot  = 0xFFFFFF02,
83 };
84 
85 struct SensorSpec {
86     SensorType sensor_type = SensorType::Invalid_;
87 
88     // When enabling a sensor, rate can be specified in Hz or as one of the
89     // special values
90     SensorSpecialRate special_rate = SensorSpecialRate::None;
91     float rate_hz = -1;
92     uint64_t latency_ns = 0;
93 
94     // Reference value (ground truth) used for calibration
95     bool have_cal_ref = false;
96     float cal_ref;
97 };
98 
99 /*
100  * An interface for communicating with a ContextHub.
101  */
102 class ContextHub : public NonCopyable {
103   public:
~ContextHub()104     virtual ~ContextHub() {};
105 
106     static std::string SensorTypeToAbbrevName(SensorType sensor_type);
107     static SensorType SensorAbbrevNameToType(const char *abbrev_name);
108     static SensorType SensorAbbrevNameToType(const std::string& abbrev_name);
109     static std::string ListAllSensorAbbrevNames();
110 
111     /*
112      * Performs initialization to allow commands to be sent to the context hub.
113      * Must be called before any other functions that send commands. Returns
114      * true on success, false on failure.
115      */
116     virtual bool Initialize() = 0;
117 
118     /*
119      * Configures the ContextHub to allow logs to be printed to stdout.
120      */
121     virtual void SetLoggingEnabled(bool logging_enabled) = 0;
122 
123     /*
124      * Loads a new firmware image to the ContextHub. The firmware image is
125      * specified by filename. Returns false if an error occurs.
126      */
127     bool Flash(const std::string& filename);
128 
129     /*
130      * Performs the sensor calibration routine and writes the resulting data to
131      * a file.
132      */
133     bool CalibrateSensors(const std::vector<SensorSpec>& sensors);
134 
135     /*
136      * Performs the sensor self-test routine.
137      */
138     bool TestSensors(const std::vector<SensorSpec>& sensors);
139 
140     /*
141      * Sends a sensor enable request to the context hub.
142      */
143     bool EnableSensor(const SensorSpec& sensor);
144     bool EnableSensors(const std::vector<SensorSpec>& sensors);
145 
146     /*
147      * Sends a disable sensor request to context hub. Note that this always
148      * results in sending a request, i.e. this does not check whether the sensor
149      * is currently enabled or not.
150      */
151     bool DisableSensor(SensorType sensor_type);
152     bool DisableSensors(const std::vector<SensorSpec>& sensors);
153 
154     /*
155      * Sends a disable sensor request for every sensor type we know about.
156      */
157     bool DisableAllSensors();
158 
159     /*
160      * Calls DisableSensor() on all active sensors (i.e. those which have been
161      * enabled but not yet disabled). This should be called from the destructor
162      * of derived classes before tearing down communications to ensure we don't
163      * leave sensors enabled after exiting.
164      */
165     bool DisableActiveSensors();
166 
167     /*
168      * Sends all data stored in the calibration file to the context hub.
169      */
170     virtual bool LoadCalibration();
171 
172     /*
173      * Prints up to <limit> incoming events. If limit is 0, then continues
174      * indefinitely.
175      */
176     void PrintAllEvents(unsigned int limit);
177 
178     /*
179      * Requests bridge version information
180      */
181     bool PrintBridgeVersion();
182 
183     /*
184      * Prints up to <sample_limit> incoming sensor samples corresponding to the
185      * given SensorType, ignoring other events. If sample_limit is 0, then
186      * continues indefinitely.
187      */
188     void PrintSensorEvents(SensorType sensor_type, int sample_limit);
189     void PrintSensorEvents(const std::vector<SensorSpec>& sensors,
190         int sample_limit);
191 
192   protected:
193     enum class TransportResult {
194         Success,
195         GeneralFailure,
196         Timeout,
197         ParseFailure,
198         Canceled,
199         // Add more specific error reasons as needed
200     };
201 
202     // Performs the calibration routine, but does not call SaveCalibration()
203     bool CalibrateSingleSensor(const SensorSpec& sensor);
204 
205     // Performs the self-test routine
206     bool TestSingleSensor(const SensorSpec& sensor);
207 
208     /*
209      * Iterates over sensors, invoking the given callback on each element.
210      * Returns true if all callbacks returned true. Exits early on failure.
211      */
212     bool ForEachSensor(const std::vector<SensorSpec>& sensors,
213         std::function<bool(const SensorSpec&)> callback);
214 
215     /*
216      * Parses a calibration result event and invokes the appropriate
217      * SetCalibration function with the calibration data.
218      */
219     bool HandleCalibrationResult(const SensorSpec& sensor,
220         const AppToHostEvent &event);
221 
222     /*
223      * Parses a self-test result event
224      */
225     bool HandleTestResult(const SensorSpec& sensor,
226         const AppToHostEvent &event);
227 
228     /*
229      * Same as ReadSensorEvents, but filters on AppToHostEvent instead of
230      * SensorEvent.
231      */
232     TransportResult ReadAppEvents(std::function<bool(const AppToHostEvent&)> callback,
233         int timeout_ms = 0);
234 
235     /*
236      * Calls ReadEvent in a loop, handling errors and ignoring events that
237      * didn't originate from a sensor. Valid SensorEvents are passed to the
238      * callback for further processing. The callback should return a boolean
239      * indicating whether to continue (true) or exit the read loop (false).
240      */
241     void ReadSensorEvents(std::function<bool(const SensorEvent&)> callback);
242 
243     /*
244      * Sends the given calibration data down to the hub
245      */
246     bool SendCalibrationData(SensorType sensor_type,
247         const std::vector<uint8_t>& cal_data);
248 
249     /*
250      * Read an event from the sensor hub. Block until a event is successfully
251      * read, no event traffic is generated for the timeout period, or an error
252      * occurs, such as a CRC check failure.
253      */
254     virtual TransportResult ReadEvent(std::vector<uint8_t>& response,
255         int timeout_ms) = 0;
256     virtual TransportResult WriteEvent(const std::vector<uint8_t>& request) = 0;
257 
258     // Implements the firmware loading functionality for the sensor hub. Returns
259     // false if an error occurs while writing the firmware to the device.
260     virtual bool FlashSensorHub(const std::vector<uint8_t>& bytes) = 0;
261 
262     // Convenience functions that build on top of the more generic byte-level
263     // interface
264     TransportResult ReadEvent(std::unique_ptr<ReadEventResponse>* response,
265         int timeout_ms = 0);
266     TransportResult WriteEvent(const WriteEventRequest& request);
267 
268     // Override these if saving calibration data to persistent storage is
269     // supported on the platform
270     virtual bool SetCalibration(SensorType sensor_type, int32_t data);
271     virtual bool SetCalibration(SensorType sensor_type, float data);
272     virtual bool SetCalibration(SensorType sensor_type, int32_t x,
273         int32_t y, int32_t z);
274     virtual bool SetCalibration(SensorType sensor_type, int32_t x,
275         int32_t y, int32_t z, int32_t w);
276     virtual bool SaveCalibration();
277 
278 private:
279     std::bitset<static_cast<int>(SensorType::Max_)> sensor_is_active_;
280 };
281 
282 }  // namespace android
283 
284 #endif  // CONTEXTHUB_H_
285