Pi-hole Visualizer

Pi-hole Visualizer displays Pi-hole statistics on the Raspberry Pi Sense-HAT with multiple animations.

Details

• Pi-hole Visualizer cycles between five different customizable animations at regular intervals.

• The first animation(icon) displays the global connection status. A green pulsating icon represents a functioning internet connection.

• The second animation(vertical bar chart) depicts the overall volume of DNS queries generated on the network. Each column represents a specific and adjustable time interval relative to the previous 24-hour timeframe. The time interval ranges from 10 minutes to 3 hours. The chart can be color coded to represent the level of DNS traffic or percentage of ads blocked.

• In the third animation(spiral graph), the daily ad block percentage is represented by the number of red pixels displayed.

• The fourth animation(horizontal bar chart) displays the relative level of DNS queries generated by top clients on the network in descending order.

• The last animation(pie chart) displays the proportion of each DNS record type.

• Options include manual chart selection, randomization of pixel generation, specifying the orientation of the display, and low-light mode.

• Joystick controls allow for adjustment of program options interactively.

• Pi-hole Visualizer is either run from the command line or enabled as a systemd service to run automatically at boot.

---

Requirements

• To install Pi-hole, run curl -sSL https://install.pi-hole.net | bash.
• The Sense-HAT package can be installed with sudo apt-get install sense-hat.

---

Authorization

To view statistics regarding top clients and query types, authorization from the Pi-hole web server is required. If you are running Pi-hole Visualizer on the same machine that is running Pi-hole, it is assumed a configuration file containing the password hash is located at (/etc/pihole/setupVars.conf) and no action is required.
If you are on a remote machine, you can enable authorization by creating an environment variable containing the password hash. Append the following line to (~/.bash_profile) or (~/.profile): export WEBPASSWORD="hash_value".

---

Usage

dns_stats.py [OPTION]

Options

-h, --help
Show this help message and exit.

-i {10, 30, 60, 120, 180}, --interval {10, 30, 60, 120, 180}
Specify interval time in minutes. Defaults to one hour.

-c {basic, traffic, ads}, --color {basic, traffic, ads}
Enter 'basic' to generate bar charts in the default red color, 'traffic' to color code based on level of DNS queries, or 'ads' to color code by ad block percentage.

-a ADDRESS, --address ADDRESS
Specify address of DNS server, defaults to localhost.

-o {0, 90, 180, 270}, --orientation {0, 90, 180, 270}
Specify orientation of display so that RPi may be installed in non-default orientation.

-ll, --lowlight
Lower LED matrix brightness for use in low light environments.

-r, --randomize
Randomize order of pixels displayed.

-s {1, 2, 3, 4, 5}, --select {1, 2, 3, 4, 5}
Specify which animation(s) to display, with multiple items separated by a space.

Joystick Controls

• UP - PUSH
  Cycle color mode.

• RIGHT - PUSH
  Cycle interval selection.

• DOWN - PUSH
  Toggle low-light mode.

• LEFT - PUSH
  Cycle display orientation.

• MIDDLE - PUSH
  Toggle randomization.

• MIDDLE - HOLD
  Exit program.

---

To Install As a System Service

1. Make the script and unit file executable:
   sudo chmod +x dns_stats.py
sudo chmod +x dns_stats.service

2. Check that the path in the unit file after ExecStart matches the path of your script.

3. Copy the unit file to the system directory:
   sudo cp dns_stats.service /lib/systemd/system

4. Enable the service to run at startup:
   sudo systemctl enable dns_stats

5. Reboot:
   sudo reboot

6. To check the status of the service:
   sudo systemctl status dns_stats