PC Stats Monitor - ESP32 OLED Display

3D Printable case: 0.96": https://makerworld.com/en/models/2051935

1.3": https://makerworld.com/en/models/2185211

2.42" https://makerworld.com/en/models/2341351

Be aware that there are different sizes of the same SSD1306 (0.96") OLED screen on aliexpress. Im using this one "Original" version (do not purchase dual color, it won't work): It seems that there is also "New" screen version which comes in another 2 sizes. So be sure to pick correct 3D printable case from link above. https://aliexpress.com/item/1005006262908701.html

For 1.3" OLED (SH1106) I have used this version: https://aliexpress.com/item/1005009757205826.html

For 2.42" OLED (SSD1309) I have used this version: https://aliexpress.com/item/4000002579405.html

ESP32-C3 SuperMini: https://aliexpress.com/item/1005008988143743.html

HOW TO Video assembly (you can ignore LED if you are not going to use it):

Version with LED based on 2n2222: https://www.youtube.com/watch?v=umV7xA0mp5I

Version with LED based on LDO6AJSA https://www.youtube.com/watch?v=M2Oa4PDUUgE

I have noticed that some of the cheap ESP32-C3 boards have WiFi related issues on hardware level. After some additional implementations to the code in attempt to fix issues (v1.2.1), some of those issues cannot be fixed as they are on hardware level. What has helped a bit: Soldering 2 pins to the side of antenna. Check video assembly where I'm sixing that issue. Some of those faulty boards have antenna too close to other components. Like in this example (left side with 3.5mm gap is better)

Note: Some ESP32-C3 SuperMini boards (especially the external antenna variant) have a very bright built-in RGB LED (WS2812) on GPIO 8. Since GPIO 8 is used for I2C SDA, this LED cannot be turned off via software. If it bothers you, desolder the LED or cut its data trace on the PCB.

A real-time PC monitoring system that displays CPU, RAM, GPU, and disk stats on a small OLED screen using ESP32 and a companion Python script.

Features

• Dual Display Modes:
  • PC Online: Real-time stats with customizable metrics and positions
  • PC Offline: Animated clock (Mario, Space Invaders, Arkanoid, Pac-Man, Standard, or Large styles)
• v2.0 Python GUI:
  • Easy graphical configuration - no more editing files!
  • Select from all available sensors on your system
  • Support for up to 20 metrics
  • Custom labels (max 10 characters)
  • Autostart configuration built-in
  • Windows and Linux support
• Web Configuration Portal: Customize all settings via browser
  • 5-row (spacious) or 6-row (compact) display modes
  • Large 2-row and 3-row modes for readability at a distance
  • Progress bars for visual representation
  • Clock styles and animation settings
  • Automatic timezone with DST support (~50 regions)
  • Display brightness control and scheduled night dimming
  • Export/Import configuration
  • OTA firmware updates
• WiFi Portal: Easy first-time setup without code changes
• mDNS Discovery: Access your device via http://smalloled.local (configurable name)
• Optimized Performance: Minimal CPU usage on PC (<1%)
• Persistent Settings: All preferences saved to ESP32 flash memory

Quick Start for Beginners

Never done this before? Here's the simple version:

1. Flash ESP32 - Use Web Flasher (no installation needed!)
2. Connect ESP32 to WiFi - Connect to "PCMonitor-Setup" network, go to 192.168.4.1
3. Install Python - Download from python.org (check "Add to PATH" during install)
4. Install LibreHardwareMonitor (Windows only) - Download from GitHub, run as Admin
5. Run Python Script - Open terminal/cmd, type: pip install psutil pywin32 wmi pystray pillow then python pc_stats_monitor_v2.py
6. Configure in GUI - Enter ESP32 IP address, select sensors you want to monitor, click "Save & Start"
7. Position Metrics - Open ESP32 IP in browser, drag metrics to desired positions on display preview

Done! Your PC stats will now appear on the OLED display.

For detailed instructions, keep reading below.

Hardware Requirements

ESP32 Setup

• ESP32-C3 Super Mini (or compatible ESP32 board)
• OLED Display (128x64, I2C):
  • SSD1306 0.96" (most common)
  • SH1106 1.3" (larger, recommended)
  • SSD1309 2.42" (largest, uses same firmware as 0.96")
