Platform Awareness Service: D-bus Interface Documentation

Submit New Article

Last Modified On :   April 22, 2009 5:07 PM PDT
Rate
 



Introduction


This document explains how to retrieve information and subscribe to notifications from the Platform Awareness Service Dbus API. For a more exhaustive explanation of Dbus internals including all possible data types, see http://dbus.freedesktop.org/doc/dbus-tutorial.html. We primarily used the Glib and Python wrappers during our testing, but there is quite a lengthy list of wrappers found at http://www.freedesktop.org/wiki/Software/DBusBindings. The data types listed below are Dbus data types.

The following should be used on every call made to the Platform Awareness Service because they remain constant, regardless of which interface is being used:

Service:                 org.moblin.Platform

Object path:          /org/moblin/Platform

Power Information


Interface

The org.moblin.Platform.Power interface should be used whenever obtaining information or subscribing to events regarding the platform’s power status.

Methods

BOOLEAN     IsUsingExternalPowerSource()

If the device is drawing power from an external power source (e.g. the AC Power adapter is plugged in), this function returns True. Otherwise, this function returns False.

INT32 GetTimeRemaining()

If the device is running from battery power (i.e. IsUsingExternalPowerSource() returns False), then a non-negative value indicates the estimated number of seconds remaining until the battery has no more power (i.e GetPercentRemaining() returns 0). NOTE: It does not indicate how many seconds remain until the system enters a power saving state.

If the device is running on external power (i.e. IsUsingExternalPowerSource() returns True), this function returns -1. If the draining rate of the battery cannot be determined, GetTimeRemaining() returns -2.

UINT32      GetPercentRemaining()

This method returns a number from 0 to 100 indicating the percentage of battery power remaining.

Signal

PowerSourceChanged (BOOLEAN newSourceIsExternal)

When a subscriber receives this signal, the BOOLEAN argument will be True if the system is now attached to an external power source (i.e. IsUsingExternalPowerSource() returns True), or False if the system is now running on battery power.

Connection Information


Interface

The org.moblin.Platform.Connection interface should be used whenever obtaining information or subscribing to events regarding the platform’s connection status.

Methods

BOOLEAN     IsConnected()

This method returns True if there is at least one valid network connection, regardless of what media type (802.03 or 802.11). If there are no valid network connections, IsConnected() returns False.

BOOLEAN     IsReachable (STRING URI)

IsReachable() returns True if the URI specified by the parameter gives a valid response within the system socket timeout interval. If it cannot be reached, if the return code from the server is not 200, or if the request times out this function returns False. This version does not include support for custom ports, server redirection, and protocols other than HTTP.

DOUBLE      GetLatency (STRING URI)

GetLatency()returns the number of seconds (or fraction thereof) required to receive a response from a request made to the URI specified by the URI parameter. If the URI cannot be reached, if the return code from the server is not 200, or if the request times out (i.e. IsReachable() returns False), this function returns -1. This version does not include support for custom ports, server redirection, and protocols other than HTTP.

DOUBLE      GetDataRate (STRING URI)

GetDataRate() uses the byte size of the request, the byte size of the response, and the latency to calculate the instantaneous data rate between the device and the URI specified in the parameter. The return value is measured in KiloBytes/second. If the URI cannot be reached, if the return code from the server is not 200, or if the request times out (i.e. IsReachable() returns False), this function returns -1. This version does not include support for custom ports, server redirection, and protocols other than HTTP.

STRING      GetMediaType()

This function returns a STRING that identifies the network medium currently in use. In this version, possible values are “802.03”, “802.11a”, “802.11b”, “802.11g”, and “Unknown”. If no connection is available, this function returns “Not Connected”.

DOUBLE      GetLinkSpeed()

This function returns the link speed of the network medium that is currently in use. It can be used to quickly estimate the current quality of a network connection, but it does not guarantee that a connection to a specific URI is available. The return value is measured in Kilobits/second. This function returns 0 if there is no connection available.

Signals

