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 /** 129 * Sensors defined in this range [{@link #SENSOR_TYPE_VENDOR_EXTENSION_START}, 130 * {@link #SENSOR_TYPE_VENDOR_EXTENSION_END}] are for vendors and should be used only 131 * by the system app to access sensors not defined as standard types. 132 * Sensors supported in this range can vary depending on car models/manufacturers. 133 * Third-party apps should not use sensors in this range as they are not compatible across 134 * all cars; third-party apps that attempt to access a sensor in this range trigger a 135 * security exception (as access is restricted to system apps). 136 * 137 * @hide 138 */ 139 public static final int SENSOR_TYPE_VENDOR_EXTENSION_START = 0x60000000; 140 /** @hide */ 141 public static final int SENSOR_TYPE_VENDOR_EXTENSION_END = 0x6fffffff; 142 143 /** @hide */ 144 @IntDef({ 145 SENSOR_TYPE_COMPASS, 146 SENSOR_TYPE_CAR_SPEED, 147 SENSOR_TYPE_RPM, 148 SENSOR_TYPE_ODOMETER, 149 SENSOR_TYPE_FUEL_LEVEL, 150 SENSOR_TYPE_PARKING_BRAKE, 151 SENSOR_TYPE_GEAR, 152 SENSOR_TYPE_NIGHT, 153 SENSOR_TYPE_LOCATION, 154 SENSOR_TYPE_DRIVING_STATUS, 155 SENSOR_TYPE_ENVIRONMENT, 156 SENSOR_TYPE_ACCELEROMETER, 157 SENSOR_TYPE_GPS_SATELLITE, 158 SENSOR_TYPE_GYROSCOPE 159 }) 160 @Retention(RetentionPolicy.SOURCE) 161 public @interface SensorType {} 162 163 /** Read sensor at the default normal rate set for each sensors. This is default rate. */ 164 public static final int SENSOR_RATE_NORMAL = 3; 165 /**@hide*/ 166 public static final int SENSOR_RATE_UI = 2; 167 /**@hide*/ 168 public static final int SENSOR_RATE_FAST = 1; 169 /** Read sensor at the maximum rate. Actual rate will be different depending on the sensor. */ 170 public static final int SENSOR_RATE_FASTEST = 0; 171 172 /** @hide */ 173 @IntDef({ 174 SENSOR_RATE_NORMAL, 175 SENSOR_RATE_UI, 176 SENSOR_RATE_FAST, 177 SENSOR_RATE_FASTEST 178 }) 179 @Retention(RetentionPolicy.SOURCE) 180 public @interface SensorRate {} 181 182 /** 183 * Listener for car sensor data change. 184 * Callbacks are called in the Looper context. 185 */ 186 public interface OnSensorChangedListener { 187 /** 188 * Called when there is new sensor data from car. 189 * @param manager The manager the listener is attached to. Useful if the app wished to 190 * unregister. 191 * @param event Incoming sensor event for the given sensor type. 192 */ onSensorChanged(final CarSensorManager manager, final CarSensorEvent event)193 void onSensorChanged(final CarSensorManager manager, final CarSensorEvent event); 194 } 195 196 /** 197 * Get the list of CarSensors available in the connected car. 198 * @return Array of all sensor types supported. 199 * @throws CarNotConnectedException if the connection to the car service has been lost. 200 */ getSupportedSensors()201 public abstract int[] getSupportedSensors() throws CarNotConnectedException; 202 203 /** 204 * Indicate support for a given sensor. 205 * @param sensorType 206 * @return Returns {@code true} if the sensor is supported. 207 * @throws CarNotConnectedException if the connection to the car service has been lost. 208 */ isSensorSupported(@ensorType int sensorType)209 public abstract boolean isSensorSupported(@SensorType int sensorType) 210 throws CarNotConnectedException; 211 212 /** 213 * Register {@link OnSensorChangedListener} to get repeated sensor updates. Can register 214 * multiple listeners for a single sensor or use the same listener for different 215 * sensors. If the same listener is registered again for the same sensor, it is ignored or 216 * updated (depending on the rate). 217 * <p> 218 * The {@link OnSensorChangedListener} is the identifier for the request and the same 219 * instance must be passed into {@link #removeListener(OnSensorChangedListener)}. 220 * <p> 221 * 222 * @param sensorType Sensor type to subscribe. 223 * @param rate How fast sensor events are delivered. Should be one of 224 * {@link #SENSOR_RATE_FASTEST} or {@link #SENSOR_RATE_NORMAL}. Rate may not be 225 * respected, especially when the same sensor is registered with a different listener 226 * and with different rates. 227 * @return Returns {@code true} if the sensor was successfully enabled. 228 * @throws CarNotConnectedException if the connection to the car service has been lost. 229 * @throws IllegalArgumentException if wrong argument (such as wrong rate). 230 * @throws SecurityException if missing the appropriate permission. 231 */ 232 @RequiresPermission(anyOf={Manifest.permission.ACCESS_FINE_LOCATION, Car.PERMISSION_SPEED, 233 Car.PERMISSION_MILEAGE, Car.PERMISSION_FUEL}, conditional=true) addListener(OnSensorChangedListener listener, @SensorType int sensorType, @SensorRate int rate)234 public abstract boolean addListener(OnSensorChangedListener listener, 235 @SensorType int sensorType, @SensorRate int rate) 236 throws CarNotConnectedException, IllegalArgumentException; 237 238 /** 239 * Stop getting sensor updates for the given listener. If there are multiple registrations for 240 * this listener, all listening is stopped. 241 * @param listener The listener to remove. 242 */ removeListener(OnSensorChangedListener listener)243 public abstract void removeListener(OnSensorChangedListener listener); 244 245 /** 246 * Stop getting sensor updates for the given listener and sensor. If the same listener is used 247 * for other sensors, those subscriptions are not affected. 248 * @param listener The listener to remove. 249 * @param sensorType The type to stop receiving notifications for. 250 */ removeListener(OnSensorChangedListener listener, @SensorType int sensorType)251 public abstract void removeListener(OnSensorChangedListener listener, 252 @SensorType int sensorType); 253 254 /** 255 * Get the most recent CarSensorEvent for the given type. 256 * @param type A sensor to request. 257 * @return null if no sensor update since connection to the car. 258 * @throws CarNotConnectedException if the connection to the car service has been lost. 259 */ getLatestSensorEvent(@ensorType int type)260 public abstract CarSensorEvent getLatestSensorEvent(@SensorType int type) 261 throws CarNotConnectedException; 262 } 263