Pi-hole Alternative Display
While Pi-hole's chronometer is nice and other text/console displays are better, I still feel there was the potential for even more. Many of the displays that run chronometer, etc. are LCD touchscreens, yet the "touch" part isn't used. I also like having the ability to customize my Pi-hole display, so using templates for creating the display rather than hardcoding the display into a script also makes sense to me. phad combines support for touchscreens with python templates to let you display multiple screens of data by simply tapping on the screen. If you don't have a touchscreen then you can still have phad cycle between different screens at a rate you determine.
phad's default screens include:
top ads page
top domains page
top clients page
These instructions assume you already have a Raspberry Pi configured with Pi-hole and a touchscreen display. As there are many options for hardware and software, any initial setup and configuration is beyond the scope of these instructions.
- Clone this repo using
gitor download and uncompress a release from the releases page on GitHub.
- Install any missing python dependencies by invoking
pip install -r requirements.txt
- Add the phad command to
if [ "$TERM" == "linux" ] ; then while : do # Run phad in touchscreen mode (the default) /home/pi/git/phad/phad # If you don't have a touchscreen or just want to cycle between screens every 10 seconds # then use this command instead: # /home/pi/git/phad/phad -s 10 done fi
- reboot your pi
Once your pi has rebooted it should display phad's main screen on your pi's display. Simply tap the touchscreen to cycle to other displays (or wait 10 seconds for the display to automatically cycle if you specified
-s 10). The default phad configuration will show a summary page followed by pages that show the top ads, domains, and clients.
By default (when
-s is not specified) phad will revert back to the main summary page after 10 seconds. (The length of timeout can easily be changed or disabled via the phad.conf file.)
phad reads the configuration file phad.conf that is located in the same directory as phad itself. This configuration file allows you to modify the appearance of variables used to render the phad screens and modify the behavior of phad itself. See the detailed comments in phad.conf for explainations of the various options.
All variable formatting that is configurable via phad.conf is based on the "new style" of python formatting that can be found at https://pyformat.info
The templates used to display each phad screen are located in the
templates directory. These templates are standard Jinja2 templates. Jinja2 is a full featured template engine for Python, and its documentation can be found at http://jinja.pocoo.org/docs/templates/
Both Python variable formatting and Jinja2 templating are well beyond the scope of this README. Please refer to the above two project pages for detailed documnentation on both.
Command Line Options
phad --help will display a summary of command line options. Options are outlined below as well with a bit more detail.
-c [--config] configfile
Load an alternate configuration file. By default phad will load the phad.conf that is found in the same directory as phad itself.
-s [--seconds] delay
Run phad in "slideshow" mode, cycling through each screen on the display by delay seconds.
-t [--template] template_name
Render the specified template and print it to stdout. This is handy when debugging/testing custom templates, etc.
When phad is invoked normally it will write it's process ID (PID) to a file specified in the phad.conf file. The --readconf option will send a signal to that process telling it to re-read the configuration file. This lets you SSH into a pi-hole server and make changes to the configuration of phad without having to reboot or do any other tricks to get it to start using the new configuration.
Dump all phad variables to stdout in a JSON structure. This lets you view all the variables that are available within the phad templates.
Dump a list of all the top-level variable names used by phad. Phad breaks down variables into logical groups, such as top_ads, top_domains, host (for host-specific data), version (for the version of pi-hole, it's components, etc) and so on.
-l [--list] item [item...[
--jsonto limit the JSON that is displayed by specifying one or more of the item names in the
--itemsoutput. For example, use
--json --list top_adsto see only the variable data associated with the top_ads set of data.
Generate debugging output to stdout
Tips and Tricks
To blank your touchscreen by default, edit the
phad.confand add the template
blank.j2to the beginning of the list, then restart phad or tell it to re-read the configuration file via
./phad -r. The
blank.j2template simply clears the screen and does not print anything else.
To see a list of all the clients on your network that your pi-hole knows about and their hostnames if pi-hole knows about them as well, run
./pihole -t clients.j2. The clients.j2 template simply dumps a list of all known client IP addresses and hostnames if known.
Template files are read in each time phad cycles to display a new template. If you are editing an existing template or creating a new one that you have already added to the
phad.confthen simply tapping on your display to cycle through the templates is enough for phad to re-load it and display any changes that you have made.