+ +

Power Manager Sample Overview

+ +

The sample demonstrates how to use System and App Control API to monitor and change device's settings (battery level, screen brightness, Wi-Fi, GPS, Bluetooth).

+ +

The Power Manager sample application implements three following features:

+
Displaying device information
+
The panel at the top of the screen displays battery percentage and level (empty/critical/low/high), charging status (on/off) as well as the status of + some power consuming device's settings (Wi-Fi, Bluetooth, GPS).
+
+
Warning the user when the battery level drops too low
+
When the battery level drops below the defined warnings level, a popup is displayed to warn the user about it (Fig. 2). The user can manually set the warnings level.
+
+
Enabling/disabling custom Power Saving mode
+
The application provides a convenient way to change the following device's settings to reduce power consumption:
+
- display brightness - when in Power Saving mode, the display brightness is changed to low (20%);
- Wi-Fi state - when in Power Saving mode, the Wi-Fi is automatically turned off;
- Bluetooth state - when in Power Saving mode, the user will be advised to turn off Bluetooth and, upon request, Settings application will be launched;
- GPS state - approach same as in the Bluetooth state case.
+
When the Power Saving mode is disabled, display brightness is changed to full (100%) and the power consuming settings can be turned on the same way they were turned off + (whether automatically or upon request).
+
There are 3 types of alerts the user can encounter when trying to turn Power Saving mode on/off:
+
- turn power consuming settings off - if the application detects that any of the three power consuming settings (Wi-Fi, Bluetooth or GPS) is on when enabling Power Saving mode, + a popup is displayed to alert the user about it (Fig. 4) and offers to launch Settings application to manage it;
- turn power consuming settings on - similarly, if the application detects that any of the three settings is off when disabling Power Saving mode, + a popup is displayed (Fig. 5);
- device is charging - Power Saving mode will not be enabled if the device is charging. If the user tries to turn the mode on in such situation, a popup + is displayed to inform the user about it (Fig. 6).
+

+ + ++ + + + + + + + + + +

Figure 1: Power Manager sample app main view.

Power Manager sample app main view

Figure 2: Power Manager sample app view: battery level dropped.

Power Manager sample app view: battery level dropped

Figure 3: Power Manager sample app view: Power Saving mode on.

Power Manager sample app view: Power Saving mode on

Figure 4: Power Manager sample app main: turn off settings.

Power Manager sample app main: turn off settings

Figure 5: Power Manager sample app view: turn on settings.

Power Manager sample app view: turn on settings

Figure 6: Power Manager sample app view: device is charging.

Power Manager sample app view: device is charging

+ +

The main view of the application (as seen in Fig. 1) consists of the following areas (top to bottom):

Device status area
+
Information about device's settings and state is displayed here. There are 5 subareas that convey the following data:
+
- charging status (on/off),
- Wi-Fi status (on/off),
- Bluetooth status (on/off),
- GPS status (on/off),
- Battery state (percentage and level).
+
Battery level warnings area
+
This is the control panel for warnings about battery level going too low. The user can set the battery level at which he or she wants to receive warnings using a slider.
+
Power Saving mode area
+
The area consists only of a button the user can use to turn the Power Saving mode on/off.
+

+ + +

Prerequisites

To ensure proper application execution, the following privileges must be set:

http://tizen.org/privilege/network.get - to read Wi-Fi status;
http://tizen.org/privilege/network.set - to set Wi-Fi status;
http://tizen.org/privilege/appmanager.launch - to launch Settings application;
http://tizen.org/privilege/display - to change display brightness.

+ + +

Implementation

+ +

Acquiring device's information

+ +

Runtime information + Wi-Fi status

+ +

The Runtime Information API is used in this sample application to obtain the following runtime information:

battery charging status (RUNTIME_INFO_KEY_BATTERY_IS_CHARGING),
Bluetooth status (RUNTIME_INFO_KEY_BLUETOOTH_ENABLED),
GPS status (RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED).