Connected

This signal is generated when the device moves from a state in which it had no valid network connections, to a state in which it has at least one valid connection. It is not generated when there is already a valid connection, and an addition connection is established. For example, if a device currently has an 802.03 (Ethernet) connection, this signal will not be fired if the Wifi radio is turned on and a valid 802.11g connection is established.

Disconnected

This signal is generated when the device moves from a state in which there was at least one valid network connection, to a state in which there are no valid network connections. It is not generated when a valid connection is lost and the system still has another valid connection. For example, if a device currently has both a valid 802.03 (Ethernet) connection and a valid 802.11g connection, this signal will not be fired if the Ethernet cable is unplugged.

Display Information


Interface

The org.moblin.Platform.Display interface should be used whenever obtaining information or subscribing to events regarding the platform’s display device.

Methods

UINT32      GetPixelWidth()

This method returns the width of the Moblin device’s main LCD screen in pixels. For example, if current resolution is 1024x600, this method will return 1024.

UINT32      GetPixelHeight()

This method returns the height of the Moblin device’s main LCD screen in pixels. For example, if current resolution is 1024x600, this method will return 600.

UINT32      GetPhysicalWidth()

This method returns the physical width of the Moblin device’s main LCD screen in millimeters. The validity of the return value depends on whether the underlying LCD EDID block provides the necessary data. In this version, no tested devices returned correct values.

UINT32      GetPhysicalHeight()

This method returns the physical width of the Moblin device’s main LCD screen in millimeters. The validity of the return value depends on whether the underlying LCD EDID block provides the necessary data. In this version, no tested devices returned correct values.

STRING      GetOrientation()

This method returns as a STRING the current orientation of Moblin device’s main LCD screen. The possible values are: “Landscape”, “Portrait”, “InvertedLandscape”, and “InvertedPortrait”.

UINT32 GetScreenBrightness()

This method returns the current brightness of the screen as a percentage. For example, if the screen is currently as bright as possible, this method returns 100.                                          

Signals

OrientationChanged(STRING orientation)

This signal is emitted when the orientation of the device’s main LCD changes. Upon reception of this signal, the callee can check the orientation parameter to determine what the new orientation is. The possible values are: “Landscape”, “Portrait”, “InvertedLandscape”, and “InvertedPortrait”.

ScreenBrightnessChanged(UINT32 brightness)

This signal is emitted when the brightness of the device’s main LCD changes. Upon reception of this signal, the callee can check the brightness parameter to determine the current brightness of the LCD as a percentage.

Location Information


Interface

The org.moblin.Platform.Location interface should be used whenever obtaining information or subscribing to events regarding the platform’s location.

Method

DOUBLE,DOUBLE,DOUBLE GetLocation()

This single method returns latitude, longitude and altitude in three separate double values. The first element contains the latitude coordinate, the second element contains the longitude coordinate, and the third element contains the altitude. The longitude and latitude coordinates are given in degrees, while the altitude is reported in meters.

Valid data will only be returned on a device that is running gpsd to collect the GPS data. Information about gpsd is available at http://gpsd.berlios.de/.

--enable-gps=[yes/no] is a build flag in the ./configure script of the Platform Awareness Service which will let you build the service with or without location information (and the dependency upon gpsd). If GetLocation() is called while location information is disabled, the following error is returned:

“this build does not have gps enabled. Please rebuild midplatformsvc with the flag --enable-gps=yes.”

If GetLocation() is called and gpsd is not running on the device, the following error is returned:

“unable to connect to gpsd. Is gpsd running?”

Also, if the GPS device has difficulty finding enough satellites to report a valid lat/long location, an error is returned:

“cannot get a strong enough signal strength.”

Processor Information


Interface

The org.moblin.Platform.Processor interface should be used whenever obtaining information or subscribing to events regarding the platform’s processing capabilities.

Methods

UINT32      GetCPUUtilization()

This method returns the current processor utilization as a percentage. Because it samples utilization for one second at the time the call is made, this function does not complete until the measurement is complete.

