The Intel® Mobile Platform SDK provides functionality to monitor and track changes in the power status of a system, without the need for the application to constantly poll for the data.
 
Software developers learn how to obtain information pertaining to the system’s power status using the Intel® Mobile Platform SDK.

While running applications on mobile devices, it is essential for an application to be aware of the current power status of the system. Depending on whether the system is running on internal or external power, applications should be able to adjust their functionality to conserve power. To do this, applications need to track the current power status of the system. The Intel® Mobile Platform SDK provides such a functionality to monitor and track changes in the power status of a system, without the need for the application to constantly poll for the data.

This article demonstrates how to use the Intel® Mobile Platform SDK to obtain information concerning system power status. As explained in the Intel Mobile Platform SDK documentation (CHM 582KB), each instance of the battery class provides status of all individual battery devices present in the system, while the power class aggregates and virtualizes the providers without the knowledge of devices that provide the information. For example, if a system has multiple batteries, ‘power’ will provide information about how much system power is left by aggregating all the batteries. Let’s look at the SDK in a little more detail before diving into the sample application.

The main objective of the Intel Mobile Platform SDK is to help build mobile-aware applications. For example, when improving application behaviors to adjust for changes in battery life, the application needs to have up-to-date information about system power and should be able to track changes without polling for it.

The MPSDK is a multi-platform multiple runtime development kit. Interfaces for C++, .NET and Java* are supported. With these, the Intel Mobile Platform SDK provides developers with a common and consistent interface for controlling platform interaction and adaptation of platform devices (for example, network adapters and batteries) and capabilities (for example, power and bandwidth).

The sample application discussed here demonstrates how to use the Intel Mobile Platform SDK to obtain system power information.

The target platform is a laptop running Intel® Centrino® mobile technology and using the Windows* XP Professional operating system. Sample code was developed using C++.

Let’s look at the sample application in action.

Figure 1: When running on external power.

Figure 1 shows the status when the system is running on battery/external power. Properties like, ‘Power Source’, ‘Capacity’, ‘% Life Remaining’ and ‘Time remaining’ are discussed in this example. Discussion about more properties/APIs can be found in ‘Power’ and ’Battery’ sections of the Intel Mobile Platform SDK Programmers Guide (CHM 582KB).

Figure 2: When the user specified low threshold point is reached.

Figure 2 demonstrates the use of events to monitor a user-specified low threshold. The user can specify the % battery life that needs to be monitored. When that limit is reached, the user is notified with a pop-up window.

Figure 3: Status when running on external power.

Figure 3 indicates a change in current power status when power source is changed for internal to external. That is, when it’s plugged into the AC adapter.

Figure 4: Events tab

Figure 4 displays information about events related to change in system power status. The example tracks events like ‘Change in system power source – Internal/External’ and ‘Low threshold of current power source’ (discussed in the section below).

The sample application should give you an idea of what’s possible, and how easily it can be achieved. We leave it up to you to add this functionality to your own applications! Let’s now look at how to implement this application.

We’ve included the source code along with the article for full implementation details. The following sections point out the salient features in the code.

Initialization

Since ‘Power’ falls into the ‘Capability’ abstraction layer within the SDK, the instance of power is retrieved from capability instance as shown below:

//Initialize power instance 
PowerInstance* pMyPowerInstance; 
ContextClass ConClass; 
ContextInstance* ConInstance; 
pMyPowerInstance = NULL; 

ConInstance = reinterpret_cast<ContextInstance*>(ConClass.GetInstance(L"Power")); 
pMyPowerInstance = reinterpret_cast<PowerInstance*>(CapInstance); 

Once the object is initialized, properties and methods on the ‘power’ class can be used to retrieve power information. Refer to the documentation for full details.

Properties

The ‘Power’ instance provides access to many properties such as power source, capacity, percentage life remaining, and others.

The following source shows how to use the ‘Power’ properties:

