win-battery

Monitor battery status in Windows 10.

Contents

• Installation
• Usage
  • Status Object
  • API
  • Events
• Issues/Requests

Installation

This module requires a piece but not all of the Windows 10 SDK module to install properly. You can download the specific files and place them yourself (see the contained README.txt), or download the whole Windows 10 SDK.

npm install win-battery

Usage

Note that using this library on a device without a battery will result in an error being thrown from the require statement.

const battery = reqiure('win-battery');
// Throws an error if no battery present!

battery.status();
//  {
//    level: 73,
//    charging: true,
//    full: false,
//    energySaver: 'disabled',
//    dischargeTime: 500000000
//  }

battery.on('levelchange', (status) => {
    if (status.charging) {
        console.log('Power gained!');
    } else {
        console.log('Power lost...');
    }
});

Status Object

All events and functions in this library, unless otherwise specified, return a status object containing the following properties:

level

A number from 0 to 100, the percentage of battery remaining.

charging

A boolean, whether the battery is charging or not.

full

A boolean, whether the battery is fully charged or not.

energySaver

A string, 'on' if energy saver is on, 'off' if energy saver is off but ready to turn on automatically, or 'disabled' if energy saver is turned off completely or the device is charging.

dischargeTime

A number, the estimated milliseconds remaining of battery life.

This value will be Infinity when charging. It is recommended to not use this value when charging, particularly when using this value in calculations.

Properties

battery.level

read only
Same as level from status object.

battery.charging

read only
Same as charging from status object.

battery.full

read only
Same as full from status object.

battery.energySaver

read only
Same as energySaver from status object.

battery.dischargeTime

read only
Same as dischargeTime from status object.

battery.low

A number from 0 to 100, the threshold for a lowcharge event to fire. When setting, will fire a lowcharge event even if a lowcharge event has already been fired on this charge. See lowcharge event for details on this event.

Attempting to set this to anything other than a number between 0 and 100 (inclusive) will result in an error.

battery.critical

A number from 0 to 100, the threshold for a critical battery event to fire. When setting, will fire a criticalcharge event even if a criticalcharge event has already been fired on this charge. See criticalcharge event for details on this event.

Attempting to set this to anything other than a number between 0 and 100 (inclusive) will result in an error.

API

battery.status()

• Returns a status object.

Check the battery status. Allows a battery state to be recorded separately from the battery object itself.

battery.fireEvents([force])

Since 0.1.1

• Parameters:
  • force (optional) - whether to force emission of lowcharge and criticalcharge events even if they have been previously emitted. Still requires that the charge level qualifications be met.
• Returns undefined (no return).

Forces the firing of all battery change events (levelchange, chargingchange, energysaverchange, dischargetimechange), as well as any applicable charge events (fullcharge, lowcharge, criticalcharge).
If the force parameter is provided and true, lowcharge and criticalcharge events will fire even if they would normally not be due to being fired previously. See those events for more details on when this would occur.

Events

Events can be forced to fire without waiting for a change using battery.fireEvents().

levelchange

Emitted when the battery level has changed. This event is still emitted when charging.

chargingchange

Emitted when the battery starts or stops charging.

energysaverchange

Emitted when the energy saver state has changed.

dischargetimechange

Emitted when the estimated dischargeTime changes.

fullcharge

Emitted when the battery is charging and has reached full charge.

lowcharge

Emitted when the battery reaches the low charge threshold. Defaults to 20 percent.

This event will fire in a few different specific circumstances:

1. The device is running on battery power and the battery reaches the low threshold
2. The device is unplugged while the battery is less than or equal to the low threshold
3. The low threshold is set to a different value and the battery is less than or equal to the new threshold.

Once the event has fired, it will not fire due to subsequent levelchange events of lower value until the battery has been plugged in again, resulting in either case 1 or 2, or the low threshold has been modified again.

criticalcharge

Emitted when the battery reaches the critical charge threshold. Defaults to 10 percent.

This event will fire in a few different specific circumstances:

1. The device is running on battery power and the battery reaches the critical threshold
2. The device is unplugged while the battery is less than or equal to the critical threshold
3. The critical threshold is set to a different value and the battery is less than or equal to the new threshold.

Once the event has fired, it will not fire due to subsequent levelchange events of lower value until the battery has been plugged in again, resulting in either case 1 or 2, or the critical threshold has been modified again.

Issues/Requests

Issues and requests should be directed to the git repository. http://github.com/obermillerk/win-battery/issues