11 Power Management

The com.oracle.deviceaccess.power package contains interfaces and classes for power management of peripheral devices. A Peripheral implementing class may implement the PowerManaged interface if the underlying peripheral device supports some form of power management and saving states that can be mapped to the states defined by this API.

Example 11-1 demonstrates how to use the power management API.

Example 11-1 Using the Power Management APIs

import com.oracle.deviceaccess.Peripheral;
import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.PeripheralNotAvailableException;
import com.oracle.deviceaccess.PeripheralNotFoundException;
import com.oracle.deviceaccess.adc.ADCChannel;
import com.oracle.deviceaccess.adc.MonitoringEvent;
import com.oracle.deviceaccess.adc.MonitoringListener;
import com.oracle.deviceaccess.power.PowerManaged;
import com.oracle.deviceaccess.power.PowerSavingHandler;
import java.io.IOException;
 
class SignalLevelMonitor implements MonitoringListener, PowerSavingHandler {
 
    private ADCChannel channel = null;
    private boolean inRange = false;
 
    public void start(int channelID, int low, int high) throws
            IOException, PeripheralNotAvailableException,
            PeripheralNotFoundException
    {
        channel = (ADCChannel) PeripheralManager.open(channelID);
        channel.setSamplingInterval(1000); // every 1 seconds
        channel.startMonitoring(low, high, this);
        if (channel instanceof PowerManaged) {
            ((PowerManaged) channel).enablePowerSaving(
                  PowerManaged.LOW_POWER, this);
            // Only enable LOW_POWER saving mode (POWER_ON is implicit)
        }
    }
 
    public void thresholdReached(MonitoringEvent event) {
        inRange = (event.getType() == MonitoringEvent.BACK_TO_RANGE);
    }
 
    public long handlePowerStateChangeRequest(Peripheral peripheral,
            int currentState, int requestedState, long duration)
    {
        if (requestedState == PowerManaged.LOW_POWER) {
            return inRange ? duration : 0;
            // Only accept to change to LOW_POWER if signal is back in range
        }
        return duration; // Accept returning to POWER_ON
    }
 
    public void stop() throws IOException, PeripheralNotAvailableException {
        if (channel != null) {
            channel.stopMonitoring();
            if (channel instanceof PowerManaged) {
                ((PowerManaged) channel).disablePowerSaving();
            }
            channel.close();
        }
    }
}

As any other peripheral devices, peripheral devices that can be power-managed are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open() methods. The com.oracle.deviceaccess.power permission allows access to be granted to peripheral power management. This permission must be requested in the JAD file under MIDlet-Permissions or MIDlet-Permissions-Opt, and the application must be digitally signed by a trusted authority to gain access to the APIs. Alternatively, the permission may be allowed for all applications in the untrusted domain of the security policy file (policy.txt).

The PowerManaged Interface

The PowerManaged interface provides methods that a Peripheral class may implement to control how the underlying peripheral hardware resource is managed by the power management facility of the device.

The power management states defined are peripheral device as well as host device-dependent. For peripherals on a microcontroller unit, there may be no distinction between POWER_OFF, LOW_POWER and LOWEST_POWER and they may all be supported by clock-gating the unused peripherals. Conversely, a peripheral device external to the host device could support the four power management modes and could be powered off.

A power state change may be ordered by the power management facility of the device, or it may be requested by the power management facility on behalf of the application itself or of another application using the method requestPowerStateChange(int, int). A power state change for a specific peripheral device may be requested by another application if the peripheral device or some of the underlying peripheral device hardware resources are shared. This is the case on a GPIOPin instance, for example: another application may have opened a different GPIO pin controlled by the same GPIO controller; the application will get notified of any power state changes requested by the other application.

An application may register to be notified of power state changes. When notified, the application may take the following actions:

The application may save or restore the state or configuration of the peripheral if needed. Saving the peripheral's state or configuration may be needed when the application is being notified of a power state change requested by another application on a peripheral device with hardware resources shared with the current application. The saving and restoration of the peripheral's state or configuration may be needed when changing to or from POWER_OFF or LOWEST_POWER to POWER_ON, as the peripheral context may not be preserved.
The application may veto a power state change. For example, the application may veto a power state change from POWER_ON to LOWEST_POWER if the application is currently using or is about to use the designated peripheral.
The application may grant a shorter power state change duration. For example, the application may grant a duration of a power state change from POWER_ON to LOWEST_POWER shorter than the specified duration if the application anticipates it will use the designated peripheral earlier than the specified duration.