+ +

In addition to this information, Wi-Fi status is acquired using the Wi-Fi API. In order to do that, +the Wi-Fi module needs to be initialized first. It is done using the wifi_initialize() +function. If the initialization is successful, Wi-Fi status is acquired using wifi_is_activated() function.

+ +

+bool dev_manager_get_runtime_info(bool *charging, bool *bluetooth_on, bool *wifi_on, bool *gps_on)
+{
+   if (charging) {
+      *charging = false;
+      if (runtime_info_get_value_bool(RUNTIME_INFO_KEY_BATTERY_IS_CHARGING, charging) != RUNTIME_INFO_ERROR_NONE) {
+         dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get runtime info: battery is charging");
+      }
+   }
+   settings_on[SETTINGS_CHARGING] = *charging;
+
+   if (bluetooth_on) {
+      *bluetooth_on = false;
+      if (runtime_info_get_value_bool(RUNTIME_INFO_KEY_BLUETOOTH_ENABLED, bluetooth_on) != RUNTIME_INFO_ERROR_NONE) {
+         dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get runtime info: bluetooth enabled");
+      }
+   }
+   settings_on[SETTINGS_BLUETOOTH] = *bluetooth_on;
+
+   if (wifi_on) {
+      *wifi_on = false;
+      if (wifi_initialize() != WIFI_ERROR_NONE || wifi_is_activated(wifi_on) != WIFI_ERROR_NONE) {
+         dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get runtime info: wifi enabled");
+      }
+   }
+   settings_on[SETTINGS_WIFI] = *wifi_on;
+
+   if (gps_on) {
+      *gps_on = false;
+      if (runtime_info_get_value_bool(RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED, gps_on) != RUNTIME_INFO_ERROR_NONE) {
+         dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get runtime info: gps enabled");
+      }
+   }
+   settings_on[SETTINGS_GPS] = *gps_on;
+
+   return true;
+}
+

+ +

Battery information

+ +

Battery information is obtained using Device/Battery API. The device_battery_get_percent() +function is used to get the battery level in a form of a percentage whereas the device_battery_get_level_status() +is used to get the battery level status. The API defines five battery levels:

DEVICE_BATTERY_LEVEL_EMPTY (<2%),
DEVICE_BATTERY_LEVEL_CRITICAL (2-5%),
DEVICE_BATTERY_LEVEL_LOW (6-15%),
DEVICE_BATTERY_LEVEL_HIGH (16-95%),
DEVICE_BATTERY_LEVEL_FULL (>95%).

+ +

+int dev_manager_get_battery_percent(void)
+{
+   int percent = -1;
+
+   if (device_battery_get_percent(&percent) != DEVICE_ERROR_NONE)
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get battery percentage");
+
+   return percent;
+}
+
+char *dev_manager_get_battery_level(void)
+{
+   device_battery_level_e status = DEVICE_BATTERY_LEVEL_EMPTY;
+
+   if (device_battery_get_level_status(&status) != DEVICE_ERROR_NONE)
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get battery level");
+
+   return __format_battery_level_string(status);
+}
+

+ +

Setting relevant callbacks

+ +

To monitor changes in relevant device's settings and battery state, a set of callbacks is used.

+ +

Runtime information callbacks

+ +

To monitor relevant runtime information, the runtime_info_set_changed() function is used. +It registers a change event callback for given runtime information key. In case of this application, callbacks are set for +RUNTIME_INFO_KEY_BLUETOOTH_ENABLED, +RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED and +RUNTIME_INFO_KEY_BATTERY_IS_CHARGING keys.

+ +