• TTP223 Touch Sensor (optional - for physical button control)
• Wiring (I2C):
  • SDA → GPIO 8
  • SCL → GPIO 9
  • VCC → 3.3V
  • GND → GND
  • TTP223 Signal → GPIO 7 (optional)
  • LED Transistor Base or LDO6AJSA PWM → GPIO 1 (optional)

Touch Button (Optional)

Wiring for optional filament led and TTP223 sensor

This wiring is for 2.42" OLED. Use the same firmware as for 0.96" OLED for flashing. No need to change firmware, TTP223 and LED will work.

If you are using 2N2222 and resistors for led here is the wiring:

If you are using LDO6AJSA here is the wiring:

The firmware supports an optional TTP223 capacitive touch sensor for physical control of the display and LED night light:

Button Gestures:

Gesture	Duration	Action
Quick tap	< 500ms	PC online: Toggle metrics/clock. PC offline: Cycle clock styles
Medium press	500ms-1s, release	Toggle LED night light on/off
Long hold	> 1s, keep holding	Ramp LED brightness up (if off) or down (if on). Release to keep.

Hardware Setup:

• Connect TTP223 signal pin to GPIO 7
• Power the TTP223 with 3.3V and GND

Configuration (in src/config/user_config.h):

#define TOUCH_BUTTON_ENABLED 1      // 1 = enabled, 0 = disabled
#define TOUCH_BUTTON_PIN 7          // GPIO pin (default: 7)
#define TOUCH_DEBOUNCE_MS 50       // Debounce delay (default: 100ms)
#define TOUCH_ACTIVE_LEVEL HIGH     // HIGH for TTP223 (active HIGH)

Software Setup

1. ESP32 Firmware

Option A: Pre-built Binary (Easy - No Compilation Needed)

Download the latest release: v1.5.0

Easiest Method - Web Flasher (No Installation Required!):

1. Visit ESP Web Flasher
2. Connect your ESP32-C3 via USB. If it constantly connects/disconnects, hold the BOOT button, connect to USB while still holding it, then release after connecting. Alternatively, hold BOOT, press RESET while holding BOOT, then release both buttons.
3. Click "Connect" and select your port
4. Click "Choose File" and select firmware-vx.x.x.bin
5. Make sure you pick firmware for correct OLED size version! It may initially work but you will get black screen after you reconnect device.
6. Set Flash Address to 0x0
7. Click "Program" and wait ~30 seconds
8. Done!

Alternative Methods:

• Windows: Run flash.bat and follow prompts
• Linux/Mac: Run ./flash.sh and follow prompts
• Manual: esptool.py --chip esp32c3 --port COM3 --baud 460800 write_flash 0x0 firmware-complete.bin

For detailed instructions, see release/v1.1.0/FLASH_INSTRUCTIONS.md

Option B: Build from Source

Prerequisites:

• PlatformIO (or Arduino IDE)

Installation:

1. Clone this repository
2. Open the project in PlatformIO
3. Connect your ESP32 via USB
4. Build and upload:

   pio run --target upload

First-Time WiFi Setup

1. After uploading, the ESP32 will create a WiFi access point
2. Connect to the network: PCMonitor-Setup
3. Open your browser to 192.168.4.1
4. Configure your WiFi credentials
5. The ESP32 will connect and display its IP address on the OLED

Web Configuration Portal

Once connected to WiFi, access the full configuration page:

1. Open a browser and navigate to the ESP32's IP address (shown on OLED) or http://smalloled.local

