We already have a guide on using Pi-Hole with the Raspberry Pi Zero W to send advertisements on your network into a black hole.

But, the PiOLED is small and we want to monitor more statistics at a glance. While we could open the web console to monitor Pi-hole, we can't show that to friends easily. Plus, who doesn't want more shiny, blinky, networking hardware?

We're going to install PADD (Pi-hole Ad Detection Display) and Pi-Hole on the Adafruit 2.8" or 3.5" PiTFT Plus to display useful and fun statistics such as Amount of Pi-holed Advertisements, and the top offending domain attempting to serve pesky advertisements to your network.

What's Pi-hole? 

Pi-hole is an open-source project which let's your Pi act as a DNS (Domain Name Server). While you may have an ad-blocker installed on your browser, do you have one on your phone? What about blocking in-application advertisements in your mobile games? On your Smart TV? On your smart fridge? 

Pi-hole lets you block ads from any device configured to use it as a Domain Name Server. When an advertisement (i.e: ads.adserver.com) tries to resolve it's IP address, Pi-hole will return nothing back. You'll never connect to the advertisement server and the ad won't even load. This makes it quicker, faster, and use less data than conventional ad blockers. 

Parts

You'll need the following parts to get up-and-running with Pi-hole and PADD

You need a Raspberry Pi with built in wireless. The Raspberry Pi 3 line (3, 3 B, 3 B+) devices are wireless-ready without external configuration:

1 x Raspberry Pi 3
Model B+ - 1.4GHz Cortex-A53 with 1GB RAM

You'll also need a power supply for your Pi and a MicroSD card for holding the Pi's OS and it's applications:

1 x 5V 2.4A Power Supply
5V 2.4A Switching Power Supply with 20AWG MicroUSB Cable
1 x 8GB MicroSD Card
8GB Class 10 SD/MicroSD Memory Card - SD Adapter Included

PiTFT Display

To use the full version of PADD, you'll need a PiTFT supporting a resolution of at least 480x320.

If you're using a display smaller than 480x320, PADD will boot into a mini mode which displays way less statistics about the network. To view PADD, we suggest using the PiTFT Plus 3.5":

Blue polished finger touching the PiTFT Plus 480x320 3.5" TFT+Touchscreen for Raspberry Pi.
Is this not the cutest, little display for the Raspberry Pi? It features a 3.5" display with 480x320 16-bit color pixels and a resistive touch overlay
Out of Stock

If you happen to have one of our 2.8" or 2.4" PiTFT's, those will work too

Red polished white finger touching the PiTFT Plus Assembled 320x240 2.8" TFT + Resistive Touchscreen.
Is this not the cutest little display for the Raspberry Pi? It features a 2.8" display with 320x240 16-bit color pixels and a resistive touch overlay. The plate uses the high...
Out of Stock
Red polished nail touching the screen of a Adafruit PiTFT Plus 320x240 2.8" TFT + Capacitive Touchscreen.
Is this not the cutest little display for the Raspberry Pi? It features a 2.8" display with 320x240 16-bit color pixels and a capacitive touch overlay. That's right,...
$44.95
In Stock
Black polished white finger touching Adafruit PiTFT 2.4" HAT display in a Adafruit PiTFT 2.4" HAT Mini Kit.
Is this not the cutest little display for the Raspberry Pi? It features a 2.4" display with 320x240 16-bit color pixels and a resistive touch overlay. The HAT uses the high speed...
Out of Stock

Other Parts

We used a Pi 3 case to protect our Pi from aesthetics and to protect our Pi against scratches, bumps, and falls. The case also makes the Pi-hole look like a networking appliance.

Angled shot of assembled black Pi Model B+ / Pi 2 / Pi 3 Case Base with a clear lid.
It took awhile to perfect - but that's okay since we can now safely say that the Adafruit case for Raspberry Pi Model B+ / Pi 2 / Pi 3 is The...
$7.95
In Stock

If you don't have a way to burn the OS image onto a micro sd card from your computer, we suggest picking up a USB MicroSD reader/writer.

We'll need to set up the Pi with an operating system (OS), WiFi, and secure login (SSH) support before we install Pi Hole.

We have a guide on how to set up your Pi Zero W 'headless' which is how we recommend you get started. The Pi 3 (and up) and the Pi Zero W both have built in WiFi, so our guide can be used for both platforms:

Make sure you are using Raspbian LITE and not stretch for the OS setup.

