battery

UPower’s display device: charge, state and time estimates.

text {
    content = mantle.battery:map(function(battery)
        local seconds = battery and battery.present and battery.time_to_empty
        if not seconds then
            return ""
        end
        return string.format("%d:%02d left", seconds // 3600, seconds % 3600 // 60)
    end),
}

State

mantle.battery:get() returns BatteryState, nil before the first push. A field marked ? may be absent.

mantle.battery’s payload. No battery, or no UPower, reads present = false and defaults.

Field	Type	Description
`percent`	`integer`	UPower’s `Percentage`, rounded to `0` to `100`; a spurious `0` while not draining keeps the last value.
`present`	`boolean`	UPower’s display device is a present battery. Check it before drawing the other fields.
`state`	`BatteryStatus`	What the battery is doing; see `BatteryStatus`.
`time_to_empty?`	`integer`	Seconds until flat, or `nil` while UPower has no estimate.
`time_to_full?`	`integer`	Seconds until full, or `nil` while UPower has no estimate.

`BatteryStatus`

battery.state: UPower’s Device.State by name, e.g. b.state == "PendingCharge".

Value	Description
`"Unknown"`	No answer: UPower unreachable, an unknown state number, or a display device that is not a battery.
`"Charging"`	Taking current from an adapter.
`"Discharging"`	Draining.
`"Empty"`	Flat.
`"FullyCharged"`	Charged and holding.
`"PendingCharge"`	On mains, neither draining nor taking current: a charge limit, weak charger or thermal pause.
`"PendingDischarge"`	Waiting to discharge.

Actions

None: read-only, so any method but get, map and on_change raises.

Backend

Contract	Behavior
Source	UPower’s `DisplayDevice`, the composite of every battery
Updates	Re-reads every field on each `PropertiesChanged`; no timer, since UPower already polls the hardware
No battery or no UPower	`present = false`, `percent = 0`, `state = "Unknown"`, no time estimates

How do I…

Show a battery label with every `nil` state handled

text {
    foreground = mantle.battery:map(function(battery)
        return (battery and battery.present and battery.percent <= 15) and "#F38BA8" or "#CDD6F4"
    end),
    content = mantle.battery:map(function(battery)
        if battery == nil then
            return "…"
        elseif not battery.present then
            return ""
        end
        return string.format("%d%%%s", battery.percent, battery.state == "Charging" and " +" or "")
    end),
}

See also: Battery indicator recipe; power for on-battery and power draw.

Source: supervisor/src/capabilities/battery/

Keyboard shortcuts

Mantle