//Get info about current power source 
if (!pMyPowerInstance->Source.IsNull()) 
{ 
str1 = "Source: "; 
SourceEnum value =pMyPowerInstance->Source.GetValue(); 
StringObject sValue = value.ToString(); 

if (wcscmp( sValue.GetValue() , L"Internal") == 0) 
{ 
str2 = "Internal - System is running on Battery"; 
} 
Else 
{ 
If (wcscmp( sValue.GetValue() , L"External") == 0) 
{ 
str2 = "External - System is running on AC"; 
} 
} 

//Get info about capacity of current power source 
if (!pMyPowerInstance->Capacity.IsNull()) 
{ 
value = pMyPowerInstance->Capacity.GetValue(); 
} 

//Get % life remaining in current power source. 
if (!pMyPowerInstance->LifePercentRemaining.IsNull()) 
{ 
value = pMyPowerInstance->LifePercentRemaining.GetValue(); 
} 

This code provides information about the current power source and the capacity of the source.

Event Notification

Event notification is a mechanism to obtain changes in system status without constantly polling for it. In other words, you can set up your code to receive a notification when a certain criterion is satisfied.

In this sample application, two ways of getting event notifications are used as explained in the section below.

Monitoring Change in Power Source Using ‘Events’

An event notification class is used to monitor changes in the power source. This is implemented by monitoring the power source properties, ‘ExternalPower’ and ‘InternalPower’. Whenever changes in these properties occur, the event notification mechanism is invoked.

A Basic implementation of a class for handling these events is shown below:

class MyPowerSource : public Observer 
{ 
public: 
void Notify( const Event& event) 
{ 
if (event.GetType()==Event::eExternallyPowered) 
{ 
//Power source changed to Internal Power 
} 
else { 
if (event.GetType()==Event::eInternallyPowered) 
{ 
//Power source changed to External Power 
} 
} 
} 
}; 

MyPowerSource myPower;



//Add observers to listen to changes in Power Source

//Any changes in the events will trigger the 

//'Notify()' method from the observer class

pMyPowerInstance-$gt;ExternalPower.AddObserver(myPower);

pMyPowerInstance->InternalPower.AddObserver(myPower);

By performing these steps, listeners are added to the specified events. When these events occur, the Notify() method in MyPowerSource is invoked and the appropriate action is taken.

It is essential to remove the listeners before terminating the application. If this is not done, there may be few hanging references even though the application has exited. Following piece of code demonstrates how to remove references:

//Cleanup code - remove all listeners (Reqd) 

pMyPowerInstance->InternallyPowered.RemoveObserver(myPower); 

pMyPowerInstance->ExternallyPowered.RemoveObserver(myPower); 

Monitoring Low Threshold Power Using ‘Thresholds’

An event notification class is implemented using ‘Thresholds’ to monitor user-specified Power thresholds. Thresholds are another way to receive notification about changes to any values without having the application continually poll.

Thresholds fall into three categories:

1. Gauge: Notification occurs when upper or lower boundary conditions are met (discussed in this sample)
2. Count: Notification occurs when a counter hits a certain limit.
3. Value: Notification occurs when a property changes to a new value.

For more information about ‘Events and Thresholds’, please refer to the Intel Mobile Platform SDK Programmers Guide (CHM 582KB).

Here’s an implementation of a class that we want called whenever a threshold condition is met:

class MyLowerLimit : public Observer

{

public:

void Notify(const Event& event)

{

if (event.GetType() == Event::eThresholdLow)

{

::MessageBox(NULL,"Low Threshold reached","Warning",MB_OK);

// ...

}



//Stop listening

myLowThreshold.Stop();

}

};

In the main dialog class, initialization is performed as follows:

UIntGaugeThreshold myLowThreshold;

MyLowerLimit lowerLimit;



//Set what property are we interested in monitoring

myLowThreshold.SetObservedProperty(pMyPowerInstance- >LifePercentRemaining);



//Set the lower threshold as specified

myLowThreshold.SetLowThreshold(value);

myLowThreshold.SetHighThreshold(value+5);

myLowThreshold.SetGranularityPeriod(5000);



//Add observer to gauge object

myLowThreshold.AddObserver(lowerLimit);



//Start executing gauge object

myLowThreshold.Start();

Note the call to the `setObservedProperty()` and the settings of the actual threshold values. As mentioned in the first event class implementation, you must remove the listeners before the application is term inated.

The samples discussed here demonstrate how to use the Intel Mobile Platform SDK to retrieve power information and updates at runtime without continuously polling devices. Other information about the platform, devices, and capabilities (such as, connectivity, network, and processor) can also be retrieved using the Intel Mobile Platform SDK.

For more information on the Intel Mobile Platform SDK, visit: http://ossmpsdk.intel.com/

Rajshree Chabukswar is an Application Engineer working on client enabling. (Mobile Application Enabling group) Prior to working at Intel, she obtained an MS in Computer Engineering at Syracuse University, NY.

Joe Zhao is a Software Technical Consulting Engineer working for Intel Corporation’s Software and Solutions Group in Shanghai, China. He worked for nearly 2 years in Intel. He was the engineer in supporting Mobile Platform SDK, and now he is in charge of the maintenance of MPSDK Open Source project website. He got Master degree from the University of East Anglia in England.

• For more information about the Intel Mobile Platform Software Development Kit, visit here
• Learn more about the Intel® Mobile Application Architecture here

Comments (0)

Trackbacks (0)

Leave a comment