EP-0256

From 52Pi Wiki
Jump to navigation Jump to search

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


mkdir sbs-project 
cd sbs-project/
wget https://raw.githubusercontent.com/raspberrypi/linux/refs/heads/rpi-6.12.y/drivers/power/supply/sbs-battery.c
Retrieved from "https://wiki.52pi.com/index.php?title=EP-0256&oldid=16258"