EP-0136

From 52Pi Wiki
Jump to navigation Jump to search

UPS Plus

UPS V2 1.jpg

Descriptions

UPS Plus is a new generation of UPS power management module which supports OTA firmware upgrade and supports RTC onboard.
And there are two INA219 chip onboard to detect batteries voltage and the voltage output from UPS Plus to Raspberry Pi.
DO NOT PLUG Power supply to Raspberry Pi in USB-C port during Using UPS, it may damage UPS!!!!

Compatibility

Raspberry Model Compatibility
Raspberry Pi A YES
Raspberry Pi A+ YES
Raspberry Pi B YES
Raspberry Pi B+ YES
Raspberry Pi 2B YES
Raspberry Pi 3B YES
Raspberry Pi 3B+ YES
Raspberry Pi 4B YES
Raspberry Pi Zero NO
Raspberry Pi Zero W NO

Features

  • Easy to install
  • Enhanced power management
  • Remote OTA firmware upgrade
  • Programmable BACK-TO-AC auto power up
  • Programmable sample period
  • I2C communication
  • Standalone RTC
  • Support stacked battery design

Specifications

  • Current/voltage monitoring of Raspberry Pi power supply port.
  • Battery terminal current/voltage monitoring, supports two-way monitoring of charge and discharge.
  • Independent RTC function.
  • OTA function (supports forced upgrade mode and active upgrade mode).
  • Power estimation
Note: At least one full charge and discharge cycle must be completed!)
  • Adjustable sampling period.
  • Support FCP, AFC, SFCP fast charge protocol.
  • Support BC1.2 charging protocol.
  • Battery temperature monitoring
Note: the forced temperature protection cannot be turned off, threshold: 65 degrees!
  • Programmable Power Voltage Detector(PVD) function, Default value: 3.6V
  • Incoming call self-start function.
  • Power down memory function.
  • Programmable shutdown / forced restart.
  • Running time statistics
  • Electrostatic protection.
  • Linear compensation range discharge capacity: 5V 4.5A.
  • Non-linear compensation range discharge capacity: 5V 8A.
  • Charging capacity 4.5V 5A/5V 2.5A/9V 2A/12V 1.5A.
  • Stacked battery design
NOTE: Stacked power board need to be special accessories.Can not support None official accessories.
  • Use I2C communication without occupying additional ports.
  • Support 4.2V 4.35V 4.4V 4.5V 18650 lithium battery
Note: Different types of batteries cannot be mixed!
  • After-sales data telemetry.

Register Mapping

USB Plus V5.0 Register Mapping Chart

  • 0x17 - Operation Mode
 RO - Read Only, RW - Read & Write 
Address Function Range Unit R/W Attr
0x01 - 0x02 Voltage of UPS's MCU 2400 - 3600 mV RO
0x03 - 0x04 Voltage of Pogopin's Bottom 0 - 5500 mV RO
0x05 - 0x06 Voltage of Batteries' Terminal 0 - 4500 mV RO
0x07 - 0x08 Voltage of USB-C Charging Port 0 - 13500 mV RO
0x09 - 0x0A Voltage of MicroUSB Charging Port 0 - 13500 mV RO
0x0B - 0x0C Batteries Temperature -20 - 65 RO
0x0D - 0x0E Full Voltage 0 - 4500 mV RW
0x0F - 0x10 Empty Voltage 0 - 4500 mV RW
0x11 - 0x12 Protection Voltage 0 - 4500 mV RW
0x13 - 0x14 Battery Remaining 0 - 100 % RO
0x15 - 0x16 Sample Period 1 - 1440 Min RW
0x17 Power Status/Operation Mode 0/1 Bool RO
0x18 Shutdown Countdown 0(False)/10 - 255 Bool/Sec RW
0x19 Back-To-AC Auto Power up 0/1 Bool RW
0x1A Restart Countdown 0(False)/10- 255 Bool/Sec RW
0x1B Reset to Factory Defaults 0/1 Bool RW
0x1C - 0x1F Cumulative Running Time 0 - 2147483647 Sec RO
0x20 - 0x23 Accumulated Charging Time 0 - 2147483647 Sec RO
0x24 - 0x27 Running Time 0 - 2147483647 Sec RO
0x28 - 0x29 Version 1 Fixed RO
0x2A (FW.V5+) Battery Parameters self-programmed by user 0/1 Bool RW
0x2B - 0xEF [Reserved] NA NA RW
0xF0 - 0xFB Serial Number Device UID Fixed RO
0xFC - 0xFF Factory Testing NA NA RW
  • 0x18 - OTA Firmware Upgrade Mode
