- -

Handling the Location Unavailable State

- -

It is hard for the device to detect the location, when the device is underground or there are no Wi-Fi APs and mobile network cell towers near the device. In those situations, it is better to stop the location service to save battery life. Otherwise, the life time of the device is dramatically reduced by consuming power in the hybrid or GPS mode.

- -

You can save power by stopping the location service while the service is not available. You can do this by using a timeout, an alarm, or the low battery callback.

- -

Using a Timeout

- -

If you create a service application, you can stop the location service with an alarm and then restart the service after a specific time interval, because there are no pause and resume states for the service application. Finally, you can stop the location service when the current position is fixed after some seconds or minutes.

- -

The following example demonstrates how you can stop the location service using the timer with the ecore_timer_add() function:

- -

-#include <tizen.h>
-#include <service_app.h>
-#include "service.h" /* Auto-generated header file by the Tizen Studio */
-#include <locations.h>
-#include <Ecore.h>
-
-struct appdata {
-    location_manager_h location;
-    Ecore_Timer *timer;
-};
-typedef struct appdata appdata_s;
-
-/* Callback invoked by updating the position */
-static void
-_position_updated_cb(double latitude, double longitude, double altitude, time_t timestamp, void *data)
-{
-    dlog_print(DLOG_DEBUG, LOG_TAG, "[%ld] lat[%f] lon[%f] alt[%f]\n", timestamp, latitude, longitude, altitude);
-}
-
-/* Create the location service */
-static void
-create_location_service(void *data)
-{
-    appdata_s *ad = (appdata_s *)data;
-    location_manager_h manager;
-    int ret;
-
-    ret = location_manager_create(LOCATIONS_METHOD_HYBRID, &manager);
-    if (ret != LOCATIONS_ERROR_NONE) {
-        dlog_print(DLOG_ERROR, LOG_TAG, "location_manager_create() failed.(%d)", ret);
-    }
-    else {
-        ad->location = manager;
-        ret = location_manager_set_position_updated_cb(manager, _position_updated_cb, 1, (void *)manager);
-    }
-}
-
-/* Destroy the location service */
-static void
-destroy_location_service(void *data)
-{
-    appdata_s *ad = (appdata_s *)data;
-    int ret;
-
-    if (ad->location) {
-        ret = location_manager_destroy(ad->location);
-        if (ret != LOCATIONS_ERROR_NONE)
-            dlog_print(DLOG_ERROR, LOG_TAG, "location_manager_destroy() failed.(%d)", ret);
-        else
-            ad->location = NULL;
-    }
-}
-
-/* Stop the location service after updating the first position */
-static void
-stop_location_service(void *data)
-{
-    appdata_s *ad = (appdata_s *) data;
-    int ret = 0;
-
-    if (ad->location) {
-        ret = location_manager_stop(ad->location);
-        if (ret != LOCATIONS_ERROR_NONE)
-        dlog_print(DLOG_ERROR, LOG_TAG, "location_manager_stop() failed: %d", ret);
-        else
-            dlog_print(DLOG_DEBUG, LOG_TAG, "location service was stopped.");
-    }
-}
-
-/* Callback invoked by the expired timer */
-static Eina_Bool
-_timeout_cb(void *data)
-{
-    appdata_s *ad = (appdata_s *) data;
-
-    /* Call stopping the location service when the specific time is expired */
-    stop_location_service(ad);
-
-    return ECORE_CALLBACK_CANCEL;
-}
-
-/* Start the location service and create a timer */
-static void
-start_location_service(void *data)
-{
-    appdata_s *ad = (appdata_s *) data;
-    int ret = 0;
-
-    ret = location_manager_start(ad->location);
-    if (ad->location) {
-        if (ret != LOCATIONS_ERROR_NONE)
-            dlog_print(DLOG_ERROR, LOG_TAG, "location_manager_start() failed: %d", ret);
-        else
-            dlog_print(DLOG_DEBUG, LOG_TAG, "location service was started");
-        /* Set the timeout */
-        int TIMEOUT = 120;
-        /* Create a timer and set a callback function called after TIMEOUT */
-        Ecore_Timer *my_timer = ecore_timer_add(TIMEOUT, _timeout_cb, ad);
-        if (my_timer != NULL)
-            ad->timer = my_timer;
-    }
-}
-
-bool
-service_app_create(void *data)
-{
-    appdata_s *ad = (appdata_s *)data;
-
-    create_location_service(&ad->location);
-    if (ad->location)
-        start_location_service(ad);
-
-    return true;
-}
-
-void
-service_app_terminate(void *data)
-{
-    appdata_s *ad = (appdata_s *)data;
-
-    if (ad->location)
-        destroy_location_service(ad);
-    if (ad->timer)
-        ecore_timer_del(ad->timer);
-
-    return;
-}
-
-
-/* Assume that auto-generated functions from the Tizen Studio are here */
-
-int
-main(int argc, char* argv[])
-{
-    appdata_s ad = {0,};
-
-    service_app_lifecycle_callback_s event_callback;
-    app_event_handler_h handlers[5] = {NULL,};
-
-    event_callback.create = service_app_create;
-    event_callback.terminate = service_app_terminate;
-    return service_app_main(argc, argv, &event_callback, &ad);
-}
-

