Internationalisation
Bundled Plugins API
battery
Provides access to various properties of the battery. Each of these properties is a cp.prop, so it can be watched for changes. For example:
1
local battery = require("cp.battery")
2
battery.powerSupply:watch(function(value)
3
print("Now using "..value)
4
end)
Copied!
This will print "Now using AC Power" or "Now using Battery Power" whenever the power supply changes.
By default the watcher initialises in a "stopped" state, and must be started for the cp.prop watchers to trigger.

API Overview

API Documentation

Constants

amperage

Signature
cp.battery.amperage <cp.prop: number; read-only>
Type
Constant
Description
Returns the amount of current flowing through the battery, in mAh.
Notes
  • A number containing the amount of current flowing through the battery. The value may be: Less than zero if the battery is being discharged (i.e. the computer is running on battery power) Zero if the battery is being neither charged nor discharded** Greater than zero if the bettery is being charged

capacity

Signature
cp.battery.capacity <cp.prop: number; read-only>
Type
Constant
Description
Returns the current capacity of the battery in mAh.
Notes
  • This is the measure of how charged the battery is, vs the value of cp.battery.maxCapacity().

cycles

Signature
cp.battery.cycles <cp.prop: number; read-only>
Type
Constant
Description
Returns the number of discharge cycles of the battery.
Notes
  • One cycle is a full discharge of the battery, followed by a full charge. This may also be an aggregate of many smaller discharge-then-charge cycles (e.g. 10 iterations of discharging the battery from 100% to 90% and then charging back to 100% each time, is considered to be one cycle).
Signature
cp.battery.designCapacity <cp.prop: number; read-only>
Type
Constant
Description
Returns the design capacity of the battery in mAh.

health

Signature
cp.battery.health <cp.prop: string; read-only>
Type
Constant
Description
Returns the health status of the battery; either "Good", "Fair" or "Poor",
Signature
cp.battery.healthCondition <cp.prop: string; read-only>
Type
Constant
Description
Returns the health condition status of the battery:

isCharged

Signature
cp.battery.isCharged <cp.prop: boolean; read-only>
Type
Constant
Description
Checks if the battery is fully charged.
Signature
cp.battery.isCharging <cp.prop: boolean; read-only>
Type
Constant
Description
Checks if the battery is currently charging.
| Signature | cp.battery.isFinishingCharge <cp.prop: boolean | string; read-only> | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Constant | | Description | Checks if the battery is trickle charging; |
Signature
cp.battery.maxCapacity <cp.prop; number; read-only>
Type
Constant
Description
Returns the maximum capacity of the battery in mAh.
Notes
  • This may exceed the value of cp.battery.designCapacity() due to small variations in the production chemistry vs the design.
| Signature | cp.battery.otherBatteryInfo <cp.prop: table | nil; read-only> | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Constant | | Description | Returns information about non-PSU batteries (e.g. bluetooth accessories). If none are found, nil is returned. |
Signature
cp.battery.percentage <cp.prop; string; read-only>
Type
Constant
Description
Returns the current source of power; either "AC Power", "Battery Power" or "Off Line".

psuSerial

Signature
cp.battery.psuSerial <cp.prop: number; read-only>
Type
Constant
Description
Returns the serial number of the attached power supply, or 0 if not present.
Signature
cp.battery.timeRemaining <cp.prop: number; read-only>
Type
Constant
Description
The amount of battery life remaining, in minuges.
Notes
  • The return value may be: Greater than zero to indicate the number of minutes remaining. -1 if the remaining batttery life is being calculated.** -2 if there is unlimited time remaining (i.e. the system is on AC power).
Signature
cp.battery.timeToFullCharge <cp.prop; number; read-only>
Type
Constant
Description
Returns the time remaining for the battery to be fully charged, in minutes, or `-`` if still being calculated.

voltage

Signature
cp.battery.voltage <cp.prop: number; read-only>
Type
Constant
Description
Returns the current voltage of the battery in mV.

watts

Signature
cp.battery.watts <cp.prop: number; read-only>
Type
Constant
Description
Returns the power entering or leaving the battery, in W.

Variables

_watcher

Signature
cp.battery._watcher -> hs.battery.watcher object
Type
Variable
Description
The battery watcher.

Functions

start

Signature
cp.battery.start() -> none
Type
Function
Description
Starts the battery watcher.
Parameters
  • None
Returns
  • None

stop

Signature
cp.battery.stop() -> none
Type
Function
Description
Stops the battery watcher.
Parameters
  • None
Returns
  • None
Last modified 1mo ago