2. Clock Settings:

   • Idle clock style (Mario, Space Invaders, Arkanoid, Pac-Man, Standard, or Large)
   • Time format (12/24 hour)
   • Date format (DD/MM/YYYY, MM/DD/YYYY, or YYYY-MM-DD)

3. Display Layout:

   • Choose between 5-row (spacious, 13px) or 6-row (compact, 10px) modes
   • Large 2-row and 3-row modes for double-size text
   • Enable progress bars for visual representation
   • Row 6 positions automatically hidden in 5-row mode

4. Timezone:

   • Select your region from ~50 timezone presets
   • Automatic DST transitions (no manual toggle needed)

5. Display Labels:

   • Customize static labels shown on OLED (not metric names)
   • Fan/Pump label (e.g., "PUMP", "FAN", "COOLER")
   • CPU, RAM, GPU, and Disk labels
   • Perfect for personalizing your setup!

6. Configuration:

   • Export configuration to JSON file (backup)
   • Import configuration from JSON file (restore)
   • Reset to factory defaults

2. PC Stats Sender (Python)

Prerequisites

• Python 3.7+
• LibreHardwareMonitor (for hardware sensor monitoring)
• Note: LibreHardwareMonitor 0.9.5+ changed its WMI backend. The Python script automatically detects this and falls back to the REST API. If using 0.9.5+, enable "Options > Remote Web Server > Run" in LibreHardwareMonitor.

Installing Python:

For windows download e.g. this version Check both checkboxes on installation screen (to use admin rights and add python.exe to PATH)

At the end of installation, if asked to remove characters limit for path, agree on it.

Installing LibreHardwareMonitor

1. Download from LibreHardwareMonitor
2. Extract and run LibreHardwareMonitor.exe as Administrator
3. Windows defender may block it from running. This is false/positive, just add it to exception.
4. Check following options. First 4 from the top:

For version 0.9.5 and above check Web server option:

Python Script Setup (v2.0 - New GUI Version!)

The v2.0 script now includes a graphical interface that makes configuration easy - no more editing files manually!

Step 1: Install Python Dependencies

For Windows:

pip install psutil pywin32 wmi pystray pillow

For Linux:

pip install psutil tk
or (if above is not working)
sudo apt install python3-pip -y
sudo apt install python3-tk -y

Step 2: Run the Script for First Time

Windows:

python pc_stats_monitor_v2.py

Linux:

python3 pc_stats_monitor_v2_linux.py

The GUI will automatically open if no configuration exists.

Step 3: Configure in the GUI

The configuration window lets you:

1. Enter ESP32 IP Address - Find this on your OLED display after WiFi setup
2. Set UDP Port (default: 4210) - Leave this unless you changed it
3. Update Interval (default: 3 seconds) - How often to send stats
4. Select Metrics to Monitor:
   • Browse through categories: System, Temperatures, Fans, Loads, Clocks, Power, Network Data, Network Throughput
   • Check the boxes next to sensors you want to monitor
   • You can select up to 20 metrics
   • Current values are shown to help you identify sensors
   • Use the Search box to quickly find specific sensors
5. Custom Labels (optional):
   • Each sensor has a "Label" field
   • Enter a custom name (max 10 characters) to display on ESP32
   • Leave empty to use auto-generated names
6. Click "Save & Start Monitoring" when done

Step 4: Position Metrics on ESP32 Display

After the Python script starts sending data:

1. Open your ESP32's IP address in a web browser
2. Scroll down to the "Metrics from PC" section
3. You'll see all metrics received from your PC
4. Select location of the metric on display and optionally pair it with companion metric. E.g. "CPU: 10% 40C" > shows usage and temperature of CPU.
5. Use progress bars for visual representation (optional)
6. Choose between 5-row (more spacing) or 6-row (compact) display modes

TIP: Start with 1-2 metrics initially and slowly build entire layout.

The display will update in real-time as you arrange metrics!

Step 5: Enable Autostart (Optional)

Windows:

python pc_stats_monitor_v2.py --autostart enable

