PiOLED Dashboard (SH1106)

A Raspberry Pi system monitor for a 128x64 SH1106 OLED display over I2C.

This project shows live system information on a small OLED screen and can also control a cooling fan based on CPU temperature.

What This Project Does

The current pioled_dashboard.py rotates through 3 display pages:

• Page 1: uptime, hostname, IP address, network download speed, network upload speed
• Page 2: CPU cores, CPU frequency, CPU usage, CPU temperature, power warning status, fan speed
• Page 3: RAM usage, disk usage, disk read speed, disk write speed, power warning status, fan speed

It also includes:

• automatic page switching every 5 seconds
• live refresh every 0.5 seconds
• temperature-based PWM fan control on GPIO 14
• under-voltage / power warning detection using vcgencmd
• boot-time startup support with run_pioled_dashboard.sh

Hardware Needed

• Raspberry Pi
• SH1106 128x64 OLED display
• I2C wiring between the Pi and the OLED
• optional cooling fan connected to GPIO 14 if you want fan control

Project Structure

PiOLED-Dashboard/
|-- LICENSE
|-- pioled_dashboard.py
|-- pixelmix.ttf
|-- README.md
|-- run_pioled_dashboard.sh

What Each File Does

• pioled_dashboard.py - main Python script for reading system stats, drawing the OLED UI, and controlling the fan
• run_pioled_dashboard.sh - startup script used to launch the dashboard after boot
• pixelmix.ttf - font used for the OLED text
• README.md - setup and usage guide
• LICENSE - project license

Quick Start

If you want the shortest path to getting it running:

1. Enable I2C on the Raspberry Pi.
2. Install the required packages.
3. Connect the SH1106 OLED.
4. Run python3 pioled_dashboard.py.
5. If it works, set up run_pioled_dashboard.sh in crontab to start on boot.

The detailed steps are below.

Enable I2C

Open Raspberry Pi configuration:

sudo raspi-config

Then go to:

Interface Options -> I2C -> Enable

Reboot:

sudo reboot

Check That the OLED Is Detected

Install I2C tools:

sudo apt-get update
sudo apt-get install -y python3-smbus i2c-tools

Scan the I2C bus:

sudo i2cdetect -y 1

You should normally see either:

• 3c
• 3d

If nothing appears, check:

• OLED wiring
• 3.3V / GND connections
• SDA and SCL pins
• whether I2C is enabled

Python Packages

Install the required packages:

sudo apt-get install -y python3-pip python3-pil python3-psutil python3-rpi.gpio
sudo -H pip3 install --upgrade luma.oled

If needed, you can also install the Python libraries with pip3:

sudo -H pip3 install --upgrade luma.oled pillow psutil RPi.GPIO

How the OLED I2C Setup Works

The script tries these OLED addresses in pioled_dashboard.py:

serial = i2c(port=1, address=0x3D)

and if that fails, it falls back to:

serial = i2c(port=1, address=0x3C)

That means:

• the script uses I2C bus 1
• it first tries OLED address 0x3D
• it then falls back to 0x3C
• the display driver is sh1106

The code already handles the 2 most common SH1106 I2C addresses:

• 0x3D
• 0x3C

Only change the code in pioled_dashboard.py if your display uses an address other than those two.

Run the Project

Clone the repository and start the script:

git clone https://github.com/mechash/PiOLED-Dashboard
cd PiOLED-Dashboard
python3 pioled_dashboard.py

What the Current Code Depends On

The current code uses these Raspberry Pi and Linux specific features:

• /sys/class/thermal/thermal_zone0/temp for CPU temperature
• /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq for CPU frequency
• vcgencmd get_throttled for power / under-voltage status
• RPi.GPIO for fan PWM control

Because of that, this script is meant for Raspberry Pi and will not fully work on a normal desktop or non-Pi system.

Fan Control

The current code controls a fan on:

• GPIO pin 14

Fan speed is adjusted automatically based on temperature using PWM.

If you are not using a fan, you should know that the current code still initializes GPIO and PWM. In that case, you may want to edit pioled_dashboard.py before running it.

Run on Boot

The included run_pioled_dashboard.sh script:

• clears the terminal
• moves into the project folder
• waits 5 seconds
• runs python3 pioled_dashboard.py

Make it executable:

cd ~/PiOLED-Dashboard
chmod +x run_pioled_dashboard.sh

Open crontab:

crontab -e

Add this line:

@reboot ~/PiOLED-Dashboard/run_pioled_dashboard.sh

Then reboot and check the OLED.

Beginner Notes

If you are new to Raspberry Pi projects, these are the most common things that cause problems:

• I2C is not enabled
• the OLED address in the code does not match the real device address
• required packages are missing
• the font file pixelmix.ttf is missing or moved
• the fan is wired differently than the GPIO pin used in the script
• run_pioled_dashboard.sh still points to an old folder name after a repo rename

License

This project is released under the MIT License. See LICENSE.