Batteries and the different Voltage Levels
Caveat: The voltage levels and capacity estimates are rough and should be used as a guideline, not as an absolute truth.
Rechargable Li-Ion battery are ubiquitous and are used for nearly every portable device. And they are used in the Geekworm UPS as well.
If we look at a typical discharge chart for Li-Ion batteries at low currents it looks like the following drawing (lovingly hand-drawn by yours truly). Principally we do not have to worry as long as the battery is still in the blue or green areas i.e., above 3.2-3.4V (depending on the battery). These areas together hold about 80% of the charge, so to shut down after that would be totally ok. The problem we face is that these discharge graphs, while looking very nice, show the battery under a constant and comparatively low load.
Our use case is totally different. The RPi needs up to 2A at 5V (if we are careful), which means more than 3A at 3V. This leads to a flattened discharge graph. What does this mean for us? With a typical battery (2500mAh) we get to 3,4V at around 50% capacity and to 3,2V at around 20-30% charge with the RPi as a load.
Using the 3,4V to signal the RPi to turn itself off means we have used up around 1250mAh over all and thus more than 30 minutes on battery before shutting down gracefully. This, I think, is absolutely acceptable and gives a safety margin in the treatment of the battery that allows us to get more charge/discharge cycles from our battery.
And 3,2V then seems like a safe margin to the 3,0V where the battery protection circuit will turn off the power.
On the other hand, if we are in the red area already, we have to shut down everything as fast as possible (since obviously there is no protection circuit in the battery itself) to limit the possible damage to the battery as much as possible. The yellow area is the one where we should signal the Raspberry to shut down as soon as possible without actually pulling the plug on it.
A Li-Ion battery is charged with a constant current until it reaches 4.1V, then a constant voltage is kept. A voltage of 3,9V is reached once we have around 20% of the capacity, and 4,0V at around 40%.
We want to restart our RPi as soon as possible, but only when the battery already holds enough of a charge to shut down orderly in case the power fails again. So, 3,9V seems like a sensible value to give the RPi a push and wake it (i.e, reset it).
The ATTiny Daemon uses the following thresholds to react to different situations (the values can be set in the configuration file):
- Normal operation - If the voltage is above warn voltage the ATTiny operates normally, sleeping for 1 second before taking the next measurement of temperature and voltages.
- warn voltage - at this battery level the ATTiny Daemon sends a signal to the RPi, asking it to shut down gracefully (default value 3400). The ATTiny sleeps 2 seconds before waking up and taking the next measurements.
- shutdown voltage - at this battery level the ATTiny Daemon shuts down the Geekworm UPS fully, turning off the power for the RPi (default value 3200). The ATTiny sleeps 8 seconds before waking up and taking the next measurements.
- restart voltage - at this voltage the RPi is restarted (default value 3900). After the RPi is restarted normal operation commences (see above).
In all cases communication via I2C is fully supported.
If you want to use other threshold values you can without problems change them in the configuration file. This allows for instance to maximize the run time of the RPi at the expense of battery life.
By the way, this discussion is not limited to Li-Ion technology, we can define the same thresholds for other technologies like LiFePo4 as well. This means that without changing the firmware or daemon on the RPi we are prepared for these other technologies already.