Monitor Raspberry Pi Voltage Drops and Throttle States

Hey there, Darian Vance here. As a Senior DevOps Engineer at TechResolve, I manage a fleet of devices, including dozens of Raspberry Pis running everything from CI/CD runners to internal dashboards. For months, I was baffled by intermittent performance dips. I’d check logs manually, a process that burned a couple of hours each week, until I realized the culprit was often an underpowered USB adapter. That’s when I built this automated monitoring script. It saved me time and, more importantly, it stabilized our edge deployments. If you’re running any critical services on a Pi, this is a non-negotiable setup.

Prerequisites

• A Raspberry Pi with network access.
• Python 3 installed.
• A webhook URL from a service like Slack, Discord, or a custom endpoint to receive alerts.
• Basic familiarity with the command line.

The Guide: Step-by-Step

Step 1: Understanding the Pi’s Health Endpoint

The Raspberry Pi has a fantastic built-in command-line tool called vcgencmd that gives us low-level hardware information. The specific command we care about is vcgencmd get_throttled. It returns a hexadecimal value, which acts as a bitmask. Each bit represents a specific hardware state—like “Under-voltage detected” or “Frequency Capped.” Our goal is to write a script that can run this command, parse that hex code, and tell us exactly what’s going on in plain English.

Step 2: The Python Monitoring Script

Alright, let’s get to the core logic. I’ll skip the standard virtualenv setup since you likely have your own workflow for that. Just make sure you have the requests and python-dotenv libraries available in your environment. Let’s call our script pi_monitor.py.

import subprocess
import os
import requests
from dotenv import load_dotenv

# Mappings from bit position to a human-readable meaning.
# I pulled these straight from the official Raspberry Pi documentation.
THROTTLE_MESSAGES = {
    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",
}

def get_throttle_status():
    """Executes vcgencmd and returns the hex code."""
    try:
        # We run the command and capture its output.
        result = subprocess.run(
            ["vcgencmd", "get_throttled"],
            capture_output=True,
            text=True,
            check=True
        )
        # The output is like 'throttled=0x50005', so we split and take the hex part.
        hex_code = result.stdout.strip().split("=")[1]
        return int(hex_code, 16)
    except (FileNotFoundError, IndexError, subprocess.CalledProcessError) as e:
        print(f"Error executing vcgencmd: {e}")
        return None

def parse_throttle_code(code):
    """Parses the integer code and returns a list of active issues."""
    active_issues = []
    if code is None:
        return ["Could not retrieve throttle status."]
    
    if code == 0:
        return [] # No issues, return an empty list.

    for bit, message in THROTTLE_MESSAGES.items():
        # This is the key part: we use a bitwise AND to check if a specific bit is set.
        if (code & (1 << bit)):
            active_issues.append(message)
            
    return active_issues

def send_alert(message):
    """Sends a notification to a webhook."""
    webhook_url = os.getenv("WEBHOOK_URL")
    if not webhook_url:
        print("WEBHOOK_URL not found in config.env. Cannot send alert.")
        return

    payload = {"content": f"Raspberry Pi Alert: {message}"}
    try:
        requests.post(webhook_url, json=payload, timeout=10)
        print("Alert sent successfully.")
    except requests.exceptions.RequestException as e:
        print(f"Failed to send alert: {e}")

def main():
    """Main function to run the monitor check."""
    load_dotenv('config.env')
    
    throttle_code = get_throttle_status()
    
    # We only care if there are active issues.
    issues = parse_throttle_code(throttle_code)
    
    if issues:
        message = ", ".join(issues)
        print(f"Detected issues: {message}")
        send_alert(message)
    else:
        print("System nominal. No throttling detected.")

if __name__ == "__main__":
    main()

Pro Tip: Notice the THROTTLE_MESSAGES dictionary. The bits from 0-3 represent *current* states, while 16-19 represent *historical* states (since the last boot). This is crucial. An alert for “Under-voltage has occurred” tells you that you had a power dip at some point, even if the voltage is fine right now. This helps catch issues caused by intermittent power supplies.

Step 3: Configuration

Create a file named config.env in the same directory as your Python script. This is where we’ll store our webhook URL securely, so we don’t hardcode it.

Your config.env file should contain just one line:

WEBHOOK_URL="https://your.slack.or.discord.webhook/url/here"

Step 4: Automating the Check with Cron

The final piece is to run this script automatically. I use cron for this. We can schedule it to run every 15 minutes to keep a close eye on things. Open your cron configuration and add the following line. Note that we are navigating to the script’s directory first, which ensures our relative paths in the script (like for config.env) work correctly.

*/15 * * * * cd /path/to/your/project && python3 pi_monitor.py

For a less noisy, once-a-day summary report, you could use something like this instead:

0 9 * * * cd /path/to/your/project && python3 pi_monitor.py

Common Pitfalls

Here’s where I usually mess up, so maybe you can avoid my mistakes:

• Permissions: The user running the cron job must have permission to execute vcgencmd. On a standard Raspberry Pi OS setup, the default ‘pi’ user does, but if you’re using a custom user or a hardened environment, you might need to adjust permissions.
• Python Environment in Cron: Cron jobs run in a very minimal shell environment. If you installed the Python libraries for a specific user or in a virtual environment, make sure your cron command activates that environment or uses the correct Python executable. Using an absolute path to your venv’s python binary is a good practice.
• Ignoring Historical Flags: In my first version, I only monitored the *current* flags (bits 0-3). I kept getting weird, unexplained crashes. It was only when I started logging the *historical* flags (16-19) that I caught the fleeting under-voltage events that were causing all the trouble.

Conclusion

And that’s it. You now have a robust, automated monitoring system for your Raspberry Pi’s power and thermal health. This isn’t just a “nice-to-have”; for any Pi running a production workload, it’s essential for stability and reliability. It turns your Pi from a black box into a system that tells you when it needs help. Now you can spend less time debugging mysterious failures and more time building. Happy monitoring!

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions