Skip to content
This repository has been archived by the owner on Jun 9, 2023. It is now read-only.

Latest commit

 

History

History
181 lines (151 loc) · 14.4 KB

cp.battery.md

File metadata and controls

181 lines (151 loc) · 14.4 KB
Raw

docs » 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

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

designCapacity

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",

healthCondition

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.

isCharging

Signature cp.battery.isCharging <cp.prop: boolean; read-only>
Type Constant
Description Checks if the battery is currently charging.

isFinishingCharge

| Signature | cp.battery.isFinishingCharge <cp.prop: boolean | string; read-only> | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Constant | | Description | Checks if the battery is trickle charging; |

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.

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

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".

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.

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

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.

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