This will:

• Create a startup entry in Windows
• Run minimized to system tray on boot
• Right-click tray icon to configure or quit

Linux (systemd):

python3 pc_stats_monitor_v2_linux.py --autostart enable

This creates a systemd user service that:

• Starts automatically on boot
• Restarts if it crashes
• Check status: systemctl --user status pc-monitor
• View logs: journalctl --user -u pc-monitor -f

Common Commands

Edit Configuration:

# Windows
python pc_stats_monitor_v2.py --edit

# Linux
python3 pc_stats_monitor_v2_linux.py --edit

Run in Background (Windows only):

python pc_stats_monitor_v2.py --minimized

Disable Autostart:

# Windows
python pc_stats_monitor_v2.py --autostart disable

# Linux
python3 pc_stats_monitor_v2_linux.py --autostart disable

Understanding Display Modes

The firmware supports multiple display layouts:

5-Row Mode (Recommended):

• More spacing (13px between rows)
• Better readability
• Positions 0-9 available
• 11px spacing with centered clock

6-Row Mode (Compact):

• Tighter spacing (10px between rows)
• Fits more metrics
• Positions 0-11 available

Large 2-Row / 3-Row Modes:

• Double-size text for readability at a distance
• Single-column layout
• Best for desk setups where you want a quick glance

You can switch between modes in the ESP32 web interface under "Display Layout Settings".

Legacy Script (Older Versions)

If you're using firmware versions below 1.3.0, use the legacy scripts:

• pc_stats_monitor.py for Windows
• pc_stats_monitor_linux.py for Linux

These require manual configuration by editing the ESP32_IP in the script file.

Usage

Normal Operation

1. ESP32 should be powered and connected to WiFi
2. LibreHardwareMonitor must be running on your PC
3. Python script should be running

The OLED will display:

• PC Online: Real-time stats (CPU, RAM, GPU temp, disk, fan speed)
• PC Offline: Animated clock (choose from 6 styles in the web portal)

Display Modes

When PC is Online (receiving stats):

• Real-time monitoring display with customizable labels
• Shows CPU usage/temp, RAM usage, GPU temp, Disk usage, Fan/Pump speed
• Progress bars for visual representation
• Automatically switches when PC sends data

When PC is Offline (idle mode):

• Mario Clock: Animated pixel Mario that jumps to "hit" digits when time changes
• Space Invaders Clock: Invader/ship shoots lasers to change digits
• Arkanoid Clock: Breakout-style ball physics destroy and rebuild digits
• Pac-Man Clock: Pac-Man eats pellet-based digits
• Standard Clock: Simple centered clock with date and day of week
• Large Clock: Extra-large time display with date

Change clock style anytime via the web portal or touch button!

Customizing Display Labels

Via Web Portal (Recommended):

1. Open ESP32's IP address in browser
2. Go to "Display Labels" section
3. Change labels to match your setup:
   • "PUMP" → "FAN" or "COOLER"
   • Customize CPU, RAM, GPU, Disk labels too
4. Save settings - changes apply immediately!

Customizing Monitored Sensors (v2.0)

With the v2.0 GUI, you can easily select any sensors available on your system:

Available Sensor Categories:

• System Metrics: CPU%, RAM%, Disk usage (using psutil)
• Temperatures: CPU cores, GPU, motherboard, drives
• Fans & Cooling: All detected fan speeds
• Loads: CPU/GPU load percentages
• Clocks: CPU/GPU clock speeds
• Power: Power consumption sensors
• Network Data: Total uploaded/downloaded (in GB)
• Network Throughput: Current upload/download speeds (in KB/s or MB/s)

How to Select Sensors:

1. Make sure LibreHardwareMonitor is running (Windows only)
2. Run python pc_stats_monitor_v2.py --edit
3. Browse through sensor categories
4. Current values are displayed next to each sensor to help you identify them
5. Check boxes for sensors you want to monitor
6. Set custom labels if desired (max 10 characters)
7. Save and start monitoring

