Minimal and clean dashboard to visualize some stats of Pi-Hole with an E-Ink display attached to your Raspberry Pi.
This is very useful if you keep a Pi Zero with Pi-Hole connected to your router and you want a clean dashboard to monitor its status. Additionally, I do not use static IP so if this ever change, I have an easy way to get the real time IP of the Raspberry.
- Raspberry Pi Zero WH (You can also solder the headers by yourself)
- 2.13 inch E-Ink display HAT for Raspberry Pi
- Pi-Hole (v5.x or v6.x compatible)
Version 2.0.0 of this dashboard is compatible with Pi-hole v6.x which features a completely redesigned REST API. The dashboard now uses the new API endpoints to fetch the required data. If you're upgrading from a previous version of this dashboard that was used with Pi-hole v5.x, please update your configuration file to use a password instead of an API token.
For detailed changes between versions, please see the CHANGELOG.md file.
After set the admin password, the tool should run out of the box with standard installation of Pi-Hole.
For Pi-hole v6:
- Set your Pi-hole password in
/etc/pihole-dashboard/config.toml - If your Pi-hole has local API authentication disabled, you can leave the password empty
If your instance of Pi-Hole is running on a different port than 80, you should change it inside /etc/pihole-dashboard/config.toml.
The IP address is shown considering the wlan0 interface, you can change this value in /etc/pihole-dashboard/config.toml.
Making the E-Ink display work is not fully covered here, as it depends mostly on the display you use. As said before, I have the WaveShare's 2.13 inch E-Ink display, that has a nice detailed Wiki here: https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT.
You can find on the above link the list of required dependencies for Python and how to run and test the provided examples. Just for reference, this is the list of dependencies that should be installed on a Raspberry Pi Zero to configure the display I have:
sudo apt-get install python3-pip python3-pil python3-numpy
sudo pip3 install RPi.GPIO
sudo pip3 install spidev
In order to use the 2.13 inch E-Ink display with Python, you also need to get and build their waveshare-epd library:
git clone https://github.com/waveshare/e-Paper.git
cd e-Paper/RaspberryPi_JetsonNano/python/
sudo python3 setup.py installYou can check if the display is working by running the test example:
cd e-Paper/RaspberryPi_JetsonNano/python/
sudo python3 examples/epd_2in13_V2_test.pyTest script depends on your screen type. There should be a sticker which tells your screen type. If yours is a newer V3, before run the test, your should change V2 to V3.
Remember that you need root access to control the display, so be sure to run the python example as root.
You also need to enable the SPI interface, otherwise the display connection will not work.
The example will print several geometric objects on the screen if everything is working as expected, followed by a simple clock program that updates every second. If the example does not work, do not proceed further with the installation as this probably will not work either.
The installation requires to have already a Raspberry with Pi-Hole installed and correctly running, if you have problem installing Pi-Hole check their README.
Ensure that you have already this Pillow dependency installed:
sudo apt install libopenjp2-7sudo pip3 install pihole-dashboardgit clone https://github.com/santoru/pihole-dashboard
cd pihole-dashboard
sudo pip3 install .Once installed, Add your Pi-hole password to your config file, change screen type if needed (at /etc/pihole-dashboard/config.toml), then reboot the Raspberry Pi.
The dashboard should appear few minutes after the reboot.
You can remove the tool anytime by running
sudo pip uninstall pihole-dashboardYou can also manually remove the cronjob and config file by running
sudo rm /etc/cron.d/pihole-dashboard-cron
sudo rm -rf /etc/pihole-dashboard/The tool will install a Cron Job on the Raspberry Pi that will check the status of Pi-Hole every minute. If there's an update to display, the screen will refresh and update its content.
If the dashboard is not displaying, you can check if the script returns any errors by running:
sudo pihole-dashboard-drawFor more detailed diagnostics, the dashboard provides several troubleshooting options:
Shows configuration and API endpoints:
sudo pihole-dashboard-draw -vThis displays:
- Configuration file location
- Current settings (interface, Pi-hole IP/port, screen type, etc.)
- API endpoints being used
- Connection and authentication test results
- Execution status
Test API connections and authentication without updating the display:
sudo pihole-dashboard-draw -tThis is particularly useful for diagnosing 401 Unauthorized errors. It will:
- Test basic connectivity to Pi-hole
- Test authentication with the configured password
- Test API access with proper authentication
- Show helpful error messages and suggested fixes
For advanced troubleshooting with full API response details:
sudo pihole-dashboard-draw -dCombine with test mode for maximum diagnostic information:
sudo pihole-dashboard-draw -t -dsudo pihole-dashboard-draw --versionIf you see 401 errors in test mode:
- Ensure the password in
/etc/pihole-dashboard/config.tomlmatches your Pi-hole password - If you've just upgraded to Pi-hole v6, you need to update from API token to password
- For authentication-free local access, verify that local API authentication is disabled in Pi-hole settings
- Verify Pi-hole is running:
systemctl status pihole-FTL - Check IP and port settings in the configuration file
- Ensure your network allows connections to the Pi-hole server
If everything is working as expected with the default command, nothing will be printed out. If you still have errors, please open an issue.