Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 1f9b32f0: Sensor documentation fixes.

Browse Source 
* commit '1f9b32f006f7c506d9df5bf73294710665746397':
  Sensor documentation fixes.
This commit is contained in:
Aravind Akella
2014-10-13 22:41:15 +00:00
committed by Android Git Automerger
parent 7666f90409 1f9b32f006
commit b78c16793b
3 changed files with 177 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
core/java/android/hardware/Sensor.java
View File

@@ -329,7 +329,11 @@ public final class Sensor {
* A sensor of this type triggers an event each time a step is taken by the user. The only
* allowed value to return is 1.0 and an event is generated for each step. Like with any other
* event, the timestamp indicates when the event (here the step) occurred, this corresponds to
* when the foot hit the ground, generating a high variation in acceleration.
* when the foot hit the ground, generating a high variation in acceleration. This sensor is
* only for detecting every individual step as soon as it is taken, for example to perform dead
* reckoning. If you only need aggregate number of steps taken over a period of time, register
* for {@link #TYPE_STEP_COUNTER} instead. It is defined as a
* {@link Sensor#REPORTING_MODE_SPECIAL_TRIGGER} sensor.
* <p>
* See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details.
*/
@@ -349,7 +353,12 @@ public final class Sensor {
* while activated. The value is returned as a float (with the fractional part set to zero) and
* is reset to zero only on a system reboot. The timestamp of the event is set to the time when
* the last step for that event was taken. This sensor is implemented in hardware and is
* expected to be low power.
* expected to be low power. If you want to continuously track the number of steps over a long
* period of time, do NOT unregister for this sensor, so that it keeps counting steps in the
* background even when the AP is in suspend mode and report the aggregate count when the AP
* is awake. Application needs to stay registered for this sensor because step counter does not
* count steps if it is not activated. This sensor is ideal for fitness tracking applications.
* It is defined as an {@link Sensor#REPORTING_MODE_ON_CHANGE} sensor.
* <p>
* See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details.
*/
@@ -750,31 +759,41 @@ public final class Sensor {
}
/**
* Returns whether this sensor is a wake-up sensor.
* Returns true if the sensor is a wake-up sensor.
* <p>
* Wake up sensors wake the application processor up when they have events to deliver. When a
* wake up sensor is registered to without batching enabled, each event will wake the
* application processor up.
* <b>Application Processor Power modes</b> <p>
* Application Processor(AP), is the processor on which applications run. When no wake lock is held
* and the user is not interacting with the device, this processor can enter a “Suspend” mode,
* reducing the power consumption by 10 times or more.
* </p>
* <p>
* When a wake up sensor is registered to with batching enabled, it
* wakes the application processor up when maxReportingLatency has elapsed or when the hardware
* FIFO storing the events from wake up sensors is getting full.
* <b>Non-wake-up sensors</b> <p>
* Non-wake-up sensors are sensors that do not wake the AP out of suspend to report data. While
* the AP is in suspend mode, the sensors continue to function and generate events, which are
* put in a hardware FIFO. The events in the FIFO are delivered to the application when the AP
* wakes up. If the FIFO was too small to store all events generated while the AP was in
* suspend mode, the older events are lost: the oldest data is dropped to accommodate the newer
* data. In the extreme case where the FIFO is non-existent {@code maxFifoEventCount() == 0},
* all events generated while the AP was in suspend mode are lost. Applications using
* non-wake-up sensors should usually:
* <ul>
* <li>Either unregister from the sensors when they do not need them, usually in the activity’s
* {@code onPause} method. This is the most common case.
* <li>Or realize that the sensors are consuming some power while the AP is in suspend mode and
* that even then, some events might be lost.
* </ul>
* </p>
* <p>
* Non-wake up sensors never wake the application processor up. Their events are only reported
* when the application processor is awake, for example because the application holds a wake
* lock, or another source woke the application processor up.
* <p>
* When a non-wake up sensor is registered to without batching enabled, the measurements made
* while the application processor is asleep might be lost and never returned.
* <p>
* When a non-wake up sensor is registered to with batching enabled, the measurements made while
* the application processor is asleep are stored in the hardware FIFO for non-wake up sensors.
* When this FIFO gets full, new events start overwriting older events. When the application
* then wakes up, the latest events are returned, and some old events might be lost. The number
* of events actually returned depends on the hardware FIFO size, as well as on what other
* sensors are activated. If losing sensor events is not acceptable during batching, you must
* use the wake-up version of the sensor.
* @return true if this is a wake up sensor, false otherwise.
* <b>Wake-up sensors</b> <p>
* In opposition to non-wake-up sensors, wake-up sensors ensure that their data is delivered
* independently of the state of the AP. While the AP is awake, the wake-up sensors behave
* like non-wake-up-sensors. When the AP is asleep, wake-up sensors wake up the AP to deliver
* events. That is, the AP will wake up and the sensor will deliver the events before the
* maximum reporting latency is elapsed or the hardware FIFO gets full. See {@link
* SensorManager#registerListener(SensorEventListener, Sensor, int, int)} for more details.
* </p>
*
* @return <code>true</code> if this is a wake-up sensor, <code>false</code> otherwise.
*/
public boolean isWakeUpSensor() {
return (mFlags & SENSOR_FLAG_WAKE_UP_SENSOR) != 0;

13
core/java/android/hardware/SensorEventListener2.java
View File

@@ -21,15 +21,16 @@ package android.hardware;
*/
public interface SensorEventListener2 extends SensorEventListener {
/**
* Called after flush() is completed. All the events in the batch at the point when
* the flush was called have been delivered to the applications registered for those
* sensor events. Flush Complete Events are sent ONLY to the application that has
* explicitly called flush(). If the hardware FIFO is flushed due to some other
* application calling flush(), flush complete event is not delivered to this application.
* Called after flush() is completed. All the events in the batch at the point when the flush
* was called have been delivered to the applications registered for those sensor events. In
* {@link android.os.Build.VERSION_CODES#KITKAT}, applications may receive flush complete events
* even if some other application has called flush() on the same sensor. Starting with
* {@link android.os.Build.VERSION_CODES#LOLLIPOP}, flush Complete events are sent ONLY to the
* application that has explicitly called flush(). If the hardware FIFO is flushed due to some
* other application calling flush(), flush complete event is not delivered to this application.
* <p>
*
* @param sensor The {@link android.hardware.Sensor Sensor} on which flush was called.
*
* @see android.hardware.SensorManager#flush(SensorEventListener)
*/
public void onFlushCompleted(Sensor sensor);

251
core/java/android/hardware/SensorManager.java
View File

@@ -626,73 +626,90 @@ public abstract class SensorManager {
protected abstract void unregisterListenerImpl(SensorEventListener listener, Sensor sensor);
/**
* Registers a {@link android.hardware.SensorEventListener
* SensorEventListener} for the given sensor.
*
* <p class="note"></p>
* Note: Don't use this method with a one shot trigger sensor such as
* {@link Sensor#TYPE_SIGNIFICANT_MOTION}.
* Use {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead.
* Registers a {@link android.hardware.SensorEventListener SensorEventListener} for the given
* sensor at the given sampling frequency.
* <p>
* The events will be delivered to the provided {@code SensorEventListener} as soon as they are
* available. To reduce the power consumption, applications can use
* {@link #registerListener(SensorEventListener, Sensor, int, int)} instead and specify a
* positive non-zero maximum reporting latency.
* </p>
* <p>
* In the case of non-wake-up sensors, the events are only delivered while the Application
* Processor (AP) is not in suspend mode. See {@link Sensor#isWakeUpSensor()} for more details.
* To ensure delivery of events from non-wake-up sensors even when the screen is OFF, the
* application registering to the sensor must hold a partial wake-lock to keep the AP awake,
* otherwise some events might be lost while the AP is asleep. Note that although events might
* be lost while the AP is asleep, the sensor will still consume power if it is not explicitly
* deactivated by the application. Applications must unregister their {@code
* SensorEventListener}s in their activity's {@code onPause()} method to avoid consuming power
* while the device is inactive. See {@link #registerListener(SensorEventListener, Sensor, int,
* int)} for more details on hardware FIFO (queueing) capabilities and when some sensor events
* might be lost.
* </p>
* <p>
* In the case of wake-up sensors, each event generated by the sensor will cause the AP to
* wake-up, ensuring that each event can be delivered. Because of this, registering to a wake-up
* sensor has very significant power implications. Call {@link Sensor#isWakeUpSensor()} to check
* whether a sensor is a wake-up sensor. See
* {@link #registerListener(SensorEventListener, Sensor, int, int)} for information on how to
* reduce the power impact of registering to wake-up sensors.
* </p>
* <p class="note">
* Note: Don't use this method with one-shot trigger sensors such as
* {@link Sensor#TYPE_SIGNIFICANT_MOTION}. Use
* {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead. Use
* {@link Sensor#getReportingMode()} to obtain the reporting mode of a given sensor.
* </p>
*
* @param listener
* A {@link android.hardware.SensorEventListener SensorEventListener}
* object.
*
* @param sensor
* The {@link android.hardware.Sensor Sensor} to register to.
*
* @param rateUs
* The rate {@link android.hardware.SensorEvent sensor events} are
* delivered at. This is only a hint to the system. Events may be
* received faster or slower than the specified rate. Usually events
* are received faster. The value must be one of
* {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST}
* or, the desired delay between events in microseconds.
* Specifying the delay in microseconds only works from Android
* 2.3 (API level 9) onwards. For earlier releases, you must use
* one of the {@code SENSOR_DELAY_*} constants.
*
* @return <code>true</code> if the sensor is supported and successfully
* enabled.
*
* @param listener A {@link android.hardware.SensorEventListener SensorEventListener} object.
* @param sensor The {@link android.hardware.Sensor Sensor} to register to.
* @param samplingPeriodUs The rate {@link android.hardware.SensorEvent sensor events} are
* delivered at. This is only a hint to the system. Events may be received faster or
* slower than the specified rate. Usually events are received faster. The value must
* be one of {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST} or, the desired delay
* between events in microseconds. Specifying the delay in microseconds only works
* from Android 2.3 (API level 9) onwards. For earlier releases, you must use one of
* the {@code SENSOR_DELAY_*} constants.
* @return <code>true</code> if the sensor is supported and successfully enabled.
* @see #registerListener(SensorEventListener, Sensor, int, Handler)
* @see #unregisterListener(SensorEventListener)
* @see #unregisterListener(SensorEventListener, Sensor)
*
*/
public boolean registerListener(SensorEventListener listener, Sensor sensor, int rateUs) {
return registerListener(listener, sensor, rateUs, null);
public boolean registerListener(SensorEventListener listener, Sensor sensor,
int samplingPeriodUs) {
return registerListener(listener, sensor, samplingPeriodUs, null);
}
/**
* Enables batch mode for a sensor with the given rate and maxBatchReportLatency. If the
* underlying hardware does not support batch mode, this defaults to
* {@link #registerListener(SensorEventListener, Sensor, int)} and other parameters are
* ignored. In non-batch mode, all sensor events must be reported as soon as they are detected.
* While in batch mode, sensor events do not need to be reported as soon as they are detected.
* They can be temporarily stored in batches and reported in batches, as long as no event is
* delayed by more than "maxBatchReportLatency" microseconds. That is, all events since the
* previous batch are recorded and returned all at once. This allows to reduce the amount of
* interrupts sent to the SoC, and allows the SoC to switch to a lower power state (Idle) while
* the sensor is capturing and batching data.
* Registers a {@link android.hardware.SensorEventListener SensorEventListener} for the given
* sensor at the given sampling frequency and the given maximum reporting latency.
* <p>
* Registering to a sensor in batch mode will not prevent the SoC from going to suspend mode. In
* this case, the sensor will continue to gather events and store it in a hardware FIFO. If the
* FIFO gets full before the AP wakes up again, some events will be lost, as the older events
* get overwritten by new events in the hardware FIFO. This can be avoided by holding a wake
* lock. If the application holds a wake lock, the SoC will not go to suspend mode, so no events
* will be lost, as the events will be reported before the FIFO gets full.
* </p>
* <p>
* Batching is always best effort. If a different application requests updates in continuous
* mode, this application will also get events in continuous mode. Batch mode updates can be
* unregistered by calling {@link #unregisterListener(SensorEventListener)}.
* This function is similar to {@link #registerListener(SensorEventListener, Sensor, int)} but
* it allows events to stay temporarily in the hardware FIFO (queue) before being delivered. The
* events can be stored in the hardware FIFO up to {@code maxReportLatencyUs} microseconds. Once
* one of the events in the FIFO needs to be reported, all of the events in the FIFO are
* reported sequentially. This means that some events will be reported before the maximum
* reporting latency has elapsed.
* </p><p>
* When {@code maxReportLatencyUs} is 0, the call is equivalent to a call to
* {@link #registerListener(SensorEventListener, Sensor, int)}, as it requires the events to be
* delivered as soon as possible.
* </p><p>
* When {@code sensor.maxFifoEventCount()} is 0, the sensor does not use a FIFO, so the call
* will also be equivalent to {@link #registerListener(SensorEventListener, Sensor, int)}.
* </p><p>
* Setting {@code maxReportLatencyUs} to a positive value allows to reduce the number of
* interrupts the AP (Application Processor) receives, hence reducing power consumption, as the
* AP can switch to a lower power state while the sensor is capturing the data. This is
* especially important when registering to wake-up sensors, for which each interrupt causes the
* AP to wake up if it was in suspend mode. See {@link Sensor#isWakeUpSensor()} for more
* information on wake-up sensors.
* </p>
* <p class="note">
* </p>
* Note: Don't use this method with a one shot trigger sensor such as
* Note: Don't use this method with one-shot trigger sensors such as
* {@link Sensor#TYPE_SIGNIFICANT_MOTION}. Use
* {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead. </p>
*
@@ -701,118 +718,104 @@ public abstract class SensorManager {
* flush complete notifications, it should register with
* {@link android.hardware.SensorEventListener SensorEventListener2} instead.
* @param sensor The {@link android.hardware.Sensor Sensor} to register to.
* @param rateUs The desired delay between two consecutive events in microseconds. This is only
* a hint to the system. Events may be received faster or slower than the specified
* rate. Usually events are received faster. Can be one of
* @param samplingPeriodUs The desired delay between two consecutive events in microseconds.
* This is only a hint to the system. Events may be received faster or slower than
* the specified rate. Usually events are received faster. Can be one of
* {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, {@link #SENSOR_DELAY_FASTEST} or the delay in
* microseconds.
* @param maxBatchReportLatencyUs An event in the batch can be delayed by at most
* maxBatchReportLatency microseconds. More events can be batched if this value is
* large. If this is set to zero, batch mode is disabled and events are delivered in
* continuous mode as soon as they are available which is equivalent to calling
* @param maxReportLatencyUs Maximum time in microseconds that events can be delayed before
* being reported to the application. A large value allows reducing the power
* consumption associated with the sensor. If maxReportLatencyUs is set to zero,
* events are delivered as soon as they are available, which is equivalent to calling
* {@link #registerListener(SensorEventListener, Sensor, int)}.
* @return <code>true</code> if batch mode is successfully enabled for this sensor,
* <code>false</code> otherwise.
* @return <code>true</code> if the sensor is supported and successfully enabled.
* @see #registerListener(SensorEventListener, Sensor, int)
* @see #unregisterListener(SensorEventListener)
* @see #flush(SensorEventListener)
*/
public boolean registerListener(SensorEventListener listener, Sensor sensor, int rateUs,
int maxBatchReportLatencyUs) {
int delay = getDelay(rateUs);
return registerListenerImpl(listener, sensor, delay, null, maxBatchReportLatencyUs, 0);
public boolean registerListener(SensorEventListener listener, Sensor sensor,
int samplingPeriodUs, int maxReportLatencyUs) {
int delay = getDelay(samplingPeriodUs);
return registerListenerImpl(listener, sensor, delay, null, maxReportLatencyUs, 0);
}
/**
* Registers a {@link android.hardware.SensorEventListener SensorEventListener} for the given
* sensor. Events are delivered in continuous mode as soon as they are available. To reduce the
* battery usage, use {@link #registerListener(SensorEventListener, Sensor, int, int)} which
* enables batch mode for the sensor.
*
* <p class="note"></p>
* Note: Don't use this method with a one shot trigger sensor such as
* {@link Sensor#TYPE_SIGNIFICANT_MOTION}.
* Use {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead.
* power consumption, applications can use
* {@link #registerListener(SensorEventListener, Sensor, int, int)} instead and specify a
* positive non-zero maximum reporting latency.
* <p class="note">
* </p>
* Note: Don't use this method with a one shot trigger sensor such as
* {@link Sensor#TYPE_SIGNIFICANT_MOTION}. Use
* {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead. </p>
*
* @param listener
* A {@link android.hardware.SensorEventListener SensorEventListener}
* object.
*
* @param sensor
* The {@link android.hardware.Sensor Sensor} to register to.
*
* @param rateUs
* The rate {@link android.hardware.SensorEvent sensor events} are
* delivered at. This is only a hint to the system. Events may be
* received faster or slower than the specified rate. Usually events
* are received faster. The value must be one of
* {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST}.
* or, the desired delay between events in microseconds.
* Specifying the delay in microseconds only works from Android
* 2.3 (API level 9) onwards. For earlier releases, you must use
* one of the {@code SENSOR_DELAY_*} constants.
*
* @param handler
* The {@link android.os.Handler Handler} the
* {@link android.hardware.SensorEvent sensor events} will be
* delivered to.
*
* @param listener A {@link android.hardware.SensorEventListener SensorEventListener} object.
* @param sensor The {@link android.hardware.Sensor Sensor} to register to.
* @param samplingPeriodUs The rate {@link android.hardware.SensorEvent sensor events} are
* delivered at. This is only a hint to the system. Events may be received faster or
* slower than the specified rate. Usually events are received faster. The value must
* be one of {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST} or, the desired
* delay between events in microseconds. Specifying the delay in microseconds only
* works from Android 2.3 (API level 9) onwards. For earlier releases, you must use
* one of the {@code SENSOR_DELAY_*} constants.
* @param handler The {@link android.os.Handler Handler} the {@link android.hardware.SensorEvent
* sensor events} will be delivered to.
* @return <code>true</code> if the sensor is supported and successfully enabled.
*
* @see #registerListener(SensorEventListener, Sensor, int)
* @see #unregisterListener(SensorEventListener)
* @see #unregisterListener(SensorEventListener, Sensor)
*/
public boolean registerListener(SensorEventListener listener, Sensor sensor, int rateUs,
Handler handler) {
int delay = getDelay(rateUs);
public boolean registerListener(SensorEventListener listener, Sensor sensor,
int samplingPeriodUs, Handler handler) {
int delay = getDelay(samplingPeriodUs);
return registerListenerImpl(listener, sensor, delay, handler, 0, 0);
}
/**
* Enables batch mode for a sensor with the given rate and maxBatchReportLatency.
* Registers a {@link android.hardware.SensorEventListener SensorEventListener} for the given
* sensor at the given sampling frequency and the given maximum reporting latency.
*
* @param listener A {@link android.hardware.SensorEventListener SensorEventListener} object
* that will receive the sensor events. If the application is interested in receiving
* flush complete notifications, it should register with
* {@link android.hardware.SensorEventListener SensorEventListener2} instead.
* @param sensor The {@link android.hardware.Sensor Sensor} to register to.
* @param rateUs The desired delay between two consecutive events in microseconds. This is only
* a hint to the system. Events may be received faster or slower than the specified
* rate. Usually events are received faster. Can be one of
* @param samplingPeriodUs The desired delay between two consecutive events in microseconds.
* This is only a hint to the system. Events may be received faster or slower than
* the specified rate. Usually events are received faster. Can be one of
* {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
* {@link #SENSOR_DELAY_GAME}, {@link #SENSOR_DELAY_FASTEST} or the delay in
* microseconds.
* @param maxBatchReportLatencyUs An event in the batch can be delayed by at most
* maxBatchReportLatency microseconds. More events can be batched if this value is
* large. If this is set to zero, batch mode is disabled and events are delivered in
* continuous mode as soon as they are available which is equivalent to calling
* @param maxReportLatencyUs Maximum time in microseconds that events can be delayed before
* being reported to the application. A large value allows reducing the power
* consumption associated with the sensor. If maxReportLatencyUs is set to zero,
* events are delivered as soon as they are available, which is equivalent to calling
* {@link #registerListener(SensorEventListener, Sensor, int)}.
* @param handler The {@link android.os.Handler Handler} the
* {@link android.hardware.SensorEvent sensor events} will be delivered to.
*
* @return <code>true</code> if batch mode is successfully enabled for this sensor,
* <code>false</code> otherwise.
* @param handler The {@link android.os.Handler Handler} the {@link android.hardware.SensorEvent
* sensor events} will be delivered to.
* @return <code>true</code> if the sensor is supported and successfully enabled.
* @see #registerListener(SensorEventListener, Sensor, int, int)
*/
public boolean registerListener(SensorEventListener listener, Sensor sensor, int rateUs,
int maxBatchReportLatencyUs, Handler handler) {
int delayUs = getDelay(rateUs);
return registerListenerImpl(listener, sensor, delayUs, handler, maxBatchReportLatencyUs, 0);
public boolean registerListener(SensorEventListener listener, Sensor sensor, int samplingPeriodUs,
int maxReportLatencyUs, Handler handler) {
int delayUs = getDelay(samplingPeriodUs);
return registerListenerImpl(listener, sensor, delayUs, handler, maxReportLatencyUs, 0);
}
/** @hide */
protected abstract boolean registerListenerImpl(SensorEventListener listener, Sensor sensor,
int delayUs, Handler handler, int maxBatchReportLatencyUs, int reservedFlags);
int delayUs, Handler handler, int maxReportLatencyUs, int reservedFlags);
/**
* Flushes the batch FIFO of all the sensors registered for this listener. If there are events
* in the FIFO of the sensor, they are returned as if the batch timeout in the FIFO of the
* sensors had expired. Events are returned in the usual way through the SensorEventListener.
* This call doesn't affect the batch timeout for this sensor. This call is asynchronous and
* Flushes the FIFO of all the sensors registered for this listener. If there are events
* in the FIFO of the sensor, they are returned as if the maxReportLantecy of the FIFO has
* expired. Events are returned in the usual way through the SensorEventListener.
* This call doesn't affect the maxReportLantecy for this sensor. This call is asynchronous and
* returns immediately.
* {@link android.hardware.SensorEventListener2#onFlushCompleted onFlushCompleted} is called
* after all the events in the batch at the time of calling this method have been delivered