GSam Battery Monitor - Users Guide

---

Users Guide  (Version 3.35)

---

GSam Battery Monitor provides more complete monitoring capabilities than the built in Battery Usage app in Android.  It relies on the same battery statistic data, however it lets the user drill down and find out much more detail.

---

Standard vs Enhanced Statistics Mode:

GSam operates in two modes - Standard, and Enhanced Statistics.  In Standard mode, GSam attempts to collect all statistics itself.  Since KitKat, Android has made this harder and harder each release as they clamp down on security settings.  This is a GOOD thing, but it makes the standard collection mode less useful over time.

Enhanced Stats:  By enabling enhanced statistics (Menu -> More -> Enable More Stats), GSam is able to access all raw battery stats that are maintained by the underlying platform.  This does not require root, but it does require some manual steps by the user.  The app will walk you through the steps to enable this.  It's a pain, but is strongly recommended for for Nougat and beyond.

In Android Pie and later, even with enhanced stats enabled, we will use Standard Mode to track system wide stats, and Enhanced mode to track application specific stats.  This is due to a change Android made restricting what APIs (programming interfaces) any app targeting Pie or later can call.  In general you won't notice the difference, but if you do, you can re-enable the fully enhanced mode by turning allowing apps to access hidden APIs.

Some of the statistics shown in this guide may not be available without the Enhanced Stats enabled.

---

Main Screen:

Main Screen

Tablet View (Pro Version)

The main screen of GSam Battery Monitor provides you with time estimates, and shows the power drain of various components of your phone such as the Screen, Bluetooth, etc.  You can access additional function via the Menu button, or by clicking on a row in the table with a blue > icon on the right.

The Professional and Kindle Fire versions of GSam Battery Monitor look somewhat different when run on Tablets, but the basic function is the same.

Time Remaining Estimates:

1. Average:  An estimate of remaining time based on usage since the phone was unplugged.  Some aspects of this may be controlled through the Power Per Percent setting in the Preferences.  This setting should get better over time as the app learns more about your device. Note:  The Professional and Kindle Fire editions will show an average for time spent active on devices that have no phones (or that are in 'airplane' mode).  This allows a more accurate prediction of how much active use you can get out of the device.
2. Last Xm:  An estimate of remaining time based on the device usage over the last X minutes.  The maximum X can be is controlled through the Calculate Time Left preference.  X may be a small number depending on when statistics were last collected.  Statistics aren't collected while the device is not in use, so if you pick up your device after extended sleep time, this number may revert back to 1 and slowly climb as you use the device again.
3. Talk Time:  An estimate of how much talk time is remaining.  Note that this only shows up on devices with phones.
4. To Full:  When charging, this represents how long it will take to fully charge the device.  Charge time can vary based on charger type (USB vs A/C) and usage of the device while it's charging.

Used X% in TIME:  X shows the percent of battery consumed based on your time reference (by default since you last unplugged the phone).  The TIME section shows the amount of elapsed time since the time reference (typically how long since you unplugged your phone).  All statistics have been gathered since the time reference.

Δ %/h - TIME Active:  The battery change per hour since the time reference.  The time active represents the time the device has spent in interactive mode (screen on, held awake, etc.)

Phone:  How long have you actually spent on the phone - talk time.  This is only visible on devices with a phone.

Screen:  How long has the screen been on.  Dig into this field to see details of how the screen affects power usage:

• Screen Doze (8.1 and beyond):  Amount of time the Always On Display was active, and the percent of overall time compared to the time the screen spent powered off.
• Discharge While On/Off:  Percent discharge of the battery while the screen was on/off.  Note that this does not represent only the consumption by the screen itself.  Tip: A high discharge amount while screen is off may indicate a problem app running in the background.
• Screen Brightness:  The time spent and percent of power used at a given brightness setting.  The power is a percentage of the screen power consumed, not a percentage of overall power consumed (and so will always add up to 100%).