UINT32      GetCPUCount()

This method returns the number of logical processors on the device. It does not distinguish whether processors are part of the same physical package or not. For example, if hyper-threading is enabled on a single physical processor, this function would return 2.

STRING      GetCPUInfo()

This method returns the brand string for the processor that usually contains information about the manufacturer, the processor model, and the frequency. For example, if the device contains an Intel® Atom™ processor, this method might return “Intel(R) Atom(TM) CPU Z500   @ 800MHz”.

Storage Information


Interface

The org.moblin.Platform.Storage interface should be used whenever obtaining information or subscribing to events regarding the platform’s storage capabilities.

Methods

ARRAY of STRING   GetLogicalStorageDevices()

This method returns a variable-length array of STRING elements. Each element is the mount point for a logical storage device attached to the system. For example, if a MID device has two internal Solid State Disks (SSD) and a USB thumb drive that has two logical partitions on it, a call to this method might return the following:

                [ “/”,

                “/root/MyDocs”,

                “/media/disk”,

                “/media/disk-1” ]

DOUBLE      GetAvailableSpace (STRING mountPath)

This method returns the number of megabytes (MB — or fraction thereof) available for storage on the logical device indicated by the mountPath parameter. If the logical device is marked read-only, this method returns 0. If no logical device mapped to mountPath can be found, this method returns an error.

BOOLEAN     IsRemovable (STRING mountPath)

This method returns a BOOLEAN indicating whether the specified logical storage device is removable. If no logical device mapped to mountPath can be found, this method returns an error.

Input Device Information


Interface

The org.moblin.Platform.Input interface should be used whenever obtaining information or subscribing to events regarding the platform’s input devices.

Methods

BOOLEAN     IsPhysicalPointerPresent()

The value returned by this method indicates whether or not there is a physical pointer device (e.g. mouse, touch-pad, etc.) attached to the system. If none is attached, returns False. If at least one physical pointing device is attached, returns True.

BOOLEAN     IsPhysicalKeyboardPresent()

The value returned by this method indicates whether or not there is a physical keyboard device (e.g. sliding, USB, Bluetooth®, etc.) attached to the system. If none is attached, or if the attached device is numeric 10-key pad, this method returns False. If at least one physical keyboard is attached, returns True.

 

BOOLEAN     IsTouchScreen()

The value returned from this method indicates whether or not the device’s LCD is a touch screen. In this version, which only supports MIDs, this method always returns True.

BOOLEAN     IsOnScreenKeyboardVisible()

This method returns True if the on-screen keyboard is visible (i.e. restricting space available for other applications). Otherwise, this method returns false.

Signals

PhysicalKeyboardPresentChanged(BOOLEAN isPresent)

This signal is fired only when the presence of a physical keyboard attached to the system changes from no keyboard present to at least one keyboard is present, and when all keyboards have been removed from the system.  The parameter indicates whether or not there is a physical keyboard present after the event. If there are two keyboards attached (e.g. a slider keyboard and a USB keyboard) and the USB keyboard is removed, this event will not be fired as a remaining keyboard is still present. If a keyboard is added to a system that previously had no keyboard, then this event will be fired and the parameter will be True.

PhysicalPointerPresentChanged(BOOLEAN isPresent)

This signal is fired only when the presence of a physical pointer attached to the Moblin system changes from no pointer present to at least one pointer is present, and when all pointers have been removed from the system.  The parameter indicates whether or not there is a physical pointer present after the event. If there are two mouse devices attached (e.g. a touch pad and a USB mouse) and the USB mouse is removed, this event will not be fired as a remaining mouse is still present. If a mouse is added to a system that previously had no mouse, then this event will be fired and the parameter will be True.

OnScreenKeyboardChanged(BOOLEAN isPresent)

This signal is fired whenever the on-screen keyboard appears and whenever the on-screen keyboard disappears. The parameter indicates whether or not the on-screen keyboard is currently visible.