Address Function
0x01 - 0x10 Encrypted buffer
0x11 - 0xEF [Reserved]
0xF0 - 0xFB Serial Number
0xFC - 0xFF Factory Test

Gallery

  • Product Outlook
UPS V2 1.jpg
UPS V2 2.jpg
UPS V2 3.jpg
  • Application scenario
UPS V2 13.jpg


PCB Drawing

Function Area Display

  • Function Details
UPS V2 10.jpg
UPS V2 11.jpg
UPS V2 12.jpg

LED light status definition

  • Discharge Status
Power C(%) LED1 LED2 LED3 LED4
C >= 75% ON ON ON ON
50% <= C <75% ON ON ON OFF
25% <= C <50% ON ON OFF OFF
0% <= C < 25% ON OFF OFF OFF
Wrong Batteries Parameters 1.5Hz Blinking OFF OFF OFF


  • Charging Status
Power C(%) LED1 LED2 LED3 LED4
100% ON ON ON ON
75% <= C ON ON ON 1.5Hz Blink
50% <= C <75% ON ON 1.5Hz Blink OFF
25% <= C < 50% ON 1.5Hz Blink OFF OFF
C < 25% 1.5Hz Blinking OFF OFF OFF

How To Assemble

  • How to Assemble
UPS V2 4-2.jpg


How To Use

