1 /* 2 * Copyright (C) 2015 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.support.car.hardware; 18 19 import android.Manifest; 20 import android.support.annotation.IntDef; 21 import android.support.annotation.RequiresPermission; 22 import android.support.car.Car; 23 import android.support.car.CarManagerBase; 24 import android.support.car.CarNotConnectedException; 25 26 import java.lang.annotation.Retention; 27 import java.lang.annotation.RetentionPolicy; 28 29 /** 30 * Enables applications to monitor car sensor data. Applications register listeners to this 31 * manager to subscribe to individual sensor streams using the SENSOR_TYPE_* constants as the 32 * keys. Data points are returned as {@link CarSensorEvent} objects that have translations for 33 * many built-in data types. For vendor extension streams, interpret data based on 34 * vendor-provided documentation. 35 */ 36 public abstract class CarSensorManager implements CarManagerBase { 37 /** 38 * Represent the direction of the car as an angle in degrees measured clockwise with 0 degree 39 * pointing North. Sensor data in {@link CarSensorEvent} is a float (floatValues[0]). 40 */ 41 public static final int SENSOR_TYPE_COMPASS = 1; 42 /** 43 * Represent vehicle speed in meters per second (m/s). Sensor data in 44 * {@link CarSensorEvent} is a float >= 0. Requires {@link Car#PERMISSION_SPEED} permission. 45 * @hide 46 */ 47 public static final int SENSOR_TYPE_CAR_SPEED = 2; 48 /** 49 * Represent the engine RPM of the car. Sensor data in {@link CarSensorEvent} is a float. 50 * @hide 51 */ 52 public static final int SENSOR_TYPE_RPM = 3; 53 /** 54 * Represent the total travel distance of the car in kilometers. Sensor data is a float. 55 * Requires {@link Car#PERMISSION_MILEAGE} permission. 56 * @hide 57 */ 58 public static final int SENSOR_TYPE_ODOMETER = 4; 59 /** 60 * Represent the fuel level of the car. In {@link CarSensorEvent}, floatValues[{@link 61 * CarSensorEvent#INDEX_FUEL_LEVEL_IN_PERCENTILE}] represents fuel level in percentile (0 to 62 * 100) while floatValues[{@link CarSensorEvent#INDEX_FUEL_LEVEL_IN_DISTANCE}] represents 63 * estimated range in kilometers with the remaining fuel. The gas mileage used for the 64 * estimation may not represent the current driving condition. Requires {@link 65 * Car#PERMISSION_FUEL} permission. 66 * @hide 67 */ 68 public static final int SENSOR_TYPE_FUEL_LEVEL = 5; 69 /** 70 * Represent the current status of parking brake. Sensor data in {@link CarSensorEvent} is in 71 * intValues[0]. A value of 1 indicates the parking brake is engaged; a value of 0 indicates 72 * the parking brake is not engaged. 73 * For this sensor, rate in {@link #addListener(OnSensorChangedListener, int, int)} is 74 * ignored and all changes are notified. 75 */ 76 public static final int SENSOR_TYPE_PARKING_BRAKE = 6; 77 /** 78 * Represent the current position of transmission gear. Sensor data in {@link 79 * CarSensorEvent} is in intValues[0]. For the meaning of the value, check {@link 80 * CarSensorEvent#GEAR_NEUTRAL} and other GEAR_*. 81 * @hide 82 */ 83 public static final int SENSOR_TYPE_GEAR = 7; 84 85 /** @hide */ 86 public static final int SENSOR_TYPE_RESERVED8 = 8; 87 88 /** 89 * Represent the current status of the day/night sensor. Sensor data is in intValues[0]. 90 */ 91 public static final int SENSOR_TYPE_NIGHT = 9; 92 /** 93 * Represent the location. Sensor data is floatValues. 94 * @hide 95 */ 96 public static final int SENSOR_TYPE_LOCATION = 10; 97 /** 98 * Represent the current driving status of car. Different user interactions should be used 99 * depending on the current driving status. Driving status is in intValues[0]. 100 */ 101 public static final int SENSOR_TYPE_DRIVING_STATUS = 11; 102 /** 103 * Environment (such as temperature and pressure). 104 * @hide 105 */ 106 public static final int SENSOR_TYPE_ENVIRONMENT = 12; 107 /** @hide */ 108 public static final int SENSOR_TYPE_RESERVED13 = 13; 109 /** @hide */ 110 public static final int SENSOR_TYPE_ACCELEROMETER = 14; 111 /** @hide */ 112 public static final int SENSOR_TYPE_RESERVED15 = 15; 113 /** @hide */ 114 public static final int SENSOR_TYPE_RESERVED16 = 16; 115 /** @hide */ 116 public static final int SENSOR_TYPE_GPS_SATELLITE = 17; 117 /** @hide */ 118 public static final int SENSOR_TYPE_GYROSCOPE = 18; 119 /** @hide */ 120 public static final int SENSOR_TYPE_RESERVED19 = 19; 121 /** @hide */ 122 public static final int SENSOR_TYPE_RESERVED20 = 20; 123 /** @hide */ 124 public static final int SENSOR_TYPE_RESERVED21 = 21; 125 /** @hide */ 126 public static final int SENSOR_TYPE_RESERVED22 = 22; 127 /** 128 * Represents wheel distance in millimeters. Some cars may not have individual sensors on each 129 * wheel. If a value is not available, -1 will be reported. The wheel distance accumulates 130 * over time. 131 * Requires {@link Car#PERMISSION_MILEAGE} permission. 132 */ 133 public static final int SENSOR_TYPE_WHEEL_TICK_DISTANCE = 23; 134 /** 135 * Set to true when ABS is active. This sensor is event driven. 136 * Requires {@link Car#PERMISSION_VEHICLE_DYNAMICS_STATE} permission. 137 */ 138 public static final int SENSOR_TYPE_ABS_ACTIVE = 24; 139 /** 140 * Set to true when traction control is active. This sensor is event driven. 141 * Requires {@link Car#PERMISSION_VEHICLE_DYNAMICS_STATE} permission. 142 */ 143 public static final int SENSOR_TYPE_TRACTION_CONTROL_ACTIVE = 25; 144 145 /** 146 * Sensors defined in this range [{@link #SENSOR_TYPE_VENDOR_EXTENSION_START}, 147 * {@link #SENSOR_TYPE_VENDOR_EXTENSION_END}] are for vendors and should be used only 148 * by the system app to access sensors not defined as standard types. 149 * Sensors supported in this range can vary depending on car models/manufacturers. 150 * Third-party apps should not use sensors in this range as they are not compatible across 151 * all cars; third-party apps that attempt to access a sensor in this range trigger a 152 * security exception (as access is restricted to system apps). 153 * 154 * @hide 155 */ 156 public static final int SENSOR_TYPE_VENDOR_EXTENSION_START = 0x60000000; 157 /** @hide */ 158 public static final int SENSOR_TYPE_VENDOR_EXTENSION_END = 0x6fffffff; 159 160 /** @hide */ 161 @IntDef({ 162 SENSOR_TYPE_COMPASS, 163 SENSOR_TYPE_CAR_SPEED, 164 SENSOR_TYPE_RPM, 165 SENSOR_TYPE_ODOMETER, 166 SENSOR_TYPE_FUEL_LEVEL, 167 SENSOR_TYPE_PARKING_BRAKE, 168 SENSOR_TYPE_GEAR, 169 SENSOR_TYPE_NIGHT, 170 SENSOR_TYPE_LOCATION, 171 SENSOR_TYPE_DRIVING_STATUS, 172 SENSOR_TYPE_ENVIRONMENT, 173 SENSOR_TYPE_ACCELEROMETER, 174 SENSOR_TYPE_GPS_SATELLITE, 175 SENSOR_TYPE_GYROSCOPE, 176 SENSOR_TYPE_WHEEL_TICK_DISTANCE, 177 SENSOR_TYPE_ABS_ACTIVE, 178 SENSOR_TYPE_TRACTION_CONTROL_ACTIVE 179 }) 180 @Retention(RetentionPolicy.SOURCE) 181 public @interface SensorType {} 182 183 /** Read sensor at the default normal rate set for each sensors. This is default rate. */ 184 public static final int SENSOR_RATE_NORMAL = 3; 185 /**@hide*/ 186 public static final int SENSOR_RATE_UI = 2; 187 /**@hide*/ 188 public static final int SENSOR_RATE_FAST = 1; 189 /** Read sensor at the maximum rate. Actual rate will be different depending on the sensor. */ 190 public static final int SENSOR_RATE_FASTEST = 0; 191 192 /** @hide */ 193 @IntDef({ 194 SENSOR_RATE_NORMAL, 195 SENSOR_RATE_UI, 196 SENSOR_RATE_FAST, 197 SENSOR_RATE_FASTEST 198 }) 199 @Retention(RetentionPolicy.SOURCE) 200 public @interface SensorRate {} 201 202 /** 203 * Listener for car sensor data change. 204 * Callbacks are called in the Looper context. 205 */ 206 public interface OnSensorChangedListener { 207 /** 208 * Called when there is new sensor data from car. 209 * @param manager The manager the listener is attached to. Useful if the app wished to 210 * unregister. 211 * @param event Incoming sensor event for the given sensor type. 212 */ 213 void onSensorChanged(final CarSensorManager manager, final CarSensorEvent event); 214 } 215 216 /** 217 * Get the list of CarSensors available in the connected car. 218 * @return Array of all sensor types supported. 219 * @throws CarNotConnectedException if the connection to the car service has been lost. 220 */ 221 public abstract int[] getSupportedSensors() throws CarNotConnectedException; 222 223 /** 224 * Indicate support for a given sensor. 225 * @param sensorType 226 * @return Returns {@code true} if the sensor is supported. 227 * @throws CarNotConnectedException if the connection to the car service has been lost. 228 */ 229 public abstract boolean isSensorSupported(@SensorType int sensorType) 230 throws CarNotConnectedException; 231 232 /** 233 * Register {@link OnSensorChangedListener} to get repeated sensor updates. Can register 234 * multiple listeners for a single sensor or use the same listener for different 235 * sensors. If the same listener is registered again for the same sensor, it is ignored or 236 * updated (depending on the rate). 237 * <p> 238 * The {@link OnSensorChangedListener} is the identifier for the request and the same 239 * instance must be passed into {@link #removeListener(OnSensorChangedListener)}. 240 * <p> 241 * 242 * @param sensorType Sensor type to subscribe. 243 * @param rate How fast sensor events are delivered. Should be one of 244 * {@link #SENSOR_RATE_FASTEST} or {@link #SENSOR_RATE_NORMAL}. Rate may not be 245 * respected, especially when the same sensor is registered with a different listener 246 * and with different rates. 247 * @return Returns {@code true} if the sensor was successfully enabled. 248 * @throws CarNotConnectedException if the connection to the car service has been lost. 249 * @throws IllegalArgumentException if wrong argument (such as wrong rate). 250 * @throws SecurityException if missing the appropriate permission. 251 */ 252 @RequiresPermission(anyOf={Manifest.permission.ACCESS_FINE_LOCATION, Car.PERMISSION_SPEED, 253 Car.PERMISSION_MILEAGE, Car.PERMISSION_FUEL, Car.PERMISSION_VEHICLE_DYNAMICS_STATE}, 254 conditional=true) 255 public abstract boolean addListener(OnSensorChangedListener listener, 256 @SensorType int sensorType, @SensorRate int rate) 257 throws CarNotConnectedException, IllegalArgumentException; 258 259 /** 260 * Stop getting sensor updates for the given listener. If there are multiple registrations for 261 * this listener, all listening is stopped. 262 * @param listener The listener to remove. 263 */ 264 public abstract void removeListener(OnSensorChangedListener listener); 265 266 /** 267 * Stop getting sensor updates for the given listener and sensor. If the same listener is used 268 * for other sensors, those subscriptions are not affected. 269 * @param listener The listener to remove. 270 * @param sensorType The type to stop receiving notifications for. 271 */ 272 public abstract void removeListener(OnSensorChangedListener listener, 273 @SensorType int sensorType); 274 275 /** 276 * Get the most recent CarSensorEvent for the given type. 277 * @param type A sensor to request. 278 * @return null if no sensor update since connection to the car. 279 * @throws CarNotConnectedException if the connection to the car service has been lost. 280 */ 281 public abstract CarSensorEvent getLatestSensorEvent(@SensorType int type) 282 throws CarNotConnectedException; 283 284 /** 285 * Get the config data for the given type. 286 * @param sensor type to request 287 * @return CarSensorConfig object 288 * @throws CarNotConnectedException if the connection to the car service has been lost. 289 * @hide 290 */ 291 public abstract CarSensorConfig getSensorConfig(@SensorType int type) 292 throws CarNotConnectedException; 293 294 } 295