- -

Using an Alarm

- -

Tizen provides the Alarm API to trigger events whenever you want to. You can increase the life time of the device by stopping the location service with an alarm, when you have no further need for the location information or the device cannot fix the current location for a long time because its location only has weak GPS satellite, Wi-Fi, and mobile network signals.

- - - - - - - - - - -

Note
The application control is supported in UI applications only, so the following example cannot be reused in service applications.

- -

The following example demonstrates how you can stop the location service using an alarm:

- -

-#include <tizen.h>
-#include <service_app.h>
-#include "service.h" /* Auto-generated header file by the Tizen Studio */
-#include <locations.h>
-#include <app_alarm.h>
-#include <app_control.h>
-
-/* Same as above example except for the following code */
-
-struct appdata {
-    location_manager_h location;
-    int alarm_id;
-};
-typedef struct appdata appdata_s;
-
-/* Stop the location service */
-static void
-stop_location_service(void *data)
-{
-    appdata_s *ad = (appdata_s *) data;
-    int ret = 0;
-
-    if (ad->location) {
-        ret = location_manager_stop(ad->location);
-        if (ret != LOCATIONS_ERROR_NONE)
-            dlog_print(DLOG_ERROR, LOG_TAG, "location_manager_stop() failed: %d", ret);
-        else
-            dlog_print(DLOG_DEBUG, LOG_TAG, "location service was stopped.");
-        if (ad->alarm_id) {
-            alarm_cancel(ad->alarm_id);
-            ad->alarm_id = 0;
-        }
-    }
-}
-
-/* Create an app control for the alarm */
-static bool
-_initialize_alarm(void *data)
-{
-    appdata_s *ad = (appdata_s *) data;
-
-    int ret;
-    /* Set the delay time */
-    int DELAY = 120;
-    int alarm_id;
-
-    app_control_h app_control = NULL;
-    ret = app_control_create(&app_control);
-    ret = app_control_set_operation(app_control, APP_CONTROL_OPERATION_DEFAULT);
-
-    /* Set app_id as the name of the application */
-    ret = app_control_set_app_id(app_control, "org.example.clockui");
-
-    /* Set the key ("location") and value ("stop") of a bundle */
-    ret = app_control_add_extra_data(app_control, "location", "stop");
-
-    /* In order to be called after DELAY */
-    ret = alarm_schedule_once_after_delay(app_control, DELAY, &alarm_id);
-    if (ret != ALARM_ERROR_NONE) {
-        char *err_msg = get_error_message(ret);
-        dlog_print(DLOG_ERROR, LOG_TAG, "alarm_schedule_once_after_delay() failed.(%d)", ret);
-        dlog_print(DLOG_INFO, LOG_TAG, "%s", err_msg);
-
-        return false;
-    }
-
-    ad->alarm_id = alarm_id;
-
-    ret = app_control_destroy(app_control);
-    if (ret != APP_CONTROL_ERROR_NONE)
-        dlog_print(DLOG_ERROR, LOG_TAG, "app_control_destroy() failed.(%d)", ret);
-    else
-        dlog_print(DLOG_DEBUG, LOG_TAG, "Set the triggered time with alarm_id: %d", ad->alarm_id);
-
-    return true;
-}
-
-/* Start the location service */
-void
-start_location_service(void *data)
-{
-    appdata_s *ad = (appdata_s *) data;
-    int ret = 0;
-
-    ret = location_manager_start(ad->location);
-    if (ad->location) {
-        if (ret != LOCATIONS_ERROR_NONE)
-            dlog_print(DLOG_ERROR, LOG_TAG, "location_manager_start() failed: %d", ret);
-        else
-            dlog_print(DLOG_DEBUG, LOG_TAG, "location service was started");
-
-        /* Create a app control for the alarm */
-        ret = _initialize_alarm(ad);
-    }
-}
-
-/* Callback invoked by calling an app control */
-static void
-app_control(app_control_h app_control, void *data)
-{
-    appdata_s *ad = (appdata_s *) data;
-    char *value = NULL;
-
-    dlog_print(DLOG_DEBUG, LOG_TAG, "app_control was called.");
-    /* Check whether the key and value of the bundle are as expected */
-    if (app_control_get_extra_data(app_control, "location", &value) == APP_CONTROL_ERROR_NONE) {
-        if (!strcmp(value, "stop")) {
-            if (ad->location)
-                stop_location_service(ad);
-        }
-        free(value);
-    }
-}
-
-/* Callback invoked by creating an application */
-static bool
-app_create(void *data)
-{
-    appdata_s *ad = data;
-
-    create_base_gui(ad);
-
-    create_location_service(ad);
-
-    if (ad->location)
-        start_location_service(ad);
-
-    return true;
-}
-
-/* Callback invoked by terminating an application */
-static void
-app_terminate(void *data)
-{
-    /* Release all resources */
-    appdata_s *ad = (appdata_s *)data;
-
-    if (ad->location)
-        destroy_location_service(ad);
-}
-
-/* Assume that auto-generated functions from the Tizen Studio are here */
-
-int
-main(int argc, char *argv[])
-{
-    appdata_s ad = {0,};
-    int ret = 0;
-
-    ui_app_lifecycle_callback_s event_callback = {0,};
-    app_event_handler_h handlers[5] = {NULL,};
-
-    event_callback.create = app_create;
-    event_callback.terminate = app_terminate;
-    event_callback.pause = app_pause;
-    event_callback.resume = app_resume;
-    event_callback.app_control = app_control;
-
-    ret = ui_app_main(argc, argv, &event_callback, &ad);
-    if (ret != APP_ERROR_NONE)
-        dlog_print(DLOG_ERROR, LOG_TAG, "ui_app_main() is failed. err = %d", ret);
-
-    return ret;
-}
-

