3.5 KiB
Battery Status
Press Cthulhu+Shift+B in either keyboard layout to report battery status. With one battery, hear and read a short message such as “Laptop battery, discharging, 90 percent.” With several batteries, an internal Battery Menu lists each device with its status and charge. Use Up and Down to browse; Enter and Escape both close without additional output. The shortcut is a suggestion and can be remapped in Cthulhu.
Battery Status reads the UPower service over the system D-Bus. It does not run
the upower command, require root, or change power settings. Install and enable
your distribution's UPower service if it is missing. An unavailable service
produces “Battery information unavailable.” A successful read with no batteries
produces “No batteries detected.” If some devices cannot be read, readable
results are accompanied by “Some battery information is unavailable.”
The kernel, drivers, and hardware determine which laptop, controller, headset, mouse, UPS, and other batteries UPower can expose. Device model names may be generic. Unknown charge is reported explicitly; unknown charging state is omitted. Devices with only coarse levels use words such as “low” or “normal” rather than an artificial percentage. Precise percentages are rounded to whole numbers. System batteries appear first; duplicate names have numbered suffixes. UPower's combined DisplayDevice and AC adapters are excluded.
Each invocation reads UPower's latest reported values, with a one-second read limit to fit Cthulhu's two-second command deadline. An open menu is a snapshot: close and invoke again to refresh. There are no background notifications, time estimates, hardware-statistics views, or sysfs fallbacks. UPower may itself cache values between device updates. See the UPower device API.
Build and verify
From the repository root, run make check. Build release artifacts with
python3 -B tools/package.py --tentacle battery-status. This prepares amd64 and
arm64 packages and a proposed catalog under dist/; it publishes nothing.
The source catalog intentionally advertises no release downloads yet.
For an actual-host diagnostic without speech or changes to the running reader,
run from the adjacent cthulhu checkout:
GOCACHE=/tmp/cthulhu-cache go run ./cmd/tentacle-host -presentation -interaction -command battery-status "$PWD/../cthulhu-tentacles/battery-status/bin/battery-status"
Use the development launch procedure in Hello World's README for live testing,
with launch ID battery-status, the matching executable, and both Presentation
and Interaction grants. Review and test before submission, as required by
CONTRIBUTING.md. Verify:
- The shortcut, learn-mode description, and remapping in both layouts.
- A single battery speaks and brailles its status without a menu.
- With another battery-bearing device connected, the Battery Menu opens, Up/Down reads each row, and Enter and Escape dismiss it silently.
- Reopening reflects updated devices and charge; no combined duplicate appears.
- Speech preferences and interruption, connected Braille, screen lock/handoff, disable/re-enable, and normal reading after closing the menu still work.
Automated tests use injected device sources for absent/unavailable services, partial failures, and battery combinations, without altering the system service. Cross-building arm64 does not establish execution on arm64; test that package on matching hardware before publication.
Licensed GPL-3.0-or-later; see LICENSE.