EP-0256

SBS Module for UPS Gen 6

Description

The SBS (Smart Battery System) Module is an advanced battery management solution designed specifically for the UPS Gen 6 platform. This module implements the industry-standard SBS communication protocol to provide intelligent monitoring and control of lithium battery packs. By integrating precision analog front-end circuitry with a compliant SBS firmware stack, it delivers real-time battery telemetry including voltage, current, state of charge, and runtime estimation. The module supports I2C communication interfaces compatible with both PikaPython embedded environments and native Raspberry Pi I2C buses, making it versatile for various development scenarios. With open-source firmware architecture, users benefit from transparent battery management algorithms while maintaining flexibility for customization. The module ensures safe and efficient battery operation through balanced charging capabilities and configurable I2C addressing, making it an ideal power management companion for UPS Gen 6 battery expansion boards.

Features

• Balanced Charging Protection: Lithium battery charging incorporates cell balancing functionality to prevent battery damage and extend pack longevity
• SBS Protocol Compliance: Device firmware adheres to Smart Battery System (SBS) communication standards for interoperability
• UPS Gen 6 Compatibility: Fully compatible with UPS Gen 6 battery expansion boards for seamless integration
• Flexible I2C Communication: Supports I2C protocol communication compatible with both PikaPython environments and native Raspberry Pi I2C interfaces for reading battery voltage, current, and status parameters
• Open-Source Firmware: SBS firmware is open-source, enabling transparency and customization
• Enhanced Battery Management: Provides safer and more convenient battery management capabilities
• Configurable I2C Address: I2C communication address selectable via jumper configuration
• High-Precision Acquisition: Utilizes high-precision operational amplifiers for voltage and current sensing, delivering accurate readings
• Intelligent Runtime Estimation: Smart algorithms estimate remaining battery runtime, providing battery percentage and charge/discharge state indication

Gallery

TBD.

How to assemble it?

TBD.

How to setup?

Auto Setup

• Download setup shell script from GitHub: [ ]
• Execute the setup.sh shell script.

bash ~/sbs-setup/setup.sh 

• Reboot Raspberry Pi.

Hand-crafting step by step

Raspberry Pi SBS Battery Module Compilation Guide

Overview

This guide explains how to compile the SBS (Smart Battery System) battery driver as an external kernel module on Raspberry Pi 5, create a Device Tree overlay to instantiate the device, and configure automatic loading at boot time — all without recompiling the entire kernel.

Prerequisites

• Raspberry Pi 5 (or compatible model, Raspberry Pi 4B etc.)
• Running Raspberry Pi OS with kernel headers installed
• I2C interface enabled
• SBS-compatible battery connected via I2C (default address: 0x0a)

---

Part A: Compile External Kernel Module (Out-of-Tree)
Step A0: Install Required Kernel Headers
You must install kernel headers that exactly match your running kernel:

sudo apt update 
sudo apt upgrade -y 
sudo apt install -y "linux-headers-$(uname -r)"

Important: The build directory musb be "/lib/modules/$(uname -r)/build 

Verify the kernel build directory:

KDIR=/lib/modules/$(uname -r)/build 
readlink -f "$KDIR"
ls -l "$KDIR"

Step A1: Obtain Kernel Source Code
Clone the Raspberry Pi Linux repository to extract the sbs-battery.c source file:

git clone --depth=1 -b rpi-6.12.y https://github.com/raspberrypi/linux ~/linux

NOTE:This step is only to obtain the sbs-battery.c source file. The actual compilation uses the headers' build tree, so minor version differences between the source tree and your running kernel are generally acceptable. However, API changes may cause compilation failures.

Step A2: Create External Module Directory and Makefile
Create a working directory for the external module:

mkdir -p ~/kmods/sbs
cd ~/kmods/sbs

# Copy the source file from cloned repository
cp ~/linux/drivers/power/supply/sbs-battery.c .

# Create the Makefile
cat > Makefile << 'EOF'
obj-m += sbs-battery.o
EOF

Step A3: Compile Using Kernel Headers
Compile the module using the kernel headers' build directory:

KDIR=/lib/modules/$(uname -r)/build

# Clean previous builds
make -C "$KDIR" M="$PWD" clean

# Compile the module
make -C "$KDIR" M="$PWD" modules

Expected output files:

• sbs-battery.ko — The loadable kernel module
• Module.symvers — Module symbol versions
• modules.order — Module load order

Step A4: Manual Loading Verification
Test the compiled module by manually loading it:

sudo insmod sbs-battery.ko

# Verify module is loaded
lsmod | grep sbs

Part B: Create Device Tree Overlay

Step B0: Identify I2C Controller Device Tree Path
Before creating the overlay, you must identify the correct Device Tree path for your I2C controller. For Raspberry Pi 5, the path is:

/axi/pcie@1000120000/rp1/i2c@74000

To find the DT path for your specific setup:

OF=$(readlink -f /sys/class/i2c-dev/i2c-1/device/of_node)
echo "DT_PATH=${OF#/sys/firmware/devicetree/base}"

NOTE: for other Pi models, you will need to determine the appropriate path individually.

Step B1: Overlay File Requirements

Requirement	Specification
Filename suffix	Must end with -overlay.dts
Source directive	Must include /plugin/;
DTC flag	Must use @ flag during compilation
Output	.dtbo file placed in /boot/firmware/overlays/

