UPS HAT (E) Raspberry Pi UPS module User Manual

UPS HAT (E) Raspberry Pi UPS module User Manual
BLUE JAY TWSK-Y Oil-Immersed Transformer Temperature Controller User Manual

The UPS HAT (E) is an uninterruptible power supply (UPS) module for the Raspberry Pi. It features an onboard switching battery charger with path management, a boost converter, and voltage/current monitoring ICs. It supports simultaneous charging and discharging, provides a stable 5 V output, and allows monitoring of battery voltage, current, power, and other parameters via the I2C interface. It also supports battery level icon display.

SKU Product
27966 UPS HAT (E) (EN)

Features

  • Spring-loaded pogo pin interface design, compatible with Raspberry Pi series boards
  • Onboard Type-C bidirectional fast charging port, supporting PD 3.0 and various other charging input/output protocols, with up to 40 W power
  • Onboard dedicated battery fuel gauge IC, supporting reading of battery voltage, current, power, remaining capacity, and other parameters
  • 12C communication interface for reading Type-C input/output and battery status information, enabling real-time monitoring of module operating status
  • Four 21700 lithium batteries (NOT included) in series
  • Onboard high-power buck converter for stable 5 V output
  • Onboard MCU for management, supporting power-on detection and auto-start functionality
  • Supports battery level icon display for easy status monitoring

Specifications

Parameter Value
Output Voltage 5V
Control Interface I2C
Charging Power Bidirectional input/output fast charging protocol, up to 40 W
Output Power 5V 6A
Battery Type 21700 rechargeable battery, 3.7V, flat top
Capacity 5000mAh (nominal)
Product Dimensions 56mm × 88mm
Through-hole Diameter 3.0mm

Dimensions

Dimensions

Interface Description

Hardware Description
Hardware Description

  • The USB Type-C port is a bidirectional fast charging port, supporting both charging and output, with a maximum power of 40 W.
  • The USB Type-A port is a 5 V output port.
  • The LED is a power indicator, which lights up when a charging power source is detected.
  • OFF/ON is the power switch silkscreen marking.

CAUTION

  1. Do not reverse-connect the battery; reverse connection may damage the battery protection IC
  2. When installing batteries, follow the order V1-V2-V3-V4. If not installed in order, the reverse-connection warning LED may light up. The Vx markings and battery polarity indications are printed on the PCB next to the battery holders.
  3. After removing and reinstalling batteries, connect a charger for a few seconds to activate output
  4. After replacing batteries, complete several full charge-discharge cycles to allow the chip to automatically calibrate battery parameters for more accurate capacity readings.
  5. The actual output current can reach up to 10 A; however, due to thermal constraints, it is recommended to keep the current under 6 A under normal use. For higher currents, active cooling should be added.
  6. Battery capacity may be affected by battery model and temperature variations. For determining whether power is available, voltage readings should be considered the reference.

Lithium Battery Usage Precautions

WARNING

  • Lithium polymer and lithium-ion batteries are highly unstable. Improper charging or use may result in fire, personal injury, and property damage.
  • When charging or discharging the battery pack, never reverse the polarity. Do not use inferior or non-standard chargers or charging boards for lithium batteries.
  • Do not mix old and new batteries, and avoid using batteries from other brands.
  • if purchasing additional lithium battery products, ensure that the battery parameters are compatible with the lithium battery expansion board. It is recommended to choose reputable battery manufacturers and perform aging tests to ensure stable and safe operation.
  • Lithium batteries have a limited cycle life. Replace the battery with a new one when it reaches its service life or after two years of use, whichever comes first.
  • Store battery products properly, away from flammable and explosive materials and out of reach of children, to avoid safety accidents caused by improper storage.

Working with Raspberry Pi

This section covers how to use the UPS HAT (E) on a Raspberry Pi.

Enable I2C Interface

  • Open a terminal on the Raspberry Pi and enter the following command to open the configuration interface: sudo raspi-config
  • Select Interfacing Options -> I2C -> Yes to enable the I2C kernel driver.
    Enable I2C Interface
  • Then reboot the Raspberry Pi:

Battery Level Detection

When demonstrating this example on the Raspberry Pi, mount the module to the bottom of the Raspberry Pi and use it with pogo pins.
Run the following commands to execute the program:

After the program runs, it will output values such as Type-C mode, voltage, current, power, battery voltage, battery current, battery power, and remaining battery percentage.
Battery Level Detection