General Settings

  • Download the latest Raspbian OS image from: [ https://www.raspberrypi.org/software/operating-systems/ ]
  • Unzip it and flash it to MicroSD card(TF card) with Etcher imaging tool. [ https://www.balena.io/etcher/ ]
  • Follow the installation method to assemble the Raspberry Pi and UPS Plus.
  • After booting up and make sure Raspberry Pi can access internet.
  • Enable I2C function by using "raspi-config" tool, Navigate to "interface options" and select "I2C" and enable it follow the instructions.
 NOTE: It is very important to enable I2C function on Raspberry Pi, If miss this step, Raspberry Pi will not detect UPSPLUS module.
 sudo raspi-config
  • Install smbus2 library.
pip install smbus2
  • Download repository from GitHub and entering the folder that contains demo code.
cd ~ 
git clone https://github.com/geeekpi/upsplus.git
cd upsplus/

Automatic Shutdown Protection

  • If you want to use one script to install upsplus's demo code, just follow the steps below.
  • Open a terminal by press "Ctrl+ALT+T" or just click terminal icon on the task bar.
curl -Lso- https://git.io/JLygb | bash 

or

curl -Lso- https://raw.githubusercontent.com/geeekpi/upsplus/main/install.sh | bash
  • When encountering low battery, it will automatically shut down and turn off the UPS and it will restart when AC power comes.

How To Update UPS Firmware via OTA

  • Enter the OTA firmware upgrade mode:

Method 1

NOTE: Do not power off or disconnect the network during the upgrade process. If the upgrade fails, the UPS Pro will not work normally.

  • Power off the Raspberry Pi.
  • Cut off the external charging power (MicroUSB and USB-C)
  • Take out all the batteries.
  • Press and hold the UPS Pro switch key and insert the battery into the battery compartment.

At this time, the device will be forced to enter OTA mode.

The function of the switch button will no longer be available at this time.

The Raspberry Pi will be running and please execute the following python script in the system terminal to complete the upgrade.

  • Download python scripts from github:
cd ~
git clone https://github.com/geeekpi/upsplus.git
cd ~/upsplus
python3 OTA_firmware_upgrade.py

The first time it runs, it may prompt that the device is not registered.If it is a legal device, just wait a few seconds and try again.

  • UPS Pro Will be turned off after upgrading, Please unplug the power supply, remove the batteries from UPS Pro.
  • Insert the batteries back to UPS Pro and then connect power supply and turn it on by press power switch.

Method 2

  • Open a terminal and typing:
i2cset -y 1 0x17 50 127 b
  • Shutdown Raspberry Pi and remove all batteries and power supply.
  • Insert batteries back into the battery slot.
  • Execute OTA_firmware_upgrade.py python script in a terminal.
  • UPS Pro Will be turned off after upgrading, Please unplug the power supply, remove the batteries from UPS Pro.
  • Insert the batteries back to UPS Pro and then connect power supply and turn it on by press power switch.

How To Collect Data

  • Data Collection

Data collection will only collect information on abnormal voltage changes and battery charging and discharging status during equipment operation through UPS in order to provide better after-sales service, and will not collect your private information.
Please rest assured that every UPS we sell will Have a unique serial number so that we can provide battery quality analysis and feedback.
It submits your UPS Pro operating status information to the server provided by us through a python script.

  • Download Repository and execute:
cd ~
curl -Lso- https://git.io/JLygb | bash

When encountering low battery, it will automatically shut down and turn off the UPS and it will restart when AC power comes.

How To Setup RTC

Using Overlays

  • Overlays are loaded using the "dtoverlay" config.txt setting.

As an example,consider I2C Real Time Clock drivers. In the pre-DT world these would be loaded by writing a magic string comprising a device identifier and an I2C address to a special file in /sys/class/i2c-adapter, having first loaded the driver for the I2C interface and the RTC device - something like this: PS: sudo su means use root user to operate the system file, otherwise you may encount an error: "Permission denied"

    sudo modprobe i2c-bcm2835
    sudo modprobe rtc-ds1307
    sudo su 
    echo ds1307 0x68 > /sys/class/i2c-adapter/i2c-1/new_device

With DT enabled, this becomes a line in config.txt:
Edit /boot/config.txt file via vim.tiny tool or nano in a terminal: sudo vim.tiny /boot/config.txt
And then add this parameter:

    dtoverlay=i2c-rtc,ds1307

This causes the file /boot/overlays/i2c-rtc.dtbo to be loaded and a "node" describing the DS1307 I2C device to be added to the Device Tree for the Pi. By default it uses address 0x68, but this can be modified with an additional DT parameter:

    dtoverlay=i2c-rtc,ds1307,addr=0x68

Parameters usually have default values, although certain parameters are mandatory. See the list of overlays below for a description of the parameters and their defaults.

For Raspberry Pi 4B

Here we assume that you have already burned the Raspbian Image into TF card and connect to your PC and logged in. Open a terminal and modify /boot/config.txt file using what you favorate editor such as vim.tiny or nano, add parameters as following picture:

DS1307-4B(1).png


You can read /boot/overlay/README and find this info to add support for ds1307 I2C Real Time Clock device.

DS1307-4B(2).png


please ensure that /boot/config.txt file include two paramaters:

dtoverlay=i2c-rtc,ds1307 
dtparam=i2c_arm=on

After that, please make sure you have disabled the "fake hwclock" which interferes with the 'real' hwclock

sudo apt-get -y remove fake-hwclock
sudo update-rc.d -f fake-hwclock remove

Now with the fake-hw clock off, you can start the original 'hardware clock' script.
Edit the script file /lib/udev/hwclock-set with nano or vim editor and comment out these three lines:

if [ -e /run/systemd/system ] ; then
 exit 0
fi

Finally result like this:

DS1307-4B(6).png


save and reboot your RPi.


How to test RTC

  • Open terminal and typing:
sudo hwclock -w 
sudo hwclock 
  • Result will be like:
pi@upstest:~ $ sudo hwclock -w
pi@upstest:~ $ sudo hwclock
2021-05-12 11:41:23.601270+08:00

For Raspberry Pi 3B

Here we assume that you have already burned the Raspbian Image into TF card and connect to your PC and logged in. Open a terminal and modify /boot/config.txt file using what you favorate editor such as vim.tiny or nano, add parameters as following picture:

Ds13076.png


You can read /boot/overlay/README and find this info to add support for ds1307 I2C Real Time Clock device.

Name:   i2c-rtc
Info:   Adds support for a number of I2C Real Time Clock devices
Load:   dtoverlay=i2c-rtc,<param>=<val>
Params: ds1307                  Select the DS1307 device

please ensure that /boot/config.txt file include those three paramaters:

device_tree=bcm2710-rpi-3-b.dtb
dtoverlay=i2c-rtc,ds1307
dtparam=i2c_arm=on

After that, please make sure you have disabled the "fake hwclock" which interferes with the 'real' hwclock

sudo apt-get -y remove fake-hwclock
sudo update-rc.d -f fake-hwclock remove

Now with the fake-hw clock off, you can start the original 'hardware clock' script.
Edit the script file /lib/udev/hwclock-set with nano or vim editor and comment out these three lines:

if [ -e /run/systemd/system ] ; then
 exit 0
fi

Finally result like this:

Raspberry pi hwclock-set.png


save and reboot your RPi.

How To Adjust The Sampling Period

  • If you want to change the sampling interval, you can change it with the following demo code in python:

NOTE: Change the number of `SAMPLE_TIME` will adjust the sampling period: range from 2 to 60, unit minute. If the quality of the charger is not good, you need to increase the period, for example: adjust to 3~5, if the quality of the battery is not good, you need to decrease the sampling period, for example: 1~2

  • Demo code:
import smbus

DEVICE_BUS = 1
DEVICE_ADDR = 0x17
SAMPLE_TIME = 2  

bus = smbus.SMBus(DEVICE_BUS)

aReceiveBuf = []
aReceiveBuf.append(0x00)  

bus.write_byte_data(DEVICE_ADDR, 21,SAMPLE_TIME & 0xFF)
bus.write_byte_data(DEVICE_ADDR, 22,(SAMPLE_TIME >> 8)& 0xFF)

print("Setting Sampling Period to: %d Min" % SAMPLE_TIME)
  • Save it to a file and execute it:
python3 ups_change_sample_period.py

How to detect if the battery is dead

Ups location.jpg


  • Execute the `upsPlus.py` script 2-3times through the following commands to determine whether the battery is continuously discharging, and if the charge is less than the discharge, the battery will soon be lower than the set shutdown threshold and shut down.

At this time, you need to replace the battery, or change the sampling period, or replace the high-quality fast charger plug

 python3 /home/pi/bin/upsPlus.py 
  • For example:
Ups batteries status.jpg


The battery shown in the figure:Battery Current (discharge) Rate: 1553.902 mA, But the last information was: Currently charging via Micro USB Port. There is a charging port inserted, but the battery discharge is displayed, which means the battery is bad.

How to Setup back-to-ac function manually

  • Login to Raspberry Pi and open a terminal, Typing following command:
 i2cset -y 1 0x17 25 1
  • Check if the command is enabled the function by read the register value:
 i2cget -y 1 0x17 25 

How to Setup shuting down countdown function manually

  • Login to Raspberry Pi and open a terminal, Typing following command:
 i2cset -y 1 0x17 24 20

PS: 20 means countdown number is 20 seconds, you can change to another integer number.

  • Check if the command is enabled the function by read the register value:
 i2cget -y 1 0x17 25 

How to self-diagnose UPS PLUS

Ups diagnosistool.jpg


  • Filling the blank with your Deivce UIDs which can be getting from /home/pi/bin/upsPlus_iot.py script, open a terminal and typing:
 python3 /home/pi/bin/upsPlus_iot.py 
Ups uids.jpg


  • Copy UID0, UID1, UID2 to browser and press "Diagnosis" button on the page:
Ups dignosis.jpg


  • Then you will get the test results and suggestions on the page.
Dignosis result.png


Pink color means it is critical message and Blue color means suggestion.

Parameter freezing issue

According to our tracking test, about 0.8% of users after a period of time, read the UPS parameters found that the value no longer changes, the cause of this is complex, and the number of users is small, we are working to solve this problem, if you encounter this problem, please try to completely reinstall the battery, power supply and Raspberry Pi and observe again, usually the problem is solved, if there are still problems, please contact us.

Battery Logger

Ups logger.jpg


Package Includes

  • 1 x UPS Plus For Raspberry Pi
  • 4 x M2.5 copper pillar
  • 4 x M2.5 screws
  • 4 x M2.5 long copper stick
  • 4 x M2.5 nuts
  • 1 x Acrylic shield
  • 1 x Instructions
UPS V2 9.jpg


Tutorial Video

  • Youtube link:

[ https://youtu.be/jQljQJ41I5A ]

  • QRCODE:
Upsplus tutorial1.png


3D print File

FAQ

  • Q: Why is my UPS not used, just put it for more than ten days, the battery is drained?
    • A: That's because by default, the battery itself will discharge slowly. If the battery is inserted into the UPS, the UPS cannot be completely shut down, so it will continue to discharge. When the UPS is not used for a long time, do not put the battery in the battery slot.
  • Q: How to set battery capacity, Full voltage, low voltage?
    • A: It only affects the charging method and the calculation of the charge level, the protection threshold, and does not change the actual battery parameters. more info please refer to: [ https://github.com/geeekpi/upsplus/issues/80 ]
  • Q: Why it will turn on my Raspberry Pi once I plug the power supply into the charging port?
    • A: When the BACK-TO-AC function of the Raspberry Pi is turned on, the Raspberry Pi will be automatically activated when the external power supply is connected to the charging port. This setting is for some applications that use the Raspberry Pi as a server scenario, because the external power supply After the power is supplied, the UPS detects the charging status and executes the automatic startup operation, so that some scenes where the Raspberry Pi is placed in the computer room can easily start the Raspberry Pi, no need to press the button to start the UPS, if you want Using BACK-TO-AC, you can also turn off this function. After turning off this function, you need to press the power button again every time you start it.
  • Q: Why does my UPS shut down suddently and I can not turn it on?
    • A: Please use power supply with QC protocol and try to change batteries with better quality. we recommend you to connect QC power supply while your UPS need to provide service at 7x24.
  • Q: Why does the battery light go off sometime and lights up in a while?
    • A: This is because the power chip performs battery re-sampling, and the purpose is that the data of inferior batteries is inaccurate during the sampling process.
  • Q: Why is the power cut off every once in a while?
    • A: Please check the battery charging current, the data discharge direction or the charging direction. If the load is too large, the charging may not be enough, which will cause this problem.
  • Q: What kind of wall charger should I use?
    • A: If the load is normal, it is recommended to use an ordinary 5V@2A charging head. If you need to carry a slightly higher load, it is recommended to use a fast charging source. We support FCP, AFC, SFCP protocols Fast charging source.
  • Q: Can I directly input 9V and 12V to the USB port?
    • A: No, if you must do this, you must remove the DP, DM and other related detection pins, and ensure that the power supply is stable.
  • Q: I heard howling, why is this?
    • A: Because of the no-load protection mechanism, the howling will disappear after the load is installed.
  • Q: using firmware v. 4, when AC power comes back on during the shutdown countdown, I realized that the 5V supply for the raspberry pi is not switched off at the end of the countdown. so, after shutdown of the operating system, the raspberry pi will never restart automatically.

IMHO the following would be better: once a shutdown countdown starts, and we have the Back-To-AC Auto Power UP flag set, then: the shutdown sequence should proceed to its end, switch off the 5V-power for a certain time (a couple of seconds maybe), regardless of AC Power. switch the 5V back on when AC power is restored. otherwise, I am very happy with the product. one more thing: would be nice to have some sort of alert for new firmware releases and release notes for these.

Keywords

  • UPS Plus, GeeekPi UPS V5, UPS for Raspberry Pi