Phone Radio:  How long has the phone had a signal.    Click on this row to get more details, including how long the phone has been at various signal strengths.  You can also see the amount of data transferred over your mobile network.

Battery Saving Tip:  When your phone spends a long time at lower signal strengths, your battery will be consumed much faster. 

Wifi Active:  How long has your wifi radio been on with a signal?  Click on this row to see the amount of data transferred over your wifi network.  Known Issue:  When you turn on and off the Wifi radio, all data transferred stats are reset for wifi.  So if you turn this on and off a lot, treat your transfer stats with a grain of salt.

Battery Saving Tip:  Android is pretty efficient about not using the Wifi unless it's needed, and data transfer over wifi uses less power than over 3G.  So leaving it always on isn't a bad thing - just be careful if you have a very weak signal, and it keeps connecting and disconnecting.

Held Awake:  This is the amount of time that the phone appears to be sleeping (screen is off), but some application is preventing the phone from going into a deep sleep.   This is one of the chief indicators of unneeded battery drain.   This is similar to the 'Idle' value in the built-in battery usage, however we don't include the screen on time to help with clarity.  Dig into this field to get more details:

• Deep Sleep:  Amount and percent of time the device has spent in deep sleep with the CPU in it's lowest power state.  
• Doze Time:  Android supports a light and deep doze mode.  The device will go into doze mode when Android detects it's not being used to save on battery.
• % Screen Off:  The percent of time the device was in doze mode compared to the amount of time the screen was off.  The higher this value is, the more benefit your getting from doze.
• Discharge Screen Off:  The percent of battery discharge while the device is in doze mode compared to the amount while the screen is off.
• Averages Per Complete Charge:  The lifetime averages that your device spends in doze mode for a complete discharge cycle.  This is an estimated value since it's rare that a complete (100%) discharge cycle occurs.  The max value represents the maximum measured value.

Battery Saving Tip:  Apps should not wake your phone up out of a deep sleep.  If the Held Awake time seems high to you, go into the App Sucker  task, and sort by 'Time Held Awake', and 'Num Times Waking Device'.  This can help you identify a misbehaving app

Bluetooth:  The amount of time the Bluetooth radio is on.  We've seen cases where a misbehaved bluetooth driver doesn't allow the phone to sleep, however for the most part, leaving bluetooth on consumes negligible power.

App Usage:  This shows the % of power used by all apps on the phone.  Click on this row to go into the App Sucker task where you can view all the details.

Averages Per Complete Charge:  Over time, GSam Battery Monitor averages the amount of time your phone lasts and amount of screen on time on a given charge cycle.  Initially, this number will fluctuate considerably, but over time it should start to level out.  This is an estimated value since it's rare that a complete (100%) discharge cycle occurs.  The max value represents the maximum measured value.

• The Professional and Kindle Fire editions will show an average life spent active (not including Standby) for devices without phones.  This gives a better prediction of average life for devices that have a long standby time.
• You can reset the average value in the Preferences menu - but once you do, you'll have to re-establish your usage patterns.
• The average is calculated whenever you plug your phone in to charge.  You have to have used it for a good amount of time however, or that number will be ignored.  For example, if you only used your phone for 15 minutes and re-plugged it back in, GSam Battery Monitor doesn't include that time in it's averaging.
• On devices without phones, the standby time can be very large (many days).  The time you're most interested in is your in-use time, and so for such devices, Avg. Life shows your in-use time rather than your overall average battery life.  If you want to see the overall average, click the button and share to an application, and view the text provided - it will include both overall and in-use averages.

---

App Sucker:

The App Sucker tasks shows all applications that have consumed resources on your device since the given time reference.  You can sort the apps by a number of categories.  Clicking on an app will show you lots of gory details about that app and it's usage.

