1 /*
2  * Copyright (C) 2018 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 VENDOR_GOOGLE_CAMERA_SENSOR_LISTENER_GOOG_SENSOR_MOTION_H_
18 #define VENDOR_GOOGLE_CAMERA_SENSOR_LISTENER_GOOG_SENSOR_MOTION_H_
19 
20 #include "goog_sensor_wrapper.h"
21 
22 namespace android {
23 namespace camera_sensor_listener {
24 
25 // Supported motion sensor types:
26 // ::android::hardware::sensors::V1_0::SensorType::ACCELEROMETER
27 // ::android::hardware::sensors::V1_0::SensorType::GRAVITY
28 // ::android::hardware::sensors::V1_0::SensorType::GYROSCOPE
29 // ::android::hardware::sensors::V1_0::SensorType::LINEAR_ACCELERATION
30 // ::android::hardware::sensors::V1_0::SensorType::MAGNETIC_FIELD
31 enum class MotionSensorType : int {
32   ACCELEROMETER = 0,
33   GRAVITY,
34   GYROSCOPE,
35   LINEAR_ACCELERATION,
36   MAGNETIC_FIELD,
37   TOTAL_NUM
38 };
39 
40 // Motion sensor listener class.
41 // It will create a motion sensor listener whose event consists of three
42 // floating numbers corresponding to data in x, y, z axes. Please refer to
43 // Sensor Coorindate System section in
44 // https://developer.android.com/guide/topics/sensors/sensors_overview
45 // to check definition of x, y, z axis.
46 // ACCELEROMETER sensor event data's measure unit is m/s^2:
47 //   motion_vector_x: Acceleration force along the x axis (including gravity).
48 //   motion_vector_y: Acceleration force along the y axis (including gravity).
49 //   motion_vector_z: Acceleration force along the z axis (including gravity).
50 // GRAVITY sensor event data's measure unit is m/s^2:
51 //   motion_vector_x: Force of gravity along the x axis.
52 //   motion_vector_y: Force of gravity along the y axis.
53 //   motion_vector_z: Force of gravity along the z axis.
54 // GYROSCOPE sensor event data's measure unit is rad/s:
55 //   motion_vector_x: Rate of rotation around the x axis.
56 //   motion_vector_y: Rate of rotation around the y axis.
57 //   motion_vector_z: Rate of rotation around the z axis.
58 // LINEAR_ACCELERATION sensor event data's measure unit is m/s^2:
59 //   motion_vector_x: Acceleration force along the x axis (excluding gravity).
60 //   motion_vector_y: Acceleration force along the y axis (excluding gravity).
61 //   motion_vector_z: Acceleration force along the z axis (excluding gravity).
62 // MAGNETIC_FIELD sensor event data's measure unit is micro Tesla(uT):
63 //   motion_vector_x: Geomagnetic field strength along the x axis.
64 //   motion_vector_y: Geomagnetic field strength along the y axis.
65 //   motion_vector_z: Geomagnetic field strength along the z axis.
66 // Sample usage:
67 //   sp<GoogSensorMotion> sensor_ptr =
68 //       GoogSensorMotion::Create(MotionSensorType::GYROSCOPE,
69 //                                /*sampling_period_us=*/20000,
70 //                                /*event_queue_size=*/20);
71 //   std::function<void(const ExtendedSensorEvent& event)> callback =
72 //       [](const ExtendedSensorEvent& event) {
73 //         // customized operations.
74 //      };
75 //   //  Customized event callback is optional.
76 //   sensor_ptr->SetEventProcessor(callback);
77 //   if (sensor_ptr->GetSensorenablingStatus()) {
78 //     std::vector<int64_t> event_timestamps;
79 //     std::vector<float> motion_vector_x;
80 //     std::vector<float> motion_vector_y;
81 //     std::vector<float> motion_vector_z;
82 //     std::vector<int64_t> arrival_timestamps;
83 //     sensor_ptr->GetLatestNSensorEvents(
84 //         /*num_sample=*/5, &event_timestamps, &motion_vector_x,
85 //         &motion_vector_y, &motion_vector_z, &arrival_timestamps);
86 //   }
87 class GoogSensorMotion : public GoogSensorWrapper {
88  public:
89   // Return a StrongPointer pointing to newly created GoogSensorMotion
90   // instance.
91   // Inputs:
92   //   motion_sensor_type: sensor type defined in enum class MotionSensorType.
93   //   sampling_period_us: gyro sampling period in us (1e-6s). Sampling period
94   //     should be >= 2500us as system can only support up to 400Hz frequency.
95   //     If sampling_period_us < 2500us, a nullptr will be returned.
96   //   event_queue_size: size of event queue to hold incoming sensor events.
97   static sp<GoogSensorMotion> Create(
98       MotionSensorType motion_sensor_type,
99       int64_t sampling_period_us = kDefaultSamplingPeriodUs,
100       size_t event_queue_size = kDefaultEventQueueSize);
101 
102   // Destructor.
103   // Destroy and free the resources of a GoogSensorMotion.
104   ~GoogSensorMotion();
105 
106   // Get whether sensor is enabled.
107   // Return true if sensor is enabled, false otherwise.
GetSensorEnablingStatus()108   bool GetSensorEnablingStatus() const {
109     return IsEnabled();
110   }
111 
112   // Get latest n sensor events' timestamps, event data and arrival times.
113   // If output vectors are not empty, they will be cleared first.
114   // If total samples in event_deque_ is smaller than num_sample, size of
115   // output vectors will be equal to event_deque_.size().
116   // Input:
117   //   num_sample: number of latest samples to query.
118   // Outputs:
119   //   latest_n_timestamps: pointer of vector to hold timestamps.
120   //   motion_vector_x: pointer of vector to hold event data in x axis.
121   //   motion_vector_y: pointer of vector to hold event data in y axis.
122   //   motion_vector_z: pointer of vector to hold event data in z axis.
123   //   latest_n_arrival_timestamps: pointer of vector to hold arrival times.
124   // Event timestamps, data and arrival timestamps are listed in chronological
125   // order, i.e., latest_n_timestamps[0], motion_vector_x[0],
126   // motion_vector_y[0], motion_vector_z[0], and latest_n_arrival_timestamps[0]
127   // hold the earliest data.
128   void GetLatestNSensorEvents(
129       int num_sample, std::vector<int64_t>* latest_n_timestamps,
130       std::vector<float>* motion_vector_x, std::vector<float>* motion_vector_y,
131       std::vector<float>* motion_vector_z,
132       std::vector<int64_t>* latest_n_arrival_timestamps) const;
133 
134   // Query sensor events between between the range (start_time, end_time].
135   // Inputs:
136   //   start_time: queried events' timestamps must be > start_time.
137   //   end_time: queried events' timestamps must be <= end_time.
138   // Outputs:
139   //   event_timestamps: pointer of vector to hold queried events' timestamps.
140   //   motion_vector_x: pointer of vector to hold queried events' x axis data.
141   //   motion_vector_y: pointer of vector to hold queried events' y axis data.
142   //   motion_vector_z: pointer of vector to hold queried events' z axis data.
143   //   event_arrival_timestamps: pointer of vector to hold arrival times.
144   // Event timestamps, data and arrival timestamps are listed in chronological
145   // order, i.e., event_timestamps[0], motion_vector_x[0],
146   // motion_vector_y[0], motion_vector_z[0], and event_arrival_timestamps[0]
147   // hold the earliest data.
148   void QuerySensorEventsBetweenTimestamps(
149       int64_t start_time, int64_t end_time,
150       std::vector<int64_t>* event_timestamps,
151       std::vector<float>* motion_vector_x, std::vector<float>* motion_vector_y,
152       std::vector<float>* motion_vector_z,
153       std::vector<int64_t>* event_arrival_timestamps) const;
154 
GetSensorName()155   const char* GetSensorName() const {
156     return GetSensorName(motion_sensor_type_);
157   }
158 
159  protected:
160   // Get motion sensor handle.
161   virtual int32_t GetSensorHandle() final;
162 
163  private:
164   // Constructor.
165   // Create and initialize a GoogSensorMotion.
166   // Inputs:
167   //   motion_sensor_type: sensor type defined in enum class MotionSensorType.
168   //   sampling_period_us: gyro sampling period in us (1e-6s). Sampling period
169   //     should be >= 2500us as system can only support up to 400Hz frequency.
170   //   event_queue_size: size of event queue to hold incoming sensor events.
171   GoogSensorMotion(MotionSensorType motion_sensor_type,
172                    int64_t sampling_period_us, size_t event_queue_size);
173 
174   static const char* GetSensorName(MotionSensorType motion_sensor_type);
175 
176   MotionSensorType motion_sensor_type_;
177 
178   static constexpr size_t kDefaultEventQueueSize = 20;
179   static constexpr int64_t kDefaultSamplingPeriodUs = 20000;  // = 50 Hz
180   static constexpr int64_t kMinSamplingPeriodUs = 2500;       // = 400 Hz
181 };
182 
183 }  // namespace camera_sensor_listener
184 }  // namespace android
185 
186 #endif  // VENDOR_GOOGLE_CAMERA_SENSOR_LISTENER_GOOG_SENSOR_MOTION_H_
187