+bool dev_manager_set_runtime_info_callbacks(changed_setting_cb changed_cb)
+{
+   if (runtime_info_set_changed_cb(RUNTIME_INFO_KEY_BLUETOOTH_ENABLED, __runtime_cb, changed_cb) != RUNTIME_INFO_ERROR_NONE ||
+      runtime_info_set_changed_cb(RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED, __runtime_cb, changed_cb) != RUNTIME_INFO_ERROR_NONE ||
+      runtime_info_set_changed_cb(RUNTIME_INFO_KEY_BATTERY_IS_CHARGING, __runtime_cb, changed_cb) != RUNTIME_INFO_ERROR_NONE) {
+         dlog_print(DLOG_ERROR, LOG_TAG, "Failed to set runtime callbacks");
+         return false;
+   }
+
+   return true;
+}
+

+ +

When a change event is detected and the __runtime_cb function is invoked which gets +the runtime information key type as an argument. The new runtime information is used to update the application's UI using +changed_cb function and the relevant setting's value is stored internally.

+ +

+static void __runtime_cb(runtime_info_key_e key, void *user_data)
+{
+   bool val = false;
+   changed_setting_cb changed_cb;
+
+   if (!user_data) {
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get cb func");
+      return;
+   }
+
+   changed_cb = (changed_setting_cb)user_data;
+
+   switch (key) {
+   case RUNTIME_INFO_KEY_BLUETOOTH_ENABLED:
+      runtime_info_get_value_bool(RUNTIME_INFO_KEY_BLUETOOTH_ENABLED, &val);
+      settings_on[SETTINGS_BLUETOOTH] = val;
+      changed_cb(SETTINGS_BLUETOOTH, settings_on[SETTINGS_BLUETOOTH]);
+      break;
+   case RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED:
+      runtime_info_get_value_bool(RUNTIME_INFO_KEY_LOCATION_SERVICE_ENABLED, &val);
+      settings_on[SETTINGS_GPS] = val;
+      changed_cb(SETTINGS_GPS, settings_on[SETTINGS_GPS]);
+      break;
+   case RUNTIME_INFO_KEY_BATTERY_IS_CHARGING:
+      runtime_info_get_value_bool(RUNTIME_INFO_KEY_BATTERY_IS_CHARGING, &val);
+      settings_on[SETTINGS_CHARGING] = val;
+      changed_cb(SETTINGS_CHARGING, settings_on[SETTINGS_CHARGING]);
+      break;
+   default:
+      break;
+   }
+}
+

+ +

Device information callbacks

+ +

In order to be notified about battery state changes, the device_add_callback() +is invoked for DEVICE_CALLBACK_BATTERY_CAPACITY (battery level percentage) and +DEVICE_CALLBACK_BATTERY_LEVEL (battery level status) callback types.

+ +

+bool dev_manager_set_device_callbacks(changed_bat_percentage_cb percentage_cb, changed_bat_level_cb level_cb)
+{
+   if (device_add_callback(DEVICE_CALLBACK_BATTERY_CAPACITY, __bat_changed_cb, percentage_cb) != DEVICE_ERROR_NONE ||
+      device_add_callback(DEVICE_CALLBACK_BATTERY_LEVEL, __bat_changed_cb, level_cb) != DEVICE_ERROR_NONE) {
+         dlog_print(DLOG_ERROR, LOG_TAG, "Failed to set device callbacks");
+         return false;
+   }
+
+   return true;
+}
+

+ +

The __bat_changed_cb() callback function gets the callback type +(device_callback_e) as an argument which is then used to update the application's UI accordingly.

+ +

+static void __bat_changed_cb(device_callback_e type, void *value, void *user_data)
+{
+   changed_bat_percentage_cb percentage_cb;
+   changed_bat_level_cb level_cb;
+   int val = (int)value;
+
+   if (!user_data) {
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get cb func");
+      return;
+   }
+
+   switch (type) {
+   case DEVICE_CALLBACK_BATTERY_CAPACITY:
+      percentage_cb = (changed_bat_percentage_cb)user_data;
+      percentage_cb(val);
+      break;
+   case DEVICE_CALLBACK_BATTERY_LEVEL:
+      level_cb = (changed_bat_level_cb)user_data;
+      level_cb(__format_battery_level_string((device_battery_level_e)val));
+      break;
+   default:
+      break;
+   }
+}
+

