Table of Contents
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.
The interfaces are session-wide.
| DBUS Service: | org.freedesktop.PowerManagement |
| 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. |
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. |
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. |
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. |
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. |