Here's the quick-start for people with some experience:

  1. Download the latest 'Lite' Raspbian to your computer
  2. Burn the Lite Raspbian to your MicroSD card using your computer
  3. Re-plug the SD card into your computer (don't use your Pi yet!) and set up your wifi connection by editing supplicant.conf
  4. Activate SSH support
  5. Plug the SD card into the Pi 3
  6. If you have an HDMI monitor we recommend connecting it so you can see that the Pi is booting OK
  7. Plug in power to the Pi 3 - you will see the green LED flicker a little. The Pi 3 will reboot while it sets up so wait a good 10 minutes
  8. If you are running Windows on your computer, install Bonjour support so you can use .local names, you'll need to reboot Windows after installation
  9. You can then ssh into raspberrypi.local

Use the following instructions to install Pi Hole:

https://github.com/pi-hole/pi-hole/#one-step-automated-install

Pre-Check

OK once you have set your Pi up and the WiFi is connecting to your home or office network, and your can ssh into it, continue with these easy steps! If you cannot connect via ssh yet, go back and read some of our guides until  you are able to log into your Pi.

Change Hostname

I like to do this first so I dont get confused between all the different Pi's in the house

Edit the hostname with sudo nano /etc/hostname and put something else on that first line, like pi-hole

Also change it in the hosts file with sudo nano /etc/hosts to match the same name. It's probably the last line:

Reboot and when you ssh in again, use pi-hole.local

Now's also a good time to change the Pi's password with passwd

Run Pi Hole Installer

There's more information on how installation at https://pi-hole.net/ - as of the writing of this guide, its easier to just run:

curl -sSL https://install.pi-hole.net | bash

It will take quite a while to install, and may seem to 'hang' at points. Just let it do its thing for about 20 minutes!

The screenshots below are based on the 3.1.4 release of Pi-Hole. The latest version may have slightly different screens and options, but generally accepting defaults to everything should be OK.

Configuration

Pick who will be the upstream DNS (for non-ad blocked sites) - Google is fine and will probably be up all the time

99% of people will use IPv4 - if you need IPv6 you'd know!

The installer will automatically try to set the dynamic IP address it got from your router to be fixed. This works well enough, if you have an advanced network set up, you can configure a custom IP address

The Web Interface is kinda cool, and is password protected. We'll be showing most of the stats on the little OLED but we still need the API to be running so keep this on

It will keep installing! Just hold tight...

When its done you'll get this final config screen! Copy & paste the password into another window for now

Test Admin Page

On your desktop computer or tablet, visit http://pi-hole.local/admin/ And you should see an administration panel!

Test Blocking

On your tablet, phone, computer, etc - Set up your DNS server in the network settings to be the IP address of the Pi

You may need to restart your network or browser to have it kick in, also there may be some cached ads so don't worry if not everything is blocked. Visit your favorite site with ads (not adafruit.com cuz we don't have any! :) and see the difference!

Now that you've got that done, lets continue and install the display!

Assembly

If you are using a case like the Adafruit Raspberry Pi Case, snap-fit the Pi into the case:

Leave the clear top off, we'll need to access the GPIO header for the PiTFT. 