NOTE

  • A negative VBUS current indicates Type-C output current; a positive value indicates input charging current.
  • A negative battery current indicates battery discharge current (considered as the load current of the Raspberry Pi); a positive battery current indicates battery charging current.
  • When the system load is high and the battery voltage is low, insufficient battery current may cause the system to repeatedly reboot, this is undesirable. In practice, you can avoid this by checking the battery voltage and automatically shutting down when it is too low.
  • The example program already includes a battery voltage check. If the battery voltage is too low and no external power is connected, the program will issue a shutdown command within 60 seconds to power off the system.

The program will display the following message when the battery voltage is too low, indicating that charging is needed; otherwise, the system will shut down automatically.
Voltage Low, please charge in time, otherwise it will shut down in 58 s

Battery Icon Display

The example provides a desktop Ul program to display the battery icon. It is recommended to use this on Raspberry Pi OS with a desktop environment.

Open a terminal and run:

  • cd ~/UPS_HAT_E
    DISPLAY:0.0′ python3 battery Tray.py

After running the program, a battery icon should appear in the upper-right corner of the desktop. If it does not show up, check the error messages, verify the 12C interface, and ensure the required libraries are installed.
Battery Icon Display

To have the Ul display and battery level detection run automatically at boot, execute the following commands:

cd ~/UPS_HAT_E
sudo chmod +x main.sh # Grant execute permission to the script
./main.sh #Do NOT use sudo
sudo reboot

After rebooting, the battery icon in the upper-right corner indicates the setup is complete. Hover the mouse over the icon to view battery level and voltage. When the battery level drops below 5%, a low-battery warning will appear, and the system will shut down after 60 seconds; the warning will disappear once an external power source is connected.
Battery Icon Display

If the battery icon does not appear, run batteryTray.py separately and check the error output.

Raspberry Pi 5 Current Limit Removal

When the Raspberry Pi 5 boots, it checks the Type-C port for PD (Power Delivery) protocol. If the official power supply is not detected, the system may show a warning and limit the USB Type-A output current to 3 A.
Current Limit Removal

Method 1: Remove USB Type-A Current Limit

This method only removes the USB Type-A current limit, but does not suppress the boot-time warning. Run the following command to edit config.txt: sudo nano /boot/firmware/config.txt

Add the following setting to remove the 3 A limit on USB Type-A and allow up to 5 A: usb_max_current_enable=1

Method 2: Remove Current Limit and Suppress Boot Warning

Run the following command to edit the EEPROM configuration: sudo rpieeprom-config-edit

Add the following setting to remove the 3 A USB Type-A current limit and suppress the boot warning. Save the changes and reboot the system: PSU_MAX_CURRENT=5000
Suppress Boot Warning

Power-on Auto-Start Principle

When the voltage is too low, you can use the program to let the Raspberry Pi save data before shutting down, preventing data loss from sudden power-off. The auto-start-on-power function is controlled by BITO of register 0x40, with a default value of 1. If you need the system to wait for power to return after a low-voltage shutdown, write 0x55 to register 0x01 to trigger a one-time shutdown sequence. Note that this command is not intended to enable auto-start-on-power.

Before running the following commands, install i2c-tools: sudo apt-get install i2c-tools
Open a terminal and run the following command to detect the 12C address: sudo 12cdetect -y 1
Power-on Auto-Start Principle

0x2D is the I2C address of the MCU. Run the following commands to read the register values; the values of registers 0x00 and 0x01 are exła and exøb respectively. For register definitions, refer to the Register Manual.
sudo 12cget y 1 0x2d 0x00
sudo 12cget y 1 0x2d 0x01
Decoded Data Structure

Writing 0x55 to register 0x01 triggers a one-time shutdown sequence: the MCU will cut power to the Raspberry Pi after about 30 seconds, and then start detecting charging after about 60 seconds. When power is detected, the module will re-apply power to the Raspberry Pi and boot it. This write does not change the BITO configuration of ex40.

WARNING
Before executing the next command, save all data on the Raspberry Pi. After writing 0x55, the module will cut power in about 30 seconds. It is recommended to perform a safe shutdown immediately after writing to avoid data loss from sudden power-off. Do not use this command to enable auto-start-on-power.

Run the following command to trigger the one-time shutdown sequence: sudo 12cset y 1 0x2d 0x01 0x55