1. View % Power Used:  Sort by the percent of overall power used by the application
2. View % Power (Background CPU Only):  Same as % Power Used, except foreground CPU usage is removed.  This lets you see what apps are using the most power when they're running in the background.  If you're actively using an app (running in the foreground), it's CPU utilization isn't quite as interesting from a battery saving perspective - you may really want to know who's consuming resources in the background.
3. View CPU Minutes Used:  Sort by the amount of CPU used by the application.
4. View CPU (Background CPU Only):  Same as CPU used except foreground CPU usage is removed.  For more information, see % Power (Background CPU Only).
5. View Network Data Used:  Sort by the amount of network data (wifi or 2/3/4G) used by the app.  Note that depending on how the app gets it's data, not all apps will show usage even when you think they should.  This is a limitation of how Android collects it's statistics.
6. View Sensor Time Used:  Sort by the aggregate amount of time an app has used various sensors.   This let's you see apps that may be using sensors improperly and not releasing them when they should - this can be quite power draining.  NOTE:  By default, GSam collects sensor data usage, but does not use it to calculate app power draw because of bugs in many devices estimate for a sensor power draw.  You can change this behavior in the preferences.
7. View Time Held Awake:  Sort by time this app has kept the device awake.   This looks at partial wake locks - the type that keep the device awake even when the screen is off.   This is a warning sign of a misbehaving app - however there are many many valid reasons for using partial wake locks - even when the sreen is on, so don't accuse an app of being bad just because it uses these.
8. View Num Times Waking Device:  Lists the number of times an app has done something which might wake the device.  Note that this doesn't mean the app DID wake the device. High values here may be a red herring - so use these with caution.
9. View GPS Time Used:  Sort by the amount of time the app used the GPS.  GPS usage is VERY battery intensive.
10. View Kernel Wakelocks:  This is a very advanced option, and is not for the average user.  The kernel is essentially your core Android operating system.  This will list the wakelocks that have been held while the screen is off, but since this is the core operating system, there is little you can do about it directly.  Click on the wakelock and then you will get the option to Google it.  For more information, see the Kernel Wakelock blog post.

 
App Details Screen:  

When clicking on an app in the App Sucker task, you will see a screen showing

lots of details about the app.  Most data in this screen should be self explanatory.  Keep in mind that an app may be a collection of processes and packages which we attempt to show.

• Usage Details:  The usage details should for the most part be self-explanatory.  Note that some functions that the app may perform do not always get attributed to the app.  For example, some network usage may be attributed to a different application which performs the service function.
• Wakelock Detail:  This shows the amount of time, number, and name of the application wakelocks.  Apps that wake up the phone a lot, or spend a lot of time holding wakelocks can be problematic, but aren't always.  It's perfectly reasonable for example that a game will hold a wakelock keeping the screen on for as long as your playing the game.
• Manage :  The Manage button takes you to the Manage Application screen for the given app.  This allows you to uninstall, force stop the app, etc.  This is the standard application manage screen for your device

---

View Statistics Since:

By default, GSam Battery Monitor shows you statistics based on when you last unplugged your phone.  However GSam offers you other ways to view yours stats as well:

• Since Last Unplugged:  This is the default for GSam, and show you stats since you last unplugged (or restarted) your device.
• Since Last Full Charge:  This shows you stats since the last full charge (> 90%).  Note that this may mean you see a %used of > 100% if you charged your phone to less than 90%.
• Since Screen Off:  This shows you stats since the screen was last turned off.  Every time the screen turns off, GSam will create a reference point.  This helps diagnose apps that are consuming power in the background while the screen is off.
• Since Now:  This lets you create a custom reference point.  You can only have 1 custom reference active at a time, and this reference will get reset on reboot or unplug.

---

Charts:

The charts task let's you see your battery % over time with various overlay supports.  The overlays let
you see what events were happening at a given point in time.  Do you see a precipitous drop in battery?   Try and see what event caused that - perhaps you were in an active phone call?  Perhaps you had GPS on?

Others:  This is one of the more interesting ones. It plots:

