How Raspbian Detects Under Voltage

Question

How does the Pi know it being underpowered and to show the lighting bolt?

As most of us know, if you use a bad power supply you get the lightning bolt telling you are underpowered.

I noticed that when I run my Pi on battery, the last 15 minutes or so before the Pi starts to reboot, the lightning bolt starts appearing, and eventually stays there until the reboots, which makes sense because my battery voltage is dropping as it is drained.

This got me thinking I could use this to make a program that turns the Pi off when it detects constant under-voltage. I know before this happened would be even better but I am not concerned about that.

Is there a command for voltage like sudo vcgencmd measure_temp for temperature to know what the voltage is? If not how does the Pi know when it is being underpowered?

EDIT: This is not a duplicate because the other question suggests you need external hardware. I am pointing out this is not strictly necessary.

EDIT 2: fixed typo in quoted command

Answer 1

Some Pi models have an onboard chip which detects a low voltage. This is used to drive the power LED on some Pi models.

Models A+, B+, Pi2B

The red power LED is connected to GPIO 35. You can monitor the GPIO to check for an under voltage condition (less than 4.65V).

Monitoring

To monitor the GPIO you would need to read its value. If the normal (good power state) value is high (1) then undervoltage will be indicated when it reads low (0). The GPIO will return to its normal state if the undervoltage condition is cleared. Therefore you would need to read the GPIO frequently to detect transient conditions.

Answer 2

If you want to do it with a shell script, here is a solution that works on Pi 1, 2 & 3 (not tested in zero). With the command:

/opt/vc/bin/vcgencmd get_throttled

If the answer is:

throttled=0x0

You're good with the supplied voltage and SoC temperature.

The bits on the returned number mean:

Bit Hex value   Meaning
0          1    Under-voltage detected
1          2    Arm frequency capped
2          4    Currently throttled
3          8    Soft temperature limit active
16     10000    Under-voltage has occurred
17     20000    Arm frequency capping has occurred
18     40000    Throttling has occurred
19     80000    Soft temperature limit has occurred

A value of 0x50000 means 16 & 18 -- from the boot moment up to now Under-Voltage has occurred at some point as well as Throttling has occurred.

Reference: vcgencmd Documentation.

Answer 3

How does the Pi know it being under-powered and to show the lighting bolt?

This is a very good question, IMHO, and since it doesn't seem to have a current and complete answer, I'd like to chime in. First, I need to credit @Ghanima's Q&A here for calling out the PMIC (Power Management IC) as the MXL7704.

The operation of the MxL7704 is covered here, and in the data sheet.

If we begin with the Rev 4 schematics for the RPi 4B, we see the pertinent connections between the MxL7704 and the USB-C power input summarized in the schematic below:

^{simulate this circuit – Schematic created using CircuitLab}

Note first the 5V_SYS node is simply a low-pass filtered version of the VBUS 5V input power. The filter has a time constant determined by R5 & C12 of 0.1 msec. 5V_SYS is the voltage monitored by the MxL7704, and compared to its 4.63V internal reference to determine the state of the Power Good outputs (PG1 & PG2) at pins 5 & 20, respectively. Please refer to the MxL7704 data sheet, and the block diagram (copied below) for details.

Knowing how the RPi's 5V power input is low-pass filtered, and routed to the MxL7704 as 5V_SYS, the Block Diagram fills in most of the other details to answer the question:

• The 4.63V voltage monitor (MON) provides a binary output indicating whether 5V_SYS is above the 4.63V threshold, or below it. This output is stored in a data register in the I2C block, and from there it is also available to the PGOOD state machine.

