PiTopBatt

PiTopBatt
=========

PiTopBatt shows the state of the battery of the pi-top [1] laptop
under piAROS, the AArch64 version of AROS for the Raspberry Pi.

The pi-top [1] battery pack has a "Smart Battery" gauge (SBS standard)
on the I2C bus at address 0x0B. PiTopBatt reads it directly through the
hardware I2C controller of the Raspberry Pi. No driver and no extra
library are needed.

PiTopBatt only READS the battery. It never writes any setting to the
gauge and does not touch the pi-top hub.


Features
--------

 - Charge in percent with a gauge and the time left
   (or the time to full while charging)
 - Power source: on battery, charging, full, on charger
 - Current (mA) and power (W), voltage, temperature
 - Details window: remaining, full and design capacity, battery health
   in percent, cycle count, what the battery asks of the charger,
   decoded status bits and alarms, I2C statistics
 - Warnings: battery low (15 % or less), empty, too hot, over-charged
 - Mini mode: a small strip on the screen title bar, e.g. "77% 10:20",
   red with "!" on a warning; it can be dragged left and right
 - Save report: everything in one text file, RAM:PiTopBatt-report.txt
 - Refresh every 2, 5, 10, 30 or 60 seconds
 - Settings are kept in ENVARC:PiTopBatt.prefs


Requirements
------------

 - pi-top [1] laptop (the first, grey/green model with the keyboard)
 - Raspberry Pi 3 or 4 running piAROS (AArch64)
 - Raspberry Pi 5 is NOT supported (its GPIO and I2C are in the RP1
   chip); the program refuses to start on it
 - pi-top [3], pi-top [4] and UPS boards for the Pi use other chips and
   are not supported


Installation
------------

Copy PiTopBatt and PiTopBatt.info to any drawer, e.g. SYS:Utilities.
To start it automatically, put a copy (or a link) into SYS:WBStartup
and add the tooltype DONOTWAIT to its icon.

Please copy the files to an AROS disk first; do not run the program
directly from a FAT-formatted USB stick.


Usage
-----

Double-click the icon or start "PiTopBatt" from the Shell.

The main window shows the charge, the power source and the main values.
"Details..." opens the second window. "Mini" (or menu Project ->
Mini mode) replaces the window with the small strip on the screen title
bar; click the strip to get the window back, click "x" to quit. The
right mouse button over the active strip opens a small menu.

If "Start in mini mode" is ticked, the next start goes straight to the
strip.


Tooltypes / Shell arguments
---------------------------

The icon contains these tooltypes, switched off with brackets. Remove
the brackets to use one.

  MINIX=75          left edge of the strip, percent of the screen width
                    (if set, a dragged position is not remembered)
  MINIY=0           top edge of the strip, pixels
  MINIH=16          height of the strip, pixels (default: title bar)
  MINIBAR=NO        no gauge in the strip, only the text

From the Shell:

  PiTopBatt [MINI] [MINIX=n] [MINIY=n] [MINIH=n] [NOBAR]


Status and known limits
-----------------------

This is the first public version.

 - Reading the battery was tested on a real pi-top [1] with a Raspberry
   Pi 3: all values are read correctly; the gauge sometimes needs a
   second or third attempt, which the program handles by itself.
 - The pi-top [1] exists with two hub versions (v1 and v2). The battery
   is read the same way on both, but only one of them has been tested
   so far.
 - Warnings are shown in the window and in the strip only; there is no
   requester and no sound yet.
 - PiTopBatt uses the I2C bus on GPIO 2 and 3 only for a moment at each
   reading and frees it again, so other programs can use the bus in
   between. Two programs reading the bus at exactly the same moment
   could still disturb each other.

If something does not work, please use "Save report..." and send the
file RAM:PiTopBatt-report.txt to the author.


History
-------

0.4 (18.10.2026)  First public version, Zune window and mini mode.
                  (0.1 - 0.3 were text-only test programs.)


Source code
-----------

PiTopBatt is built on PiSensors, the author's small C library for the
Raspberry Pi GPIO and I2C under piAROS. The battery code (pisbs.c) will
be part of a future PiSensors release.


Licence
-------

Copyright (c) 2026 rhun. MIT licence: free to use, copy, change and
pass on, also in other programs, as long as the copyright notice stays.

Written with help from Claude (AI). Facts about the pi-top battery
come from the public pi-top documentation and software; no code of
other projects is used.