If application-dictated power saving for a peripheral device is not explicitly enabled by a call to one of the enablePowerSaving() method, the default power saving strategy of the platform applies. This strategy is both platform-dependent and implementation-dependent. It may define power saving rules, such as changing the power state of a peripheral device when certain conditions are met, that may or may not differ from peripheral device to peripheral device. It may, for example, forcefully change all peripherals' power state to LOWEST_POWER upon some condition; in such a situation, attempting to access the peripheral without restoring its state or configuration may result in unexpected behavior. Therefore an application should always either:

Register for power state changes on the peripherals it uses.
Register for system-wide power state changes (if supported by the platform) and close the peripherals when going to power saving modes that may not preserve the peripheral context and then open again the peripherals when returning from such power saving modes.

The PowerManaged interface contains five constants.

static final int UNLIMITED_DURATION

This constant represents unlimited or unknown power state change requested duration.
static final int POWER_ON

This constant represents the device as fully powered on. This bit flag can be bitwise-combined (OR) with other power state bit flags.
static final int LOW_POWER

This constant represents the device in a low power mode. It may save less power while preserving more peripheral device context than LOWEST_POWER, hence allowing for a faster return to full performance. When transitioning from this state to POWER_ON no state or configuration restoration of the peripheral device must be needed. This bit flag can be bitwise-combined (OR) with other power state bit flags.
static final int LOWEST_POWER

This constant represents the lowest power mode. In this mode, the device may save more power while preserving less peripheral device context/state than LOW_POWER, hence only allowing for a slower return to full performance. When transitioning from this state to POWER_ON some state or configuration restoration of the peripheral device may be needed. This state or configuration restoration of the peripheral device may be handled by a PowerSavingHandler. This bit flag can be bitwise-combined (OR) with other power state bit flags.
static final int POWER_OFF

This constant represents that the power has been fully removed from the device. When transitioning from this state to POWER_ON a complete state or configuration restoration of the peripheral device may be needed. This state or configuration restoration of the peripheral device may be handled by a PowerSavingHandler. This bit flag can be bitwise-combined (OR) with other power state bit flags.

The PowerManaged interface also contains five methods.

void enablePowerSaving(int powerStates) throws java.io.IOException, PeripheralNotAvailableException

This method enables application-dictated power saving for the Peripheral instance. Note that the POWER_ON state is always implicitly enabled.
void enablePowerSaving(int powerStates, PowerSavingHandler handler) throws java.io.IOException, PeripheralNotAvailableException

This method enables application-dictated power saving for the Peripheral instance and registers a PowerSavingHandler instance to get asynchronously notified when the power management facility is about to change the power state of the Peripheral instance. This in turn allows the application to veto the power state change on the peripheral. Note that the POWER_ON state is always implicitly enabled.
void disablePowerSaving() throws java.io.IOException, PeripheralNotAvailableException

This method disables application-dictated power saving for the Peripheral instance. The power saving strategy of the platform applies. If a PowerSavingHandler instance was registered using enablePowerSaving(int, com.oracle.deviceaccess.power.PowerSavingHandler), it will be unregistered.
int getPowerState() throws java.io.IOException, PeripheralNotAvailableException

This method returns the current power state of the Peripheral instance. If application-dictated power saving is disabled using the disablePowerSaving() method, the power state depends on the power saving strategy of the platform.
int requestPowerStateChange(int powerState, int duration) throws java.io.IOException, PeripheralNotAvailableException

This method requests the change of the peripheral's current power state to the specified power state. If a PowerSavingHandler instance is registered, it will be notified.

The PowerSavingsHandler Class

The PowerSavingHandler interface defines methods for getting notified of power state change requests on a specific Peripheral instance. A PowerSavingHandler can be registered using the PowerManaged.enablePowerSaving(int, com.oracle.deviceaccess.power.PowerSavingHandler) method.

The PowerSavingHandler class consists of one method:

long handlePowerStateChangeRequest(Peripheral peripheral, int currentState, int requestedState, long duration)

This method is invoked to allow the application to handle a power state change request on the designated Peripheral instance. The application may veto the power state change by returning the number zero (0). Otherwise, it should return a duration lesser or equals to the proposed state change duration. An application may veto altogether a power state change from PowerManaged.POWER_ON to PowerManaged.LOWEST_POWER if, for example, the application is currently using or is about to use the designated peripheral. An application may grant a power state change duration lesser than the specified duration if for example the application anticipates it will use the designated peripheral earlier than the specified duration.