• The PGOOD state machine receives inputs from the "external system" (RPi's SOC) via the I2C bus that configure the state machine. This configuration, in turn, determines how it processes its various inputs to yield the PG1 and PG2 outputs at pins 5 & 20 of the MxL7704.

• The status of the 5V_SYS voltage (i.e. above or below 4.63V) is kept in one of the registers internal to the MxL7704. The section of the data sheet titled Input Voltage Monitor Flag covers details, but of course cannot tell us how the RPi's proprietary hardware and firmware interact with the MxL7704.

• Nevertheless, it is evident that this binary representation of the 5V_SYS status stored in these registers is the value used by the RPi to set and clear the Low Voltage Warning flag.

Answer 4

vcgencmd and checkthrottle.sh

There are two parts to this question: How is under voltage detected and how can that information be used without more hardware. The first part has already been ably addressed by @seamus's answer.

The second part can be accomplished using vcgencmd. Here is a shell script I've written which prints out the throttle status in plain English. It also returns an error code if the problem is occurring now so that it can be used by a "watchdog" type of daemon to shutdown the Pi if problems persist.

#!/bin/bash -e

# Check whether a Raspberry Pi is currently experiencing insufficient
# power or overheating or if it has had such problems in the past.

# From vcgencmd(1)
   # get_throttled

   #      Returns the throttled state of the system. This is a bit
   #      pattern - a bit being set indicates the following meanings:

   #      Bit   Meaning
   #      ────  ────────────────────────────────────
   #       0    Under-voltage detected
   #       1    Arm frequency capped
   #       2    Currently throttled
   #       3    Soft temperature limit active
   #      16    Under-voltage has occurred
   #      17    Arm frequency capping has occurred
   #      18    Throttling has occurred
   #      19    Soft temperature limit has occurred

   #      A value of zero indicates that none of the above conditions
   #      is true.


A=( [ 0]="Under-voltage detected"
    [ 1]="Arm frequency capped"
    [ 2]="Currently throttled"
    [ 3]="Soft temperature limit active"
    [16]="Under-voltage has occurred"
    [17]="Arm frequency capping has occurred"
    [18]="Throttling has occurred"
    [19]="Soft temperature limit has occurred" )

for ((i=0; i<32; i++)); do
    if [[ ! ${A[i]} ]]; then
    A[i]="set, but meaning is unknown. See vcgencmd(1)."
    fi
done

# vcgencmd get_throttled returns a string like "throttled=0x50000" 
eval $(vcgencmd get_throttled)

# If user supplied a number (e.g., 0x50005), use it instead.
if [[ "$1" ]]; then throttled="$1"; fi

if (( throttled == 0 )); then
    echo "No problems with voltage or temperature since boot."
elif (( (throttled & 0xFF) == 0 )); then
    echo "Problems have occurred but are not happening now."
fi

for ((i=0; i<32; i++)); do
    if (( throttled & 2**i )); then
    echo "bit $i: ${A[$i]}"
    fi
done

# Exit with a non-zero value if problems are occurring now.
exit $(( throttled & 0xFF ))

Usage

If you run checkthrottle.sh, it'll show you a message such as:

raspberrypi:~$ checkthrottle.sh
Problems have occurred but are not happening now.
bit 16: Under-voltage has occurred
bit 18: Throttling has occurred

You can also give checkthrottle.sh a command line argument to interpret any of the cryptic numbers returned by vcgencmd get_throttled.

raspberrypi:~$ checkthrottle.sh 0xf0005
bit 0: Under-voltage detected
bit 2: Currently throttled
bit 16: Under-voltage has occurred
bit 17: Arm frequency capping has occurred
bit 18: Throttling has occurred
bit 19: Soft temperature limit has occurred

The script returns true if no problems are currently occurring, so its result can be used in another script. For example,

declare -i count=0
while sleep 60; do
    if checkthrottle.sh; then
        count=0
        continue
    else
        count=count+1
        if (( count > 5 )); then
            shutdown --poweroff +1 "Batteries low. Shutting down soon to avoid crashing."
            exit 1
        fi
    fi
done

Answer 5

The following explains how the power circuitry of modern Pi (with 40 pin header) works Raspberry Pi Power Limitations.

The lightning bolt is controlled by the kernel, and AFAIK there is no simple way to access it.

The power state can be detected more easily. This is directly available through the system in B+ Pi2 /sys/class/leds/led1, and accessible through a program on Pi3 https://raspberrypi.stackexchange.com/a/60275/8697

NOTE Under Bullseye this changed to /sys/class/leds/PWR which is a link to /sys/devices/platform/leds/leds/PWR/