• GPS - shows when GPS was active
• In Call - shows time spent in a phone call
• Wifi - shows time spent with wifi actively connected
• Screen - shows time spent with the screen on
• AOD - Always On Display (new for 8.1) shows time spent with the screen off, but the Always On Display (Ambient Display) active.
• Active - shows time that the device was active.  Either with the screen on, or with active wakelocks.  You may need to zoom in to get a more accurate picture.
• Doze - shows the time spent in Doze mode.  The darker color indicates Deep Doze.

Temperature:  This plots the battery temperature. Typically when the temperature of your batter increases, it's because your battery is getting heavy use, so expect to see  the battery drop when the temperature rises

Phone Signal:  A poor phone signal is often a cause of battery drain.  You can plot your phone signal quality alongside your battery drain.

Rate Of Change:  Shows the rate of change (battery discharge).  This can be useful to quickly zoom in on problem areas.

CPU:  This plots the CPU Utilization and CPU Average Frequency.  This is sampled data over time, and so should not be taken too literally.  That is, look at the overall trend, not a specific datapoint.

---

Notification / Status Icon:

A status icon will appear in the status bar indicating the current percent of battery remaining.  You can customize this icon by theme in the Preferences.  There are add-on icon packs as well, some created by GSam Labs, and some created by third parties.

In the notification menu, you can see the latest time remaining estimates. For more on the Estimates, see the Main Screen section below.  Clicking on the notification message will launch the app, allowing you to get to the Main Screen.

You can chose not to show the notification icon at all if you already have an alternative way to see the battery percent.  Even better, on Jelly bean you can show the notification status without showing an icon.

An Overlay icon is also supported (requires the Icon-Pack add-on). This allows you to overlay the stock battery icon in the top right of the screen. It's size and location is fully configurable, and it should automatically hide when an app is in full-screen mode.  For more information, see the Overlay blog post.

Widgets:  There are 2 widgets supported and are pictured on the right.  You need to have the app installed on internal storage in order to use widgets.  You can add them to any screen just like any other widget.

---

Preferences:

Most preferences are self explanatory.  The ones below require more explanation:

Alarms:  You can set alarms to notify you when your battery is fully charged, or when it reaches a certain low-threshold.  These alarms will audibly and visually notify you.   The 'Hot Battery' alarm will notify you when your battery gets too hot.  The alarm will stay in your notification tray until your battery gets back to a normal temperature.

Allow Anonymous Usage Reporting:  This will report usage information using the Flurry service.  If you desire, you can turn this off - but we're using this to help improve the app - no personal information is sent.   Using Flurry allows us to do the following:

1. For every 'device' using GSam Battery Monitor, we can see some basic device information - the type of device, the version of Android, and the version of GSam Battery Monitor in use.  No personal information of any sort is sent.
2. See how users are using the app.  This lets us make improvements to the application over time.
3. 1. 
      
   Note:  If you turn his off, you will see Ads on the Free version (which is otherwise, ad-free).  No ads will ever be seen on the paid version.

Device Power Profiles:  Every device is shipped with a power profile that allows the manufacturer to indicate how much power a given function uses.  For example, how much power does a phone call use, how much does the screen use at various brightness settings, etc.  All % Utilization values depend on these - so if the underlying reference data is bad, so will our statistics.    You can chose to use a custom profile and edit the values - but use caution here.  Only use this feature if something is clearly wrong.  For example, I saw a Samsung phone where the Sensor utilization was really out of whack (using the Accelerometer for 5 minutes claimed to use 95% of the devices power).

Note:   Adjust the Device Power Profile with care.  There are very few devices that need adjustment.

Power Per Percent:  You shouldn't touch this setting except if you change your power profile.  If you do, then zero out the value in here.   This value gets used to calculate estimated times remaining, so if your time remaining seems completely wrong, you can adjust these numbers.  They are automatically generated based on your usage, and so if you manually change things, you may want to set the TOTAL_PERCENT_MEASURED value to be very high as the higher it is, the less current usage will affect the POWER_USED_PER_PERCENT_DROP.

