{"id":15148337,"url":"https://github.com/rpispy/pi-hole-screen","last_synced_at":"2026-01-19T06:32:39.005Z","repository":{"id":222005416,"uuid":"755724651","full_name":"RPiSpy/pi-hole-screen","owner":"RPiSpy","description":"A repository for a 128x64 OLED screen add-on for Raspberry Pi based Pi-Hole systems.","archived":false,"fork":false,"pushed_at":"2025-02-28T13:44:05.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-07T02:47:21.965Z","etag":null,"topics":["oled","pi-hole","raspberry-pi"],"latest_commit_sha":null,"homepage":"https://www.raspberrypi-spy.co.uk/2019/10/pi-hole-oled-status-screen/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RPiSpy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-02-10T22:22:41.000Z","updated_at":"2025-02-28T13:44:09.000Z","dependencies_parsed_at":"2024-02-28T21:28:45.332Z","dependency_job_id":"31ccd5d4-8ca4-4858-a335-bfd9a2049edf","html_url":"https://github.com/RPiSpy/pi-hole-screen","commit_stats":null,"previous_names":["rpispy/pi-hole-screen"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPiSpy%2Fpi-hole-screen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPiSpy%2Fpi-hole-screen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPiSpy%2Fpi-hole-screen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPiSpy%2Fpi-hole-screen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RPiSpy","download_url":"https://codeload.github.com/RPiSpy/pi-hole-screen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247584061,"owners_count":20962071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["oled","pi-hole","raspberry-pi"],"created_at":"2024-09-26T13:03:05.214Z","updated_at":"2026-01-19T06:32:38.999Z","avatar_url":"https://github.com/RPiSpy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-hole-screen\nA repository for a 128x64 OLED screen add-on for Raspberry Pi based Pi-Hole systems.\n\n# Requirements\n- A Raspberry Pi successfully running Pi-Hole\n- A 128x64 I2C OLED Screen\n- (optional)LED with current limiting resistor connected to GPIO24\n- (optional)Momentary switch connected between GPIO21 and Ground\n\nDeveloped and tested on a Raspberry Pi 3B. Deployed to my Raspberry Pi B+ running Pi-Hole. Both build on Raspberry Pi OS Lite (32bit) \"Bookworm\".\n\nInstallation of additional libraries may be required on older versions of Raspberry Pi OS.\n\n# Configure I2C\nIn order for the script to talk to the screen you need to enable and setup the I2C interface.\nThis can be done by following the instructions in my\n[Using an I2C OLED Display Module with the Raspberry Pi](https://www.raspberrypi-spy.co.uk/2018/04/i2c-oled-display-module-with-raspberry-pi/) blog post.\n\nIn particular the section titled \"Enable I2C Interface\".\n\nOnce completed you should be able to run\n```\ni2cdetect -y 1\n```\nand see your screen address listed.\n\n# Change I2C Bus Speed (optional)\nFor smoother scrolling you can increase the I2C bus speed as explained in my [Change Raspberry Pi I2C Bus Speed](https://www.raspberrypi-spy.co.uk/2018/02/change-raspberry-pi-i2c-bus-speed/) blog post. \n\n# Initial Setup\nOnce you screen is correctly connected and enabled you can proceed with the Python script setup.\n\nThe setup process is detailed below but it also described in my [Pi-Hole OLED Status Screen](https://www.raspberrypi-spy.co.uk/2019/10/pi-hole-oled-status-screen/) blog post. \n\n## Download project files\nUse SSH to gain access to the Pi-Hole command line and ensure you are in the home directory using:\n```\ncd ~\n```\nClone the project repository:\n```\ngit clone https://github.com/RPiSpy/pi-hole-screen.git\n```\nEnter the new project folder:\n```\ncd pi-hole-screen\n```\nRename the config-template.py file to config.py:\n```\nmv config-template.py config.py\n```\nEdit config.py and add your Pi-Hole API password:\n```\nnano config.py\n```\nUse CTRL-X, Y and ENTER to save and quit.\n\n## Setup Python 3 Virtual Environment\nTo ensure we don't interfere with the standard Python environment we will create a virtual environment inside the project folder:\n```\ncd ~/pi-hole-screen\n```\nThen to create a virtual environment called \"venv\" use:\n```\npython3 -m venv venv\n```\nthen activate it:\n```\nsource venv/bin/activate\n```\nThen finally install the libraries required by the script:\n```\npython -m pip install requests luma.oled gpiozero lgpio\n```\n\n## Test the Script\nIn order to check the screen is working you can run the script:\n```\npython oled-screen.py\n```\nTo quit the script use CTRL-C.\n\n## Setup cron\nAdd a reference to crontab so the script launches automatically when Pi-Hole reboots:\n```\ncrontab -e\n```\n(If prompted select nano as the default editor)\nAdd the following line:\n```\n@reboot /home/pi/pi-hole-screen/venv/python /home/pi/pi-hole-screen/oled-screen.py \u003e\u003e /home/pi/Scripts/oled-screen.log 2\u003e\u00261\n```\n\n## Reboot\nUsing the Pi-Hole web interface reboot the system via the \"Settings\" page.\n\n## Troubleshooting\nIf the screen doesn't appear to work, get to the commandline and look at the contents of the oled-screen.log file.\n\n# Fonts\nThe following fonts are used by the script to display data on the screen:\n- Big Shot by Portmanpreau - https://www.dafont.com/big-shot.font\n- Pixel 12x10 by Corne2Plum3 - https://www.dafont.com/pixel12x10.font\n- VCR OSD Mono by Riciery Leal - https://www.dafont.com/vcr-osd-mono.font\n\nThey were chosen to best represent text at the required pixel sizes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpispy%2Fpi-hole-screen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frpispy%2Fpi-hole-screen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpispy%2Fpi-hole-screen/lists"}