## GNOME Power Management Specification (with additions)

### Richard Hughes

`<richard@hughsie.com>`

Version 2.19.x

## Overview

A Power Management specification has been in used informally used for a few years on the GNOME desktop. There has never been any standardised nomenclature or API to allow desktops such as KDE and XFCE to interoperate. This has lead to technologies that have often been incompatible and resulted in poor integration of power management into desktop applications.

## DBUS API

The interfaces are session-wide.

DBUS Service: | `org.freedesktop.PowerManagement`

### Compulsory Basic Interface

DBUS Interface: | `org.freedesktop.PowerManagement`
DBUS Path: | `/org/freedesktop/PowerManagement`

Methods on interface `org.freedesktop.PowerManagement` define a compulsory base layer for interoperability.

Table 1. Methods on interface `org.freedesktop.PowerManagement`

Name | Input Parameters | Return Values | Throws Error | Description
--- | --- | --- | --- | ---
`Suspend` |  |  | `PermissionDenied`, `NoHardwareSupport` | Attempt to suspend the system.
`Hibernate` |  |  | `PermissionDenied`, `NoHardwareSupport` | Attempt to hibernate the system.
`Shutdown` |  |  | `PermissionDenied`, `NoHardwareSupport` | Attempt to shutdown the system.
`Reboot` |  |  | `PermissionDenied`, `NoHardwareSupport` | Attempt to reboot the system.
`CanSuspend` |  | `bool` can_suspend |  | If the current session user is able to suspend the system.
`CanHibernate` |  | `bool` can_hibernate |  | If the current session user is able to hibernate the system.
`CanShutdown` |  | `bool` can_shutdown |  | If the current session user is able to shutdown the system.
`CanReboot` |  | `bool` can_reboot |  | If the current session user is able to reboot the system.
`GetPowerSaveStatus` |  | `bool` save_power |  | This may be set on AC or battery power, both, or neither depending on the users preference setting. This setting may also change with the battery level changing. Programs should respect this value and not perform non-essential tasks when we are trying to save power.
`GetOnBattery` |  | `bool` on_battery |  | Returns the system power state, i.e. if we are running on battery power. This method may still return true on AC using a desktop system if the computer is using backup power from a monitored UPS.
`GetLowBattery` |  | `bool` low_battery |  | Returns true if the battery is low and discharging. This may be measured with time remaining or percentage change, and the exact threshold level is an implementation detail. Programs that cannot deal with a low power action such as suspend or hibernate should not run if this method returns true.

Table 2. Signals emitted from interface `org.freedesktop.PowerManagement`

Name | Return Values | Description
--- | --- | ---
`CanSuspendChanged` | `bool` can_suspend | Signals the suspend status has changed.
`CanHibernateChanged` | `bool` can_hibernate | Signals the hibernate status has changed.
`CanShutdownChanged` | `bool` can_shutdown | Signals the shutdown status has changed.
`CanRebootChanged` | `bool` can_reboot | Signals the reboot status has changed.
`PowerSaveStatusChanged` | `bool` save_power | Signals the low power mode has changed..
`OnBatteryChanged` | `bool` on_battery | Signals the battery discharge state has changed.
`LowBatteryChanged` | `bool` on_battery | Signals the battery low power state has changed.

### Optional Backlight Interface

NON STANDARDISED API

DBUS Interface: | `org.freedesktop.PowerManagement.Backlight`
DBUS Path: | `/org/freedesktop/PowerManagement/Backlight`

The `org.freedesktop.PowerManagement.Backlight` interface is optional, and allows a UI element to interact with the session daemon without using HAL directly.

By using the session dameon, rather than HAL any UI can have preference settings saved, without two policies being forced on one device.

Table 3. Methods on interface `org.freedesktop.PowerManagement.Backlight`

Name | Input Parameters | Return Values | Throws Error | Description
--- | --- | --- | --- | ---
`GetBrightness` |  | `uint` percentage_brightness | `NoHardwareSupport` | Returns the current backlight brightness as a percentage.
`SetBrightness` | `uint` percentage_brightness |  | `DeniedByPolicy`, `NoHardwareSupport` | This may not immediately set the brightness if we are in a low power sleep mode, if the panel is switched off, or if the panel is in an idle dim state.

Table 4. Signals emitted from interface `org.freedesktop.PowerManagement.Backlight`

Name | Return Values | Description
--- | --- | ---
`BrightnessChanged` | `uint` percentage_brightness | Signals the value of the current brightness has changed.

### Optional Widget Interface

NON STANDARDISED API

DBUS Interface: | `org.freedesktop.PowerManagement.Widget`
DBUS Path: | `/org/freedesktop/PowerManagement/Widget`