NOTE:
BITO of 8×40 is 1 by default, indicating that auto-start-on-power is enabled; ex01-0x55 is only used to trigger shutdown and wait for power to return.

Register Manual

The UPS HAT (E) primarily uses I2C communication to read module information, making it simple and convenient to use. The module slave address is: 0x2D.

Register Table

ID Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x00 R 0x0a 0000 1010

Power-On Trigger Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT3 BIT1 BIT0
0x01 R/W 0x0b 0000 1011

WARNING
0x81 is a one-time shutdown trigger register, not the auto-start-on-power configuration register. After writing @x55 to exe1, the module initiates a delayed shutdown sequence it cuts power to the Raspberry Pi after about 30 seconds, and then begins detecting charging after about 60 seconds. When power is detected, the module re-applies power to the Raspberry Pi and boots it. Auto-start-on-power is controlled by BITO of ex48, with a default value of 1. Before performing the write, you must save data and prepare for a safe shutdown.

Charging Status Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x02 R 1:
Charging
0: Not
charging
1: Fast
charge
0: Not
fast
charge
1: VBUS
powered
0: VBUS
not
powered
000: Standby, 001: Trickle charge, 010: Constant current
charge, 011: Constant
voltage charge, 100: Charging waiting,
101: Full charge, 110: Charge timeout

Communication Status Register

Register

R/W Default BIT7 BIT6

BIT5

BIT4

BIT3

BIT2

BIT1

BI

0x03 R Fixed: 000000 1: BQ4050
communication
OK; 0: BQ4050
communication
error
1: IP236commu
OK; 0: I comma error

Type-C VBUS Voltage Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x10 R Low 8 bits of VBUS voltage data (mV)
0x11 R High 8 bits of VBUS voltage data (mV)

Type-C VBUS Current Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x12 R Low 8 bits of VBUS current data (mA)
0x13 R High 8 bits of VBUS current data (mA)

Type-C VBUS Power Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x14 R Low 8 bits of VBUS power data (mW)
0x15 R High 8 bits of VBUS power data (mW)

Battery Voltage Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x20 R Low 8 bits of total battery voltage data (mV)
0x21 R High 8 bits of total battery voltage data (mV)

Battery Current Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x22 R Low 8 bits of battery current data (mA)
0x23 R High 8 bits of battery current data (mA), signed 16-bit; positive indicates
charge current, negative indicates discharge current

Battery Remaining Percentage Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x24 R Low 8 bits of battery remaining percentage data (%)
0x25 R High 8 bits of battery remaining percentage data (%)

Battery Remaining Capacity Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x28 R Low 8 bits of battery remaining discharge time data (min)
0x29 R High 8 bits of battery remaining discharge time data (min)

Battery Remaining Charge Time Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x2a R Low 8 bits of battery remaining charge time data (min)
0x2b R High 8 bits of battery remaining charge time data (min)

Battery 1, 2, 3, 4, Voltage Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x30 R Low 8 bits of battery 1 voltage data (mV)
0x31 R High 8 bits of battery 1 voltage data (mV)

Control Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x40 R/W 0x01 Reserved 1: Watchdog
enable; 0:
Watchdog
disable
(default)
1: Auto start on
power
(default);
0: Auto start on
power
disable

Custom UPS I2C Address

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x41 R/W 0x2d I2C address range: 0x08–0x77, default: 0x2

Watchdog Timeout Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x42 R/W 0xFF Range: 0–255, unit: s, default: 0xFF

Watchdog Delay Start Register

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x43 R/W 0xFF Range: 0–255, unit: s, default: 0xFF

Software Version

Register R/W Default BIT7 BIT6 BIT5 BIT4 BIT3 BIT2 BIT1 BIT0
0x50 R Software version; shifting the decimal point left by one digit gives the
software version, e.g. 0x14 = 20 = V2.0

Resources

  1. Hardware Resources
  2. Example
    • Example
  3. Documents
  4. Community Showcase
    INFO
    Check out these amazing projects created by the community! Please note these are independently maintained by their creators.

Documents / Resources

PDF thumbnailUPS HAT (E) Raspberry Pi UPS module
User Manual · UPS module, 27966, UPS HAT E, Raspberry Pi UPS

References

Ask a Question

Use this section to ask about setup, compatibility, troubleshooting, or anything missing from this manual.

Ask a Question

Ask about setup, compatibility, troubleshooting, or anything missing from this manual. Name and email are optional.