# cp.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:

local battery = require("cp.battery")
battery.powerSupply:watch(function(value)
    print("Now using "..value)
end)

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

Constants - Useful values which cannot be changed

  • amperage
  • capacity
  • cycles
  • designCapacity
  • health
  • healthCondition
  • isCharged
  • isCharging
  • isFinishingCharge
  • maxCapacity
  • otherBatteryInfo
  • percentage
  • psuSerial
  • timeRemaining
  • timeToFullCharge
  • voltage
  • watts

Variables - Configurable values

  • _watcher

Functions - API calls offered directly by the extension

  • start
  • stop

# 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
Source src/extensions/cp//battery.lua line 19

# 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().
Source src/extensions/cp//battery.lua line 29

# 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).
Source src/extensions/cp//battery.lua line 36

# designCapacity

Signature cp.battery.designCapacity <cp.prop: number; read-only>
Type Constant
Description Returns the design capacity of the battery in mAh.
Notes None
Source src/extensions/cp//battery.lua line 43

# 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",
Notes None
Source src/extensions/cp//battery.lua line 47

# healthCondition

Signature cp.battery.healthCondition <cp.prop: string; read-only>
Type Constant
Description Returns the health condition status of the battery:
Notes None
Source src/extensions/cp//battery.lua line 52

# isCharged

Signature cp.battery.isCharged <cp.prop: boolean; read-only>
Type Constant
Description Checks if the battery is fully charged.
Notes None
Source src/extensions/cp//battery.lua line 59

# isCharging

Signature cp.battery.isCharging <cp.prop: boolean; read-only>
Type Constant
Description Checks if the battery is currently charging.
Notes None
Source src/extensions/cp//battery.lua line 63

# isFinishingCharge

Signature cp.battery.isFinishingCharge <cp.prop: boolean | string; read-only>
Type Constant
Description Checks if the battery is trickle charging;
Notes None
Source src/extensions/cp//battery.lua line 67

# maxCapacity

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.
Source src/extensions/cp//battery.lua line 72

# otherBatteryInfo

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.
Notes None
Source src/extensions/cp//battery.lua line 79

# percentage

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".
Notes None
Source src/extensions/cp//battery.lua line 83

# 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.
Notes None
Source src/extensions/cp//battery.lua line 87

# timeRemaining

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).
Source src/extensions/cp//battery.lua line 91

# timeToFullCharge

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.
Notes None
Source src/extensions/cp//battery.lua line 101

# voltage

Signature cp.battery.voltage <cp.prop: number; read-only>
Type Constant
Description Returns the current voltage of the battery in mV.
Notes None
Source src/extensions/cp//battery.lua line 105

# watts

Signature cp.battery.watts <cp.prop: number; read-only>
Type Constant
Description Returns the power entering or leaving the battery, in W.
Notes None
Source src/extensions/cp//battery.lua line 109

# Variables

# _watcher

Signature cp.battery._watcher -> hs.battery.watcher object
Type Variable
Description The battery watcher.
Notes None
Source src/extensions/cp//battery.lua line 133

# Functions

# start

Signature cp.battery.start() -> none
Type Function
Description Starts the battery watcher.
Parameters
  • None
Returns
  • None
Notes None
Examples None
Source src/extensions/cp//battery.lua line 147

# stop

Signature cp.battery.stop() -> none
Type Function
Description Stops the battery watcher.
Parameters
  • None
Returns
  • None
Notes None
Examples None
Source src/extensions/cp//battery.lua line 160

© Copyright 2025 LateNite Films Pty Ltd. All rights reserved.