Saturday, November 12, 2011

GSam Battery Monitor - Users Guide

Users Guide  (Version 3.0)

Formerly known as Badass Battery Monitor, 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.

NOTE:   As of version 2.11, the name has been changed from Badass Battery Monitor to GSam Battery Monitor.  As the app has grown in popularity, a growing portion of users felt the name was not appropriate.

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. 

Main Screen:

Phone View
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.

By default the Big Battery at the top of the screen will show time left estimates.  Swipe it to the left to see other battery details, such as Temperature, Voltage, and Health.
Tablet View (Pro Version)
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 Estimates:
  1. Left - 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.  Left - 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. Left - Talk:  An estimate of how much talk time is remaining.  Note that this only shows up on devices with phones.
  4. Time 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.
Battery Usage - X% (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

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.

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.  Consider going into Airplane mode if your in very poor quality signal areas
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 #1:  Some Froyo-based phones don't correctly report a wifi active state.  Known Issue #2:  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.
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.

Avg. Life:  Over time, GSam Battery Monitor averages the amount of time your phone lasts on a given charge.  Initially, this number will fluctuate considerably, but over time it should start to level out.  You can share this number with your friends, allowing you to compare real-world phone battery life.  Does your friend with the same phone get better battery life than yours?  Why?  Note:   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.

Note 1:  You can reset the average value in the Preferences menu - but once you do, you'll have to re-establish your usage patterns.
Note 2:  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.
Note 3:  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:

App Sucker
App Sucker - Sort Options
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.

Tablet View (Pro/Kindle Edition)
The Professional and Kindle Fire versions of GSam Battery Monitor look somewhat different when run on Tablets, but the basic function is the same. 

  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 GPS Time Used:  Sort by the amount of time the app used the GPS.  GPS usage is VERY battery intensive.
  7. 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.
  8. 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.
  9. 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.
  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.
Kernel Wakelocks

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.
  • 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

Custom References:

By default, GSam Battery Monitor shows you statistics based on when you last unplugged your phone.  You can chose to show statistics based on the last time your phone was fully charged (Android changed this to be their default for the Battery Use app in Gingerbread), or you can create a custom reference.

Creating a custom reference lets you see utilization from any chosen point in time (vs last unplugged or last charged).  To create a reference, simply chose the Add Custom Reference task from the main screen menu.  This reference will remain in effect until you either remove it, restart your phone, or plug and unplug your phone.


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?

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.

Others:  This is one of the more interesting ones. It plots many events including GPS, In Call, Wifi On, Screen On, and Active (screen on or wakelock held).


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

View Statistics Since:    For more information, see the Custom Reference section above.  Note that when you remove a custom reference via the main screen menu, this value returns to it's default (last unplugged).

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.
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.


GSam Battery Monitor uses the following Android permissions.

  • 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.
  • 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 KitKat devices, this is no longer used.
  • Used in conjunction with the INTERNET permission.  It will check if the device has network access before trying to use the network.
  • 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.
  • 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( 
    07-13 16:54:07.727 E/com.gsamlabs.bbm.lib.NotifyingService(10114): at android.os.Parcel.readException( 
    07-13 16:54:07.727 E/com.gsamlabs.bbm.lib.NotifyingService(10114): at$Stub$Proxy.getStatistics( 
  • 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.  
  • 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. 
  • 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. 
  • 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.