Mozilla

Using the Battery API – Part of WebAPI

Detecting battery level in a device or computer can help you inform the user of the current status. Within Mozilla’s WebAPI, we have the Battery API to offer that possibility.

Accessing the battery

First, it’s a matter of accessing the battery object:

var battery = navigator.mozBattery;

Properties

There are a few properties offered to detect the charging level of the battery in the device:

Battery level
Check the currenty battery level. Returns a value between 0 and 1.
Battery charging
A boolean, returning if the device/computer is currently being charged.
Battery chargingTime
Time left in seconds until it is fully charged. Available when charging.
Battery dischargingTime
Time left in seconds until it is discharged. Available when not charging.

// Get battery level in percentage
var batteryLevel = battery.level * 100 + "%";

// Get whether device is charging or not
var chargingStatus = battery.charging;

// Time until the device is fully charged
var batteryCharged = battery.chargingTime;

// Time until the device is discharged
var batteryDischarged = battery.dischargingTime;

Events

There are four events available for detecting changes to the battery’s status:

levelchange
If the battery level changes.
chargingchange
Detect if the device went from being charged to unplugged, or vice versa.
chargingtimechange
When the device’s charging time changes (when plugged in)
dischargingtimechange
When the device’s discharging time changed (when unplugged)
battery.addEventLister("levelchange", function () {
    // Device's battery level changed
}, false);

battery.addEventListener("chargingchange", function () {
    // Device got plugged in to power, or unplugged
}, false);


battery.addEventListener("chargingtimechange", function () {
    // Device's charging time changed
}, false);

battery.addEventListener("dischargingtimechange", function () {
    // Device's discharging time changed
}, false);

Device support

Battery API is supported in Firefox Beta on:

  • Android (Firefox Aurora only, for now)
  • Windows
  • Linux (for those distros that have UPower installed – bundled with most nowadays)

Right now we don’t have anyone working on the Mac OS X implemementation, so if you have the skills, we’d love to see you contribute!

Demo and code

I’ve put together a basic demo of the Battery API and code is also available in the Battery API repository on GitHub.

If you don’t experience the expected results on your device, please file a bug and we can look into it. This feature is experimental at this time, and may not be ready for production use just yet.

Update: September 26th, 2012

Since this post was published, this API has now been unprefixed and support in Mac OS X has been added.

16 comments

Comments are now closed.

  1. Gervase Markham wrote on February 7th, 2012 at 07:14:

    It would be awesome if the API had some way to indicate the level of accuracy of the measurements. For example, if I call battery.dischargingTime() and get “1356”, does that mean it’ll definitely shut down after that exact number of seconds? If not, what is the most likely range? How do I display that figure without unwarranted precision?

    1. Robert Nyman wrote on February 8th, 2012 at 01:11:

      It’s an interesting thought, although I imagine it’s quite a challenge. It completely depends on what applications you use, screen brightness etc etc. So while a value at the time of calling the Battery API can be pretty accurate, it is very relative to what the user does after that.

  2. David Mulder wrote on February 8th, 2012 at 01:21:

    With most the other API’s I can think of various way they can be utilized without too much trouble, however what/when would this be useful. The only thing I can think of is to run updates on a mobile devices when the device is powering up + time, but I can’t see any point in websites knowing /how/ much battery life I have left. Or do you expect that web applications will use this to not do heavy computations whilst battery levels are low?

    1. Robert Nyman wrote on February 8th, 2012 at 01:42:

      Exactly like you said at the end. It could be used to offer different experiences depending on battery level – like games, avoid sending/retrieving lots of data if the device might fail in the middle, perhaps a widget panel and more.

    2. Scott Mattocks wrote on February 8th, 2012 at 14:23:

      My first thought for using this was related to casual games. If I was working on a match 3 game (like Bejeweled) that had a 5 minute game length, I might use the battery API to prevent the user from starting a game if they most likely won’t be able to finish it. Or alternatively (and probably better), I might use the battery to send score updates with varying frequency depending on the expected lifetime of the user’s battery. If they are charging up, I can probably get away with only sending the score at the end of the game. If they have little time left, I might want to send updates every 30 seconds or so.

      1. Robert Nyman wrote on February 8th, 2012 at 14:45:

        Yes, good example! It’s an API – now it’s up to developers to find all kinds of use case we didn’t even think about. :-)

  3. louisremi wrote on February 8th, 2012 at 04:30:

    I’d love it if the API wasn’t just read-only but allowed us to change the battery level. Is it conceivable in a future iteration of the spec?
    I hate it that you currently need both a power plug and a charger to increase it.

    1. Robert Nyman wrote on February 8th, 2012 at 14:46:

      Hard to say, really – not sure about future features.

  4. Pierre wrote on February 9th, 2012 at 08:59:

    Is there any way to check if the device actually has a battery ?
    For now, the result is the same if the battery is fully loaded (battery.level = 1 and battery.charging = true) and if the device don’t have a battery (at least on my Linux laptop).
    I don’t see any use right now but it’s still good to know.

    1. Robert Nyman wrote on February 9th, 2012 at 10:11:

      No, those are the default values in case there isn’t access to the battery.
      There are different opinions on that, and if you have another idea, please file a bug expressing it. Thanks!

  5. Tim McCormack wrote on September 6th, 2012 at 13:05:

    I can’t say I’m really a fan of this information being provided to arbitrary web pages.

    1. Robert Nyman wrote on September 7th, 2012 at 00:15:

      I can understand that. When it comes to access to more sensitive information, storing things on your computer etc, there are usually user confirmation dialogs.

      I believe this is not being seen as such sensitive information.

  6. Reuben Morais wrote on September 25th, 2012 at 07:28:

    Hey Robert! Since February we have unprefixed this API, and I just landed OS X support for it, so you might want to update the article :)

    1. Robert Nyman wrote on September 26th, 2012 at 00:59:

      Thanks! Updated the blog post with a note!

  7. Patrick Stadler wrote on November 12th, 2012 at 00:52:

    I just released a tiny wrapper for the Batter Status API. It’s available on here: https://github.com/pstadler/battery.js

    1. Robert Nyman wrote on November 12th, 2012 at 06:01:

      Nice, thank you!

Comments are closed for this article.