The `org.freedesktop.PowerManagement.Widget` interface is optional, and allows a UI element to display the state of the system.

Some user interface front-ends will be in a different process to that of any power manager and system state will have to be transmitted over DBUS.

Only the final icon and description are exported over DBUS as presenting an abstract power interface is wrong for this trivial functionality.

Table 5. Methods on interface `org.freedesktop.PowerManagement.Widget`

Name | Input Parameters | Return Values | Throws Error | Description
--- | --- | --- | --- | ---
`GetDescription` |  | `string` description |  | Returns the system state description, e.g. Laptop battery 34 minutes until charged (34%).
`GetIcon` |  | `string` icon |  | Returns the icon name, e.g. primary-080-charging

Table 6. Signals emitted from interface `org.freedesktop.PowerManagement.Widget`

Name | Return Values | Description
--- | --- | ---
`DescriptionChanged` | `string` description | Signals the system state description has changed.
`IconChanged` | `string` icon | Signals the system icon has changed.

### Optional Inhibit Interface

NON STANDARDISED API

DBUS Interface: | `org.freedesktop.PowerManagement.Inhibit`
DBUS Path: | `/org/freedesktop/PowerManagement/Inhibit`

When the power manager detects an idle session and system, it can perform a system suspend or hibernate, known as an idle sleep action. We can prevent the session power manager daemon from doing this action using the inhibit interface.

An automatic inhibit should be taken by the file manager if there is a slow network copy that will take many minutes to complete.

A cookie is a randomly assigned 32bit unsigned integer used to identify the inhibit. It is required as the same application may want to call inhibit multiple times, without managing the inhibit calls itself.

Inhibit and UnInhibit are easy to use, requiring only the cookie to be stored in the client application. Below is a simple python demonstration showing an inhibit action.

    #!/usr/bin/python
    import dbus
    import time
    bus = dbus.Bus(dbus.Bus.TYPE_SESSION)
    devobj = bus.get_object('org.freedesktop.PowerManagement', '/org/freedesktop/PowerManagement')
    dev = dbus.Interface (devobj, "org.freedesktop.PowerManagement.Inhibit")
    cookie = dev.Inhibit('Nautilus', 'Copying files from /media/SANVOL')
    time.sleep(10)
    dev.UnInhibit(cookie)

Table 7. Methods on interface `org.freedesktop.PowerManagement.Inhibit`

Name | Input Parameters | Return Values | Throws Error | Description
--- | --- | --- | --- | ---
`Inhibit` | `string` application, `string` reason | `uint` cookie | `PermissionDenied` | Inhibits the computer from performing an idle sleep action. Useful if you want to do an operation of long duration without the computer suspending. Reason and application should be translated strings where possible.
`UnInhibit` | `uint` cookie |  | `CookieNotFound` | Allows the computer to perform the idle sleep or user action if the number of inhibit calls is zero. If there are multiple cookies outstanding, clearing one cookie does not allow the action to happen. If the program holding the cookie exits from the session bus without calling `UnInhibit()` then it is automatically removed.
`HasInhibit` |  | `bool` has_inhibit |  | Returns false if we have no valid inhibits. This will return true if the number of inhibit cookies is greater than zero.

Table 8. Signals emitted from interface `org.freedesktop.PowerManagement.Inhibit`

Name | Return Values | Description
--- | --- | ---
`HasInhibitChanged` | `bool` has_inhibit | Signals the inhibit valid state has changed.

### Optional Statistics Interface

NON STANDARDISED API

DBUS Interface: | `org.freedesktop.PowerManagement.Statistics`
DBUS Path: | `/org/freedesktop/PowerManagement/Statistics`

Statistics data are values that can be collected by the power manager for review or profiling. These allow the user to profile power saving methods, usually shown to the user in the form of a graph.

Table 9. Methods on interface `org.freedesktop.PowerManagement.Statistics`

Name | Input Parameters | Return Values | Throws Error | Description
--- | --- | --- | --- | ---
`GetDataTypes` |  | `list of strings [as]` types |  | Gets a list of the types of data available. Data types are single strings that represent the complete data and do not indicate the axis, e.g. [ 'voltage', 'power', 'percentage' ]
`GetAxisTypes` | `string` data_type | `string` x_axis, `string` y_axis |  | For some presentations, for example graphs we can present the data in many different ways. This method returns the type of data that is recorded for each axis, e.g. x_axis might return 'percentage'
`GetData` | `uint` seconds, `string` data_type | `array of 3-integers [a(iii)]` data |  | Gets the data for a given type. In the return data the 3-integers represent the X value, Y value and data value respectively. The seconds parameter is how much data we should get.