Tips:

• The GUI shows live sensor values when you open it
• Use the search box to quickly find specific sensors
• Network metrics automatically distinguish between upload and download
• You can select up to 20 different metrics
• Labels set in Python GUI will override default names on ESP32

Troubleshooting

ESP32 Issues

Display not working

• Check I2C wiring (SDA=GPIO8, SCL=GPIO9)
• Verify I2C address is 0x3C (common for SSD1306)
• For SH1106 (1.3"): change DEFAULT_DISPLAY_TYPE to 1 in user_config.h
• For SSD1309 (2.42"): use DEFAULT_DISPLAY_TYPE 0 (same as 0.96", no change needed)

Can't connect to WiFi portal

• Make sure you're connected to "PCMonitor-Setup" network
• Try accessing 192.168.4.1 in your browser
• Reset WiFi settings via web interface

ESP32 keeps restarting

• Check power supply (use quality USB cable)
• Monitor serial output at 115200 baud for error messages

Python Script Issues (v2.0)

"No configuration found" - GUI won't open

• Make sure you have Tkinter installed (comes with Python on Windows)
• Linux: Install with sudo apt-get install python3-tk
• Check that you're running Python 3.7 or newer

"WMI not found" or hardware sensor errors (Windows)

• Make sure LibreHardwareMonitor is running as Administrator
• Install dependencies: pip install pywin32 wmi
• Check that WMI service is running: services.msc → Windows Management Instrumentation

No sensors showing in GUI (Windows)

• Run LibreHardwareMonitor before starting the Python script
• If using LibreHardwareMonitor 0.9.5+, enable: Options → Remote Web Server → Run
• The script will auto-detect and use the REST API when WMI is unavailable
• Wait a few seconds after launching LibreHardwareMonitor before running Python script

No data on ESP32 display

• Verify ESP32 IP address in Python GUI matches actual IP (shown on OLED)
• Check Windows Firewall isn't blocking UDP port 4210
• Ensure both PC and ESP32 are on the same network
• Open ESP32 web interface and check "Metrics from PC" section at the bottom
• Try running: python pc_stats_monitor_v2.py (not minimized) to see console output

Autostart not working (Windows)

• Make sure pywin32 is installed: pip install pywin32
• Check Windows Startup folder: Press Win + R, type shell:startup
• Look for "PC Monitor.lnk" shortcut
• For system tray mode, install: pip install pystray pillow

Autostart not working (Linux)

• Check service status: systemctl --user status pc-monitor
• View logs: journalctl --user -u pc-monitor -f
• Make sure systemd is available on your system
• Enable lingering (optional): loginctl enable-linger $USER

Network metrics not showing (Linux)

• Network metrics use psutil's net_io_counters()
• Upload/download speeds are calculated from byte deltas
• First reading will always be 0, wait for next update cycle

Custom labels not appearing on ESP32

• Labels are set in Python GUI, not ESP32 web interface
• Run python pc_stats_monitor_v2.py --edit to modify labels
• ESP32 receives the label name from Python script
• Check that Python script successfully connects (see console output)

Technical Details

Communication

• Protocol: UDP
• Port: 4210 (configurable)
• Format: JSON
• Update Rate: 3 seconds (configurable via GUI)
• Max Metrics: 20 (increased from 12 in v1.x)

v2.0 Improvements

• JSON-based configuration stored in monitor_config.json (Windows) or monitor_config_linux.json (Linux)
• Dynamic sensor discovery - automatically detects all available sensors
• REST API fallback - automatic support for LibreHardwareMonitor 0.9.5+ (broken WMI)
• Network metrics calculated in real-time (upload/download speeds)
• 5-row/6-row display modes with optimized spacing (13px vs 10px)
• Export/Import configuration for easy backup and sharing
• Systemd integration (Linux) for proper service management

Libraries Used

ESP32:

• WiFiManager (tzapu)
• Adafruit SSD1306 / Adafruit SH110X
• Adafruit GFX
• ArduinoJson

Python (Windows):

• psutil (system stats & network)
• pywin32/wmi (LibreHardwareMonitor integration)
• tkinter (GUI - included with Python)
• pystray/pillow (system tray - optional)

Python (Linux):

• psutil (system stats, temps, fans, network)
• tkinter (GUI)

File Structure

pc_stats_monitor_v2.py          # Windows version with GUI
pc_stats_monitor_v2_linux.py    # Linux version with GUI
monitor_config.json              # Windows config (auto-generated)
monitor_config_linux.json        # Linux config (auto-generated)
pc_stats_monitor.py              # Legacy Windows script (v1.x)
pc_stats_monitor_linux.py        # Legacy Linux script (v1.x)

Advanced / Optional Features

These features are disabled by default and require recompilation. They are configured in src/config/user_config.h and are intended for advanced users who build from source.

Display Type Selection

Change DEFAULT_DISPLAY_TYPE to match your OLED:

Value	Display	Size	Notes
0	SSD1306	0.96" / 2.42"	Default. Works for both 0.96" SSD1306 and 2.42" SSD1309
1	SH1106	1.3"	132x64 RAM with 2-column offset

SPI Display Interface

By default, displays connect via I2C (2 wires). For faster refresh rates (useful for smooth animations), you can use SPI instead.

#define DISPLAY_INTERFACE 1          // 0 = I2C (default), 1 = SPI

SPI pin assignments (ESP32-C3):

Signal	GPIO	Notes
MOSI (SDA)	6	Data
SCK	4	SPI Clock
CS	5	Chip Select
DC	3	Data/Command
RST	10	Reset (-1 if not connected)

LED PWM Night Light

Drive a filament LED (or any LED) via a 2N2222 transistor on GPIO 1. Controlled via TTP223 touch gestures (medium press toggles, long hold ramps brightness with gamma correction).

#define LED_PWM_ENABLED 1            // 0 = disabled (default), 1 = enabled
#define LED_PWM_PIN 1                // GPIO pin (default: 1)

See the wiring diagram for the transistor circuit.

QR Code WiFi Setup

Show a scannable QR code on the OLED during WiFi AP setup instead of text instructions. Useful for mobile phone setup.

#define QR_SETUP_ENABLED 1           // 0 = text instructions (default), 1 = QR code

BLE WiFi Provisioning (Experimental)

Bluetooth Low Energy setup for the SmallOLED Android app (currently in development). Instead of the WiFi AP portal, the ESP32 advertises as a BLE device. The Android app discovers it, sends WiFi credentials over BLE, and the device connects automatically.

#define BLE_SETUP_ENABLED 1          // 0 = AP mode (default), 1 = BLE provisioning
#define BLE_DEVICE_NAME "SmallOLED"  // BLE advertised name

How it works:

1. On first boot (no saved WiFi), device starts BLE advertising
2. Android app scans and finds "SmallOLED"
3. App sends your home WiFi SSID + password over BLE
4. Device connects to WiFi and saves credentials
5. Subsequent boots connect silently (no BLE needed)
6. If BLE times out (2 min) or fails, falls back to AP mode automatically

Requirements:

• min_spiffs.csv partition table (already set in platformio.ini)
• NimBLE library (already included in platformio.ini)
• Android app (in development, not yet publicly released)

Scheduled Display Dimming

Automatically dim the display during nighttime hours. Configured via the web interface under Display Settings:

• Enable/disable scheduled dimming
• Start/end hours (e.g., 10 PM to 7 AM)
• Dim brightness level (0-255)

OTA Firmware Updates

Upload new firmware wirelessly through the web interface at http://<device-ip>/update. No need to physically connect USB after the initial flash.

License

This project is open source. Feel free to modify and share!

Credits

Created for monitoring PC stats on a small OLED display. Mario animation inspired by classic pixel art.