Mozilla Hacks

Using the Battery API – Part of WebAPI

By Robert Nyman [Editor emeritus]

Posted on February 7, 2012 in Web APIs

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.

About Robert Nyman [Editor emeritus]

Technical Evangelist & Editor of Mozilla Hacks. Gives talks & blogs about HTML5, JavaScript & the Open Web. Robert is a strong believer in HTML5 and the Open Web and has been working since 1999 with Front End development for the web - in Sweden and in New York City. He regularly also blogs at http://robertnyman.com and loves to travel and meet people.

More articles by Robert Nyman [Editor emeritus]…

16 comments

  1. Gervase Markham

    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?

    February 7th, 2012 at 07:14

    1. Robert Nyman

      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.

      February 8th, 2012 at 01:11

  2. David Mulder

    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?

    February 8th, 2012 at 01:21

    1. Robert Nyman

      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.

      February 8th, 2012 at 01:42

    2. Scott Mattocks

      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.

      February 8th, 2012 at 14:23

      1. Robert Nyman

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

        February 8th, 2012 at 14:45

  3. louisremi

    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.

    February 8th, 2012 at 04:30

    1. Robert Nyman

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

      February 8th, 2012 at 14:46

  4. Pierre

    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.

    February 9th, 2012 at 08:59

    1. Robert Nyman

      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!

      February 9th, 2012 at 10:11

  5. Tim McCormack

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

    September 6th, 2012 at 13:05

    1. Robert Nyman

      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.

      September 7th, 2012 at 00:15

  6. Reuben Morais

    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 :)

    September 25th, 2012 at 07:28

    1. Robert Nyman

      Thanks! Updated the blog post with a note!

      September 26th, 2012 at 00:59

  7. Patrick Stadler

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

    November 12th, 2012 at 00:52

    1. Robert Nyman

      Nice, thank you!

      November 12th, 2012 at 06:01

Comments are closed for this article.