The PiTFT's four mounting ears can be used to attach the display to a bezel. But, we'll be snapping them off with pliers (they're perforated) for a flush-fit with the case/ 

Position the PiTFT over the 2x20 GPIO connector and press downwards. Make sure the PiTFT's header is flush against the GPIO header.

Now that our PiTFT is assembled, let's configure the display to work with our Pi.

PiTFT Configuration

You'll need to perform some configuration to get the PiTFT up and running. We'll do this through the PiTFT installer script.

This script will do all the work for you, and install both device tree overlay support as well as configure rotation and any HDMI mirroring. PiTFT no longer needs any custom kernels or modules, so you can continue to update/upgrade your Pi and it will work with the most recent releases.

To download the script, click the link below and come back to this page when you're done:

Easy Single Command Install

The latest script allows you to specify all of your options within the command so you can sit back and watch the installation.

For the PiTFT 3.5" Resistive touchscreen with a rotation of 270 degrees (so the PiTFT can sit on your desk while the USB cable is plugged in), use the following command:

sudo python3 adafruit-pitft.py --display=35r --rotation=270 --install-type=console
If you're not using the 3.5" PiTFT, follow this page to select a command for your display type. Remember to modify the --rotation parameter to --rotation=270: https://learn.adafruit.com/adafruit-pitft-3-dot-5-touch-screen-for-raspberry-pi/easy-install-2#easy-single-command-install-options-3074227-9

Say Yes to the question Would you like the console to appear on the PiTFT display

Then, reboot the Pi. You'll see the console appear on the Pi. Don't worry if the Pi-hole doesn't display, we're going to configure that next.

Next we're going to install PADD, the Pi-hole Ad Detection Display. This application displays statistics about advertisements, your Pi's status, network configuration and system statistics on your PiTFT.

It is written and maintained by Jim McKenna who did an awesome job!

In the SSH session with your Pi, navigate to your home directory:

Grab a copy of PADD:

wget -N https://raw.githubusercontent.com/jpmck/PADD/master/padd.sh

Make PADD executable by running:

sudo chmod +x padd.sh

Open PADD at Pi Bootup

Next, we're going to set PADD to open automatically on your PiTFT when we start our Pi.

Open ~/.bashrc:

nano ~/.bashrc

Navigate to the end of the file (by pressing the down arrow key) and add the following text:

# Run PADD
# If we're on the PiTFT screen (ssh is xterm)
if [ "$TERM" == "linux" ] ; then
  while :
  do
    ./padd.sh
    sleep 1
  done
fi

Save (control+O) the configuration and exit (control+X) nano to be brought back to the terminal.

Turn off the PiTFT at Night

The PiTFT is bright and doesn't need to be powered-on at night, so let's put it to sleep until we wake up.

Edit cron as root:

sudo crontab -e

Select nano as an editor by pressing the key. 

Scroll beneath the commented text (#) and enter the following:

# PADD Sleep
# Turn off the PiTFT+ at midnight
00 00 * * * sh -c 'echo "0" > /sys/class/backlight/soc\:backlight/brightness'
# Turn on the PiTFT+ at 8:00 am
00 08 * * * sh -c 'echo "1" > /sys/class/backlight/soc\:backlight/brightness'

Save (control+O) the configuration and exit (control+X) nano to be brought back to the terminal.

Reboot the Pi to apply the new changes by running:

sudo reboot

When your Pi reboots, the TFT should boot into PADD:

After PADD starts, it should go into display mode. If your PADD is displaying statistics about your network, congrats! We're all set up and ready to test our advertisement-blocking-pi.

Smaller Pi Displays

You can also use this guide with smaller displays, like the PiTFT 2.8". The full PADD display is unsupported by this screen - but don't worry - it'll automatically display a smaller, mini PADD interface. 

Configure and Test Ad Blocking

PADD will display the Pi-hole's IP address underneath its Network tab:

On your tablet, phone, computer, etc - Set up your DNS server in the network settings to be the IP address of the Pi:

You may need to restart your network or browser to have it kick in, also there may be some cached ads so don't worry if not everything is blocked. 

Not sure if your Pi-hole is configured properly? Visit blockads.fivefilters.org from the device you're configuring to test Pi-hole functionality. 

You can also visit some of your favorite sites or load a mobile application which would normally have in-application advertisements to test your Pi-hole.

Router Configuration for Pi-Hole

adafruit_products_Screenshot-2017-02-23-20.23.07.png
src: https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245

Don't want to configure each device on your network separately? Have a device that doesn't allow you to enter DNS settings? You can configure your router's DHCP options to force clients to use Pi-hole as their DNS server.

Want to switch back to a terminal? Hit CTRL+C

Updating PADD

If your PADD displays Update avail., you'll need to update it. PADD only uses stable builds of Pi-hole and FTLDNS, so you can rest assured that your internet won't break.

We can do this easily by SSH'ing into our Pi-Hole:

Log in. Then, navigate to our home directory:

And update the version of PADD on your Pi by running:

wget -N https://raw.githubusercontent.com/jpmck/PADD/master/padd.sh

After the update completes, restart your Pi by running:

sudo reboot

Once restarted, PADD should display "Pi-hole is up-to-date".

Troubleshooting

My Pi-Hole shows an error: `bash warning: setlocaleL LC_ALL: cannot change locale (en_US.UTF-8)`

Enter the following in your terminal to launch raspi-config:

sudo raspi-config

From the menu, select: Localization Options -> Change Locale.

Select Generate en_US.UTF-8 UTF-8 , and walk through the prompts.

This guide was first published on Jun 28, 2018. It was last updated on Mar 08, 2024.