External FPS Display

A custom-built FPS (Frames Per Second) display system featuring a dot matrix display, powered by ESP32.

Overview

This project implements a real-time FPS counter featuring an attractive dot-matrix display. The system captures frame rate data from the host PC and projects it onto a dedicated dot-matrix module.

Features

• Real-time FPS, GPU load, and temperature monitoring
• Custom dot-matrix display implementation
• Modular hardware design for easy integration
• Optimized for CachyOS gaming performance monitoring
• Low-latency data transmission
• Ideal companion for OLED monitors: Reduces screen burn-in caused by persistent overlays.

Hardware Components

Main Components:

• ESP32 Microcontroller: Handles processing, serial communication, and display control
• MAX7219 4 in 1: 8x8 LED dot matrix for FPS visualization
• TTP223: Capacitive Touch Button

Circuit Details:

Also, you can refer to the tables below for the connections:

Software Architecture

ESP32 Firmware (Arduino):

• Located in fps-esp32/ directory
• Reads FPS data from serial connection
• Controls dot matrix display
• Communicates via Arduino Serial Protocol

FPS Grabber:

• Python-based software running on the host PC
• Captures real-time frame rate from mangoHUD
• Transmits data to ESP32 via serial connection

Running the code

Prerequisites:

• Operating System: Tested and optimized for CachyOS, but works with other Linux distributions with modifications
• Python 3.8+
• Arduino IDE or PlatformIO for firmware flashing and install the following boards and libraries
  • esp32 by Espressif Systems (Board Manager)
  • MD_MAX72XX and MD_Parola by majicDesigns (Library Manager)
• python-pyserial
• MangoHUD
• Gooverlay

Usage Instructions:

1. Connect the ESP32 to your host PC via USB.
2. If this is the first setup, upload the firmware to the ESP32 using Arduino IDE.
3. Open the MangoHUD.conf file on the host PC and add the following configuration lines:
   • autostart_log=1
   • control=mangohud-%p
4. Launch the fps-grabber-final.py script on the host PC.
5. Upon startup, the dot matrix display will show a digital clock.
6. Start your game with MangoHUD enabled.
7. Once running, the display will update to show real-time FPS.
8. Pro Tip: You can instantly hide MangoHud while gaming by pressing Right Shift + F12.

Project Structure

.
├── README.md                 # This file
├── fps-grabber-final.py      # Python FPS grabber
├── circuit-diagram/
│   └── Dot Matrix Wiring Diagram.png
|── fps-esp32/               # ESP32 firmware
|   └── fps-esp32.ino         # Arduino sketch
└── 3D-case-models-print/          # LED Matrix case 3D models
    └── led-matrix-body.stl             # LED Matrix Body
    └── led-matrix-rear-cover.stl    # LED Matrix Rear Cover

Troubleshooting

Common Issues:

1. No display output: Verify the serial connection between the FPS grabber and the ESP32. Also, check whether the device is ttyUSB0 or ttyUSB1, and update the serialOpen function to use the correct port identifier detected by your OS.
2. ESP32 upload fails: Try different baud rate or USB port.

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please ensure all code changes follow the existing style and include appropriate comments.

For more detailed instructions, please visit my blog.