+ +

Setting display brightness

+ +

When the Power Saving mode is enabled, the application changes the device's display brightness. The Device/Display API is used to do that. +The code snippet below shows the implementation of this feature.

+ +

+bool dev_manager_power_mode_set_brightness(Eina_Bool to_low)
+{
+   int max = 0;
+   int percent = to_low ? BRIGHTNESS_LEVEL_LOW : BRIGHTNESS_LEVEL_FULL;
+
+   if (device_display_get_max_brightness(0, &max) != DEVICE_ERROR_NONE) {
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to get max brightness");
+      return false;
+   }
+
+   if (device_display_set_brightness(0, (int)percent*max/100) != DEVICE_ERROR_NONE) {
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to set brightness");
+      return false;
+   }
+
+   return true;
+}
+

+ +

Turning Settings on/off

+ +

To reduce power consumption when in Power Saving mode, the sample application allows the user to turn more power consuming +settings off. Wi-Fi deactivation is done automatically using wifi_deactivate() function.

+ +

+bool dev_manager_power_mode_settings_off(Eina_Bool turn_off)
+{
+   if (turn_off) {
+      if (settings_on[SETTINGS_WIFI] && wifi_deactivate(NULL, NULL) != WIFI_ERROR_NONE)
+         dlog_print(DLOG_ERROR, LOG_TAG, "Failed to deactivate Wi-Fi");
+
+      if (settings_on[SETTINGS_GPS])
+         __launch_setting_location_app();
+
+      if (settings_on[SETTINGS_BLUETOOTH])
+         __launch_bluetooth_app();
+   } else {
+      if (settings_on[SETTINGS_WIFI] && wifi_activate(NULL, NULL) != WIFI_ERROR_NONE)
+         dlog_print(DLOG_INFO, LOG_TAG, "Failed to activate Wi-Fi");
+
+      if (!settings_on[SETTINGS_GPS])
+         __launch_setting_location_app();
+
+      if (!settings_on[SETTINGS_BLUETOOTH])
+         __launch_bluetooth_app();
+   }
+
+   return true;
+}
+

+ +

Launching Settings application

+ +

Changing the state of GPS or Bluetooth is not allowed for regular applications. To allow the user to conveniently change these settings, the Power Manager sample applications +launches relevant module of Settings application upon user's request. App Control API is used to do that. +In case of Bluetooth, application/x-bluetooth-on-off is set explicitly as the MIME type of the data to be edited, whereas +in case of GPS settings, org.tizen.setting-location app ID is set, also with 'edit' operation type. +See the code snippets below for the Settings application launching implementation.

+ +

+static void __launch_bluetooth_app(void)
+{
+   app_control_h service = NULL;
+
+   app_control_create(&service);
+   if (!service) {
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to create app control handle");
+      return;
+   }
+
+   app_control_set_operation(service, "http://tizen.org/appcontrol/operation/edit");
+   app_control_set_mime(service, "application/x-bluetooth-on-off");
+
+   if (app_control_send_launch_request(service, NULL, NULL) != APP_CONTROL_ERROR_NONE)
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to launch Bluetooth On/Off app");
+
+   app_control_destroy(service);
+}
+

+ +

+static void __launch_setting_location_app(void)
+{
+   app_control_h service = NULL;
+
+   app_control_create(&service);
+   if (!service) {
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to create app control handle");
+      return;
+   }
+
+   app_control_set_operation(service, "http://tizen.org/appcontrol/operation/edit");
+   app_control_set_app_id(service, "org.tizen.setting-location");
+
+   if (app_control_send_launch_request(service, NULL, NULL) != APP_CONTROL_ERROR_NONE)
+      dlog_print(DLOG_ERROR, LOG_TAG, "Failed to launch Location Settings app");
+
+   app_control_destroy(service);
+}
+

+ + + + +