wfplug-ups

UPS battery widget for Raspberry Pi OS Bookworm's wf-panel-pi.

The widget is intended for the Waveshare UPS Module 3S, also documented on the Waveshare wiki. It reads the module's INA219 monitor over I2C and shows a compact battery icon with percentage text in the panel. Charging is shown with a small bolt inside the battery. Battery fill colors, shell color, bolt color, text color, and text weight are configurable from the normal wf-panel-pi plugin configuration dialog.

Features

• INA219 bus scan on /dev/i2c-1 through /dev/i2c-8
• Battery percentage calibrated from 9.3 V empty to 12.3 V full
• Charging/external power detection from current above -120 mA
• Rounded iPhone-style battery icon plus percentage text
• Configurable colors with visual GTK color pickers
• No separate tray process; this is a native wf-panel-pi widget

Architecture

This repository uses a native wf-panel-pi plugin instead of the older Python UPS monitor path. wf-panel-pi loads libups.so directly, and the plugin reads INA219 data, calculates charge level, detects charging state, and draws the panel UI in one process.

The previous Python approach (INA219.py, upsui.py, upstray.py, desktop launchers, helper probes, and generated tray assets) is intentionally not part of this repository. Keeping the reader and UI inside the panel plugin avoids an extra background process, avoids IPC or file polling, and matches the shape of official panel widgets such as CPU temperature.

Build

Install the development dependencies on Raspberry Pi OS:

sudo apt install build-essential pkg-config libgtkmm-3.0-dev wf-panel-pi-dev

Build the plugin:

make

Install

sudo make install

Add ups to a panel widget list in:

~/.config/wf-panel-pi/wf-panel-pi.ini

Example:

widgets_right=tray cputemp spacing4 ups spacing2 clock

Restart the panel:

kill "$(pgrep -n wf-panel-pi)"

lwrespawn should start it again automatically on Raspberry Pi OS.

Configuration Notes

ups.xml stores color options as type="string" on purpose. The wf-panel-pi configuration dialog implements CONF_TYPE_COLOUR by reading and writing string values with GTK color buttons. Using XML type="color" for these options can make the plugin display while crashing the panel configuration dialog.

Default colors are six-digit #RRGGBB values because GTK color parsing is used for drawing and configuration.

Files

• wfplug-ups.cpp: plugin source
• ups.xml: wf-panel-pi metadata and configurable options
• Makefile: build and install rules

Hardware

Required UPS module:

• Waveshare UPS Module 3S
• Product page wording: "Uninterruptible Power Supply Module, Supports charging And Power output at the same time, 3S & 5V 5A Output"
• 3S means 3x 18650 Li batteries in series; Waveshare lists the battery-side output range as about 9V~12.6V
• The plugin scans INA219 I2C monitor addresses 0x41 and 0x40

Other INA219-based 3S UPS boards may work, but this repository is calibrated and documented for Waveshare UPS Module 3S.