- -

Using the Low Battery Callback

- -

If you stop the location service when the device battery level becomes low, you can increase the life time of the device. You can stop the location service when the low battery callback is triggered. This is the best method for handling the location service in service applications.

- -

The following example demonstrates how you can stop the location service when the device battery is low:

- -

-/* Callback invoked by low battery event */
-static void
-service_app_low_battery(app_event_info_h event_info, void *user_data)
-{
-    / *APP_EVENT_LOW_BATTERY */
-    appdata_s *ad = (appdata_s *) user_data;
-
-    if (ad->location)
-        stop_location_service(ad);
-}
-
-/* Assume that auto-generated functions from the Tizen Studio are here */
-
-int
-main(int argc, char* argv[])
-{
-    appdata_s ad = {0,};
-
-    service_app_lifecycle_callback_s event_callback;
-    app_event_handler_h handlers[5] = {NULL,};
-
-    event_callback.create = service_app_create;
-    event_callback.terminate = service_app_terminate;
-
-    /* Set the callback for low battery event */
-    service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, service_app_low_battery, &ad);
-
-    return service_app_main(argc, argv, &event_callback, &ad);
-}
-

- - - -

Creating Applications with Reduced Battery Drain

Best Practices for Location with Reduced Battery Drain

If you want to create applications that offer reduced battery drain features to the user, Tizen provides various options for you.