---

Permissions:

GSam Battery Monitor uses the following Android permissions.

android.permission.INTERNET:

• Used to send anonymous statistics using the Flurry and Google Analytics service (user can choose to disable this). These statistics allow the development team to learn how users are using the app.  No identifying data is sent.
• Used to display ads (only on the Free version if user has chosen to view Ads)
• Used to display a chart in the Charts view using the google chart API.

android.permission.BATTERY_STATS:   

• Required to retrieve detailed statistics on battery usage.  All detailed data such as how long various resources are in use come from this permission.
• For Lollipop and beyond, you need to manually enable this via ADB (See Enhanced Stats)

android.permission.ACCESS_NETWORK_STATE:  

• Used in conjunction with the INTERNET permission.  It will check if the device has network access before trying to use the network.

android.permission.RECEIVE_BOOT_COMPLETED:   

• Let's the battery monitor start up with your device is started.  You can disable this in the preferences if you want it to start manually.

 android.permission.BLUETOOTH:  

• An Android bug introduced in ICS requires the bluetooth permission when reading the battery statistics.  This happens particularly with some car / bluetooth docks.  It should not be required, but it's added to ensure that devices with this bug can still obtain battery stats.
• Rest assured, the battery monitor does not connect to any bluetooth devices.  This is here purely to work around a bug in the Android OS.  For those that are interested, here is the stack trace showing the call to getStatistics failing due to the bluetooth permission:
07-13 16:54:07.727 E/com.gsamlabs.bbm.lib.NotifyingService(10114): Caused by: java.lang.SecurityException: Need BLUETOOTH permission: Neither user 10120 nor current process has android.permission.BLUETOOTH.   

07-13 16:54:07.727 E/com.gsamlabs.bbm.lib.NotifyingService(10114): at android.os.Parcel.readException(Parcel.java:1327) 

07-13 16:54:07.727 E/com.gsamlabs.bbm.lib.NotifyingService(10114): at android.os.Parcel.readException(Parcel.java:1281) 

07-13 16:54:07.727 E/com.gsamlabs.bbm.lib.NotifyingService(10114): at com.android.internal.app.IBatteryStats$Stub$Proxy.getStatistics(IBatteryStats.java:539) 

android.permission.READ_EXTERNAL_STORAGE:   

• Allows selection of notification tones (for alarms) that the user has stored on their external storage (SD Card).
• This is a new for Jelly Bean.  Previously, Android allowed any app to read from external storage, however new in Jelly Bean, if the user configures the Developer Options -> Protect SD Card option, then apps will need this permission.  

android.permission.READ_PHONE_STATE:   

• Allows GSam to track when your phone is in use.  On the main screen GSam shows the amount of time and power drain when you are in a call, so it's important to know when the phone is being used.  Rest assured, we do NOT use this to track anything other than a simple 'in-use' statistic.  We don't track or record any information about calling numbers, etc.
• This is a new for KitKat.  Previously these statistics were available directly from Android without manual tracking.  In KitKat, access was removed, so we need to track this ourselves.  See this post for more information. 

android.permission.ACCESS_WIFI_STATE:   

• Allows GSam to track when your wifi is turned on.  On the main screen GSam shows the amount of time and power drain when your wifi is on, so it's important to know when it is being used.  Rest assured, we do NOT use this to track anything other than a simple 'in-use' statistic.  We don't track or record any information about accessed devices, etc.
• This is a new for KitKat.  Previously these statistics were available directly from Android without manual tracking.  In KitKat, access was removed, so we need to track this ourselves.  See this post for more information. 

com.gsamlabs.permission.BATTERY_STATS:   

• This is used to retrieve BATTERY_STATS on KitKat (4.4+) based devices when paired with the Root Companion app.  The Root Companion app may be used by other apps, and so it is important that users are notified that a consuming app is retrieving Battery Stats.   Users on Android 4.3 and earlier can ignore this permission.