Step B2: Create Overlay Content
Create the Device Tree overlay file sbs-battery-overlay.dts:

/dts-v1/;
/plugin/;

/ {
    compatible = "brcm,bcm2712";

    fragment@0 {
        target-path = "/axi/pcie@1000120000/rp1/i2c@74000";
        
        __overlay__ {
            status = "okay";
            #address-cells = <1>;
            #size-cells = <0>;
            
            sbs-battery@a {
                compatible = "sbs,sbs-battery";
                reg = <0x0a>;           /* I2C addrss default is 0x0A */
                status = "okay";
            };
        };
    };
};

Address notation explanation:

• battery@a — Node name (hexadecimal without prefix, following DT convention)
• reg = <0x0a> — Actual I2C device address (0x0a = 11 in decimal)

It is recommended to keep the node name consistent with the reg value for clarity.
Step B3: Compile and Install Overlay
Compile the Device Tree overlay:

dtc -@ -I dts -O dtb -o sbs-battery.dtbo sbs-battery-overlay.dts

Install the compiled overlay to the system overlays directory:

sudo install -D -m 0644 sbs-battery.dtbo /boot/firmware/overlays/

Step B4: Enable the Overlay
Edit the Raspberry Pi configuration file to enable the overlay:

sudo nano /boot/firmware/config.txt

Add the following line in the [all] section (or appropriate section):

[all]
dtoverlay=sbs-battery

Part C: Configure Automatic Module Loading

Step C1: Install Module to Standard Path
Install the compiled module to the standard kernel modules directory and update dependencies:

# Install module to extra directory
sudo install -D -m 0644 ~/kmods/sbs/sbs-battery.ko \
    /lib/modules/$(uname -r)/extra/sbs-battery.ko

# Update module dependencies
sudo depmod -a

Recommendation: If you previously loaded the module manually with insmod, remove it first to ensure clean verification of automatic loading:

sudo rmmod sbs-battery

Step C2: Reboot and Verify
Reboot the system to test automatic loading:

sudo reboot

After reboot, verify the module loaded automatically:

# Check if module is loaded
lsmod | grep sbs

# Check kernel messages for SBS/battery related logs
dmesg | grep -i -E 'sbs|battery|power_supply'

# Check power supply class devices
ls /sys/class/power_supply/

# Verify I2C device detection (should show 1-000a for I2C bus 1, address 0x0a)
ls /sys/bus/i2c/devices | grep '1-000a'

OUTPUT:

upower Command Reference

• upower -e — Enumerate Power Devices
• Purpose: Lists all power device paths recognized by the UPower daemon.

upower -e

Typical Output:

Perfect! SBS battery is detected at I2C address 0x0a (shown as sbs_1_000a). Let me verify the full status and update the scripts for your specific device path:

• Verify Your Battery
• Usage: upower -i <device> — Inspect Device Information

upower -i /org/freedesktop/UPower/devices/battery_sbs_1_000a

Quick Status Scripts

Essential Info Only (Panel/Conky Friendly)

upower -i $(upower -e | grep battery) | grep -E "state|percentage|time to|energy-rate|temperature"

Output:

or you can write a shell script to inspect battery's information:

cat > ~/.local/bin/batt << 'EOF'
#!/bin/bash
DEVICE="/org/freedesktop/UPower/devices/battery_sbs_1_000a"

# Colors
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'

# Get data
RAW=$(upower -i "$DEVICE")
STATE=$(echo "$RAW" | grep "state:" | awk '{print $2}')
PERCENT=$(echo "$RAW" | grep "percentage:" | awk '{print $2}' | tr -d '%')
VOLTAGE=$(echo "$RAW" | grep "voltage:" | awk '{print $2}')
TEMP=$(echo "$RAW" | grep "temperature:" | awk '{print $2 " " $3}')
POWER=$(echo "$RAW" | grep "energy-rate:" | awk '{print $2 " " $3}')
ENERGY=$(echo "$RAW" | grep "energy:" | awk '{print $2 " " $3}')

# State color
case "$STATE" in
    charging) COLOR=$GREEN; ICON="🔌" ;;
    discharging) COLOR=$YELLOW; ICON="🔋" ;;
    fully-charged) COLOR=$GREEN; ICON="⚡" ;;
    *) COLOR=$NC; ICON="❓" ;;
esac

# Output
echo -e "${COLOR}${ICON} 52Pi UPSPack-2S${NC}"
echo "━━━━━━━━━━━━━━━━━━━━━━━"
echo -e "State:       ${COLOR}${STATE}${NC}"
echo "Level:       ${PERCENT}%"
echo "Voltage:     ${VOLTAGE}V"
echo "Power:       ${POWER}"
echo "Energy:      ${ENERGY}"
echo "Temp:        ${TEMP}"
echo ""
echo "Device:      sbs-1-000a (I2C 0x0a)"
EOF

chmod +x ~/.local/bin/batt

Usage:

batt

output:

• Mini Monitor (Auto-Refresh)

# Watch live (updates every 2 seconds)
watch -n 2 'upower -i /org/freedesktop/UPower/devices/battery_sbs_1_000a | grep -E "state|percentage|voltage|temp|energy-rate"'