Reducing the battery drain due to location services can remarkably save battery life on the device.

@@ -48,18 +49,14 @@

Managing Life-cycles
- To handle location information, you must understand the location service state change logic.
- To save battery life, you must know about the application life-cycle and how to synchronize it with the location service.
- To handle location information, you should understand the location service state change logic.
- To save battery life, you should know about the application life-cycle and how to synchronize it with the location service.
Optimizing Power Consumption
- You can manage different location service methods to reduce power consumption.
- You can create, start, and stop a location service instance, and destroy it when it is no longer needed.
-

Handling the Location Unavailable State -

You can select different location service methods to reduce power consumption.
You can start and stop a location service instance, and destroy it when it is no longer needed.
You can use a timeout or an alarm to stop the location service to save battery life.
You can use a callback to stop the location service when the battery is low.

diff --git a/org.tizen.tutorials/html/native/feature/app_battery_power_n.htm b/org.tizen.tutorials/html/native/feature/app_battery_power_n.htm index 5ef4182..e85a854 100644 --- a/org.tizen.tutorials/html/native/feature/app_battery_power_n.htm +++ b/org.tizen.tutorials/html/native/feature/app_battery_power_n.htm @@ -22,10 +22,9 @@

Content

Power Consumption with Different Location Methods
Required Privileges
Creating and Destroying the Location Service
Starting and Stopping the Location Service
Selecting the Location Method
Synchronizing Life-cycles
Handling the Location Unavailable State

Related Info

Optimizing Power Consumption

To reduce power consumption, you must select the optimal location method for the location service to determine the device location. You must also carefully synchronize the application and location service states to ensure that the location service is only running when the application is on the foreground.

To reduce power consumption, you should select the optimal location method for the location service to determine the device location. You should also carefully synchronize the application and location service states to ensure that the location service is only running when the application is on the foreground.

Power Consumption with Different Location Methods

Selecting Location Methods

The location services provide different methods for determining the location, as illustrated in the following table.

The power consumption and location accuracy differ based on the location source. It is important for you to select the location method, as the location method decides which location sources are used to determine the device location.

The location service provides different methods for determining the location, as illustrated in the following table.

You must decide which method your application uses, based on the advantages and disadvantages:

The power consumption and location accuracy differ based on the location source.
An application requiring high accuracy, such as navigation, must use a continuous location coming from GPS. In this case, the battery consumption is higher, but still recommended to achieve the best accuracy.

The following table shows how much power is consumed approximately by GPS at a standalone mode in the condition of no assistant GPS, such as SUPL (Secure User Plane Location) server.

Required Privileges

You should decide which method your application uses, based on the advantages and disadvantages:

LOCATIONS_METHOD_GPS provides the highest accuracy but may consume more power than other methods.
LOCATIONS_METHOD_WPS provides less accuracy but may consume lower power than LOCATIONS_METHOD_GPS.
LOCATIONS_METHOD_HYBRID provides the best effort through all location sources, but the location updates are not consistent in their accuracy.

An application requiring high accuracy, such as navigation, must use a continuous location coming from GPS. In this case, the battery consumption is higher, but still recommended to achieve the best accuracy.

Synchronizing Life-cycles

A good approach to optimizing power consumption is to synchronize the life-cycles of the application and the location service. When the application is paused, make sure that the location service is paused too. When the application is resumed, resume also the location service.

Required Privileges

To use the location service, the application must declare the required privileges in the tizen-manifest.xml file. For more information on the Tizen privileges, see Security and API Privileges.

For this example, the application manifest must include the following privileges:

Creating and Destroying the Location Service

Create the location service after creating the application. When the application is terminated, destroy the location service.

Starting and Stopping the Location Service

If you want to continuously track the location, stop the location service when the application is paused and restart it when the application is resumed.