Device: Accessing Devices, Such as SB, MMC, Battery, CPU, and Display

This tutorial demonstrates how you can manage the display, battery, LED, haptic, and power functions.

Warm-up

Become familiar with the Device API basics by learning about:

Retrieving Battery Information
Get battery information.
Device control
- Controlling the Display
  Control display devices.
- Controlling Haptic Devices
  Control haptic devices.
- Controlling LED Devices
  Control LED devices.
- Controlling the Power State
  Control the device power state.
Monitoring Device Changes
Register a changed device event to monitor device changes.

Retrieving Battery Information

To retrieve battery information:

To use the battery-related features of the Device API (in mobile and wearable applications), include the <device/battery.h> header file in your application:
```
#include <device/battery.h>
```
Get the battery details:
- Get the battery percentage with the device_battery_get_percent() function.
  The function returns the current battery percentage as an integer value from 0 to 100 that indicates the remaining battery charge as a percentage of the maximum level.
```
int error, pct;
error = device_battery_get_percent(&pct);
```
- Get the current charging battery state with the device_battery_is_charging() function:
```
int error;
bool charging;
error = device_battery_is_charging(&charging);
```
- Get the current battery level state with the device_battery_get_level_status() function.
  The device_battery_level_e enumerator (in mobile and wearable applications) defines the available battery levels.
```
int error;
device_battery_level_e level;
error = device_battery_get_level_status(&level);
```

Controlling the Display

To control the display:

To use the display-related features of the Device API (in mobile and wearable applications), include the <device/display.h> header file in your application:
```
#include <device/display.h>
```
Retrieve and set display properties:
- Get the number of display devices with the device_display_get_numbers() function:
```
int error, num;
error = device_display_get_numbers(&num);
```
- Get the maximum brightness with the device_display_get_max_brightness() function.
  The function returns the maximum brightness value that can be set. This function always returns as 100.
```
int error, max;
error = device_display_get_max_brightness(0, &max);
```
- Get and set the display brightness with the device_display_get_brightness() and device_display_set_brightness() functions:
```
int error, brt;
error = device_display_get_brightness(0, &brt);

error = device_display_set_brightness(0, 100);
```
- Get and set the display state with the device_display_get_state() and device_display_change_state() functions:
```
int error;
display_state_e state;
error = device_display_get_state(&state);

error = device_display_change_state(DISPLAY_STATE_NORMAL);
```
  The display_state_e enumerator (in mobile and wearable applications) defines the available display states.

Controlling Haptic Devices

To control haptic devices:

To use the haptic-related features of the Device API (in mobile and wearable applications), include the <device/haptic.h> header file in your application:
```
#include <device/haptic.h>
```
Get the number of haptic devices with the device_haptic_get_count() function.
```
int error, num;
error = device_haptic_get_count(&num);
```
Initialize the haptic device with the device_haptic_open() function.
The function opens a haptic-vibration device and returns the handle of the haptic device. It makes a connection to the vibrator.
```
int error;
haptic_device_h handle;
error = device_haptic_open(0, &handle);
```
Play and stop an effect on the device with the device_haptic_vibrate() and device_haptic_stop() functions.
The device vibrates during specified time with a constant intensity. The effect handle can be 0.
```
int error;
haptic_effect_h effect_handle;
error = device_haptic_vibrate(handle, 1000, 100, &effect_handle);

error = device_haptic_stop(handle, &effect_handle);
```
When no longer needed, uninitialize the haptic device with the device_haptic_close() function.
The function closes the haptic handle. It disconnects the connection to the vibrator.
```
int error;
error = device_haptic_close(0, handle);
```

Controlling LED Devices

To control LED devices:

To use the LED-related features of the Device API (in mobile and wearable applications), include the <device/led.h> header file in your application:
```
#include <device/led.h>
```
Get the maximum brightness value of a torch LED with the device_flash_get_max_brightness() function.
The function returns the maximum brightness value of the torch LED located next to the camera.
```
int error, max;
error = device_flash_get_max_brightness(&max);
```
Get and set the current brightness value of a torch LED with the device_flash_get_brightness() and device_flash_set_brightness() functions.
```
int error, val;
error = device_flash_get_brightness(&val);

error = device_flash_set_brightness(1);
```
Play and stop a custom effect of the service LED with the device_led_play_custom() and device_led_stop_custom() functions.
The custom effect of the service LED that is located on the front of a device plays.
```
int error;
error = device_led_play_custom(1000,500,0xFFFF0000, LED_CUSTOM_DEFAULT);

error = device_led_stop_custom();
```
The led_custom_flags enumerator (in mobile and wearable applications) defines the available custom effects.

Controlling the Power State

To control the device power state:

To use the power-related features of the Device API (in mobile and wearable applications), include the <device/power.h> header file in your application:
```
#include <device/power.h>
```
Lock the power state with the device_power_request_lock() function.
The function locks the given lock state for a specified time. After the given timeout, the given lock state is unlocked automatically. If the process is destroyed, every lock is removed.

The power_lock_e enumerator (in mobile and wearable applications) defines the available lock types.
```
int error;
error = device_power_request_lock(POWER_LOCK_CPU, 0);
```
Unlock the power state with the device_power_release_lock() function.
The function releases the given lock state locked before.
```
int error;
error = device_power_release_lock(POWER_LOCK_CPU);
```
Change the current power state with the device_power_wakeup() function.
The function changes the current power state to the normal or dim state:
```
int error;
error = device_power_wakeup(true);
```

Monitoring Device Changes

To monitor device changes:

To use the device change-related features of the Device API (in mobile and wearable applications), include the <device/callback.h> header file in your application:
```
#include <device/callback.h>
```

Define the device changed callback, which is called when a device status changes.

The device_callback_e enumerator (in mobile and wearable applications) defines the available callback types.

static void changed_cb(device_callback_e type, void *value, void *user_data)
{
   int val;
   if (type != DEVICE_CALLBACK_DISPLAY_STATE)
      return;
   val = (int)value;
   dlog_print(DLOG_DEBUG, LOG_TAG, "current display state : %d", val);
}

int error;
error = device_add_callback(DEVICE_CALLBACK_DISPLAY_STATE, changed_cb, NULL);

When no longer needed, unregister the callback function:

int device_remove_callback(device_callback_e type, device_changed_cb callback);

int error;
error = device_remove_callback(DEVICE_CALLBACK_DISPLAY_STATE, changed_cb);