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 package android.hardware; 18 19 import android.annotation.IntDef; 20 21 import java.lang.annotation.Retention; 22 import java.lang.annotation.RetentionPolicy; 23 24 /** 25 * This class represents a {@link android.hardware.Sensor Sensor} additional information frame, 26 * which is reported through listener callback {@link 27 * android.hardware.SensorEventCallback#onSensorAdditionalInfo onSensorAdditionalInfo}. 28 * 29 * @see SensorManager 30 * @see SensorEventCallback 31 * @see Sensor 32 * 33 */ 34 35 public class SensorAdditionalInfo { 36 37 /** 38 * The sensor that generated this event. See 39 * {@link android.hardware.SensorManager SensorManager} for details. 40 */ 41 public final Sensor sensor; 42 43 /** 44 * Type of this additional info frame. 45 */ 46 public final int type; 47 48 /** 49 * Sequence number of frame for a certain type. 50 */ 51 public final int serial; 52 53 /** 54 * Additional info payload data represented in float values. Depending on the type of 55 * information, this may be null. 56 */ 57 public final float[] floatValues; 58 59 /** 60 * Additional info payload data represented in int values. Depending on the type of information, 61 * this may be null. 62 */ 63 public final int[] intValues; 64 65 /** 66 * Typical values of additional infomation type. The set of values is subject to extension in 67 * newer versions and vendors have the freedom of define their own custom values. 68 * 69 * @hide 70 */ 71 @IntDef(prefix = { "TYPE_" }, value = { 72 TYPE_FRAME_BEGIN, 73 TYPE_FRAME_END, 74 TYPE_UNTRACKED_DELAY, 75 TYPE_INTERNAL_TEMPERATURE, 76 TYPE_VEC3_CALIBRATION, 77 TYPE_SENSOR_PLACEMENT, 78 TYPE_SAMPLING 79 }) 80 @Retention(RetentionPolicy.SOURCE) 81 public @interface AdditionalInfoType {} 82 83 /** 84 * Mark the beginning of a set of additional info frames. 85 */ 86 public static final int TYPE_FRAME_BEGIN = 0; 87 88 /** 89 * Mark the end of a set of additional info frames. 90 */ 91 public static final int TYPE_FRAME_END = 1; 92 93 /** 94 * Untracked delay. Delays that are introduced by data processing, such as filtering, which is 95 * not taken into account by sensor timestamps. 96 * 97 * Payload: 98 * floatValues[0]: delay estimation in seconds 99 * floatValues[1]: delay estimation standard deviation 100 */ 101 public static final int TYPE_UNTRACKED_DELAY = 0x10000; 102 103 /** 104 * Internal temperature. Sensor hardware device internal temperature. 105 * 106 * Payload: 107 * floatValues[0]: internal temperature in Celsius. 108 */ 109 public static final int TYPE_INTERNAL_TEMPERATURE = 0x10001; 110 111 /** 112 * Vector calibration parameter. Calibration applied to a sensor with 3 elements vector output, 113 * such as accelerometer, gyro, etc. 114 * 115 * Payload: 116 * floatValues[0..11]: First 3 rows of a homogeneous matrix in row major order that captures 117 * any linear transformation, including rotation, scaling, shear, shift. 118 */ 119 public static final int TYPE_VEC3_CALIBRATION = 0x10002; 120 121 /** 122 * Sensor placement. Describes location and installation angle of the sensor device. 123 * 124 * Payload: 125 * floatValues[0..11]: First 3 rows of homogeneous matrix in row major order that describes 126 * the location and orientation of the sensor. Origin of reference will be the mobile device 127 * geometric sensor. Reference frame is defined as the same as Android sensor frame. 128 */ 129 public static final int TYPE_SENSOR_PLACEMENT = 0x10003; 130 131 /** 132 * Sampling parameter. Describes the raw sample period and estimated jitter of sample time in 133 * terms of standard deviation. 134 * 135 * Payload: 136 * floatValues[0]: raw sample period in seconds. 137 * floatValues[1]: standard deviation of sampling period. 138 */ 139 public static final int TYPE_SAMPLING = 0x10004; 140 141 /** 142 * Local geo-magnetic Field. 143 * 144 * Additional into to sensor hardware. Local geomagnetic field information based on 145 * device geo location. This type is primarily for for magnetic field calibration and rotation 146 * vector sensor fusion. 147 * 148 * float[3]: strength (uT), declination and inclination angle (rad). 149 * @hide 150 */ 151 public static final int TYPE_LOCAL_GEOMAGNETIC_FIELD = 0x30000; 152 153 /** 154 * Local gravity acceleration strength. 155 * 156 * Additional info to sensor hardware for accelerometer calibration. 157 * 158 * float: gravitational acceleration norm in m/s^2. 159 * @hide 160 */ 161 public static final int TYPE_LOCAL_GRAVITY = 0x30001; 162 163 /** 164 * Device dock state. 165 * 166 * Additional info to sensor hardware indicating dock states of device. 167 * 168 * int32_t: dock state following definition of {@link android.content.Intent#EXTRA_DOCK_STATE}. 169 * Undefined values are ignored. 170 * @hide 171 */ 172 public static final int TYPE_DOCK_STATE = 0x30002; 173 174 /** 175 * High performance mode. 176 * 177 * Additional info to sensor hardware. Device is able to use up more power and take more 178 * resources to improve throughput and latency in high performance mode. One possible use case 179 * is virtual reality, when sensor latency need to be carefully controlled. 180 * 181 * int32_t: 1 or 0, denoting device is in or out of high performance mode, respectively. 182 * Other values are ignored. 183 * @hide 184 */ 185 public static final int TYPE_HIGH_PERFORMANCE_MODE = 0x30003; 186 187 /** 188 * Magnetic field calibration hint. 189 * 190 * Additional info to sensor hardware. Device is notified when manually triggered magnetic field 191 * calibration procedure is started or stopped. The calibration procedure is assumed timed out 192 * after 1 minute from start, even if an explicit stop is not received. 193 * 194 * int32_t: 1 for calibration start, 0 for stop, other values are ignored. 195 * @hide 196 */ 197 public static final int TYPE_MAGNETIC_FIELD_CALIBRATION = 0x30004; 198 199 /** 200 * Custom sensor info: array of float values interpreted by sensor based on the type 201 * Any type between TYPE_CUSTOM_INFO <= info_type < TYPE_DEBUG_INFO may be 202 * used to send custom sensor info. 203 * @hide 204 */ 205 public static final int TYPE_CUSTOM_INFO = 0x10000000; 206 /** @hide */ 207 public static final int TYPE_DEBUG_INFO = 0x40000000; 208 209 SensorAdditionalInfo( 210 Sensor aSensor, int aType, int aSerial, int[] aIntValues, float[] aFloatValues) { 211 sensor = aSensor; 212 type = aType; 213 serial = aSerial; 214 intValues = aIntValues; 215 floatValues = aFloatValues; 216 } 217 218 /** @hide */ 219 public static SensorAdditionalInfo createLocalGeomagneticField( 220 float strength, float declination, float inclination) { 221 if (strength < 10 || strength > 100 // much beyond extreme values on earth 222 || declination < 0 || declination > Math.PI 223 || inclination < -Math.PI / 2 || inclination > Math.PI / 2) { 224 throw new IllegalArgumentException("Geomagnetic field info out of range"); 225 } 226 227 return new SensorAdditionalInfo( 228 null, TYPE_LOCAL_GEOMAGNETIC_FIELD, 0, 229 null, new float[] { strength, declination, inclination}); 230 } 231 /** @hide */ 232 public static SensorAdditionalInfo createCustomInfo(Sensor aSensor, int type, float[] data) { 233 if (type < TYPE_CUSTOM_INFO || type >= TYPE_DEBUG_INFO || aSensor == null) { 234 throw new IllegalArgumentException( 235 "invalid parameter(s): type: " + type + "; sensor: " + aSensor); 236 } 237 238 return new SensorAdditionalInfo(aSensor, type, 0, null, data); 239 } 240 } 241
