https://github.com/error311/Unraid-ePaper-Server-Monitor/
 

Just wanted to share my project with you all. I built a custom esp32 dev board and got a ePaper display.. Wanted to do something with the ePaper display so here is the outcome of that lol. I've named it "Unraid ePaper Server Monitor" because it requires unraid of course and bash script that runs every 20 minutes. I am not affiliated with UNRAID and this is an unofficial project.

This project is a custom Unraid monitoring solution that uses an ESP32 paired with a 2.9″ ePaper display to present real‑time server metrics. It leverages a bash script (run as a Unraid User Script) to gather system information and Docker/VM stats, formats the data into a JSON file, and then the ESP32 fetches and displays the data.

Battery life I have not got a full discharge yet but based on my amp reading without using the button (monitor only) should last 6-10 weeks on single charge.

Here was my original project that just used ping library to show status:
https://github.com/error311/esp32-epaper-server-monitor

 

Plans for future updates
Start & Stop docker containers

• HTTP endpoint in apache-php
• Mount the Docker Socket or SSH to the Host

 

Key Features

Unraid System Metrics

• CPU Load: Extracted from uptime
• CPU Model: Retrieved from /proc/cpuinfo
• Memory Usage: Total, used, and free (in MB)
• Disk Free Space: Obtained from df -h

 

Docker Container Stats

Monitors the following containers:

• Jellyfin
• Jellyseerr
• GluetunVPN
• immich

For each container, the script displays:

• Online status (using docker ps)
• CPU usage, memory usage/limit, and IP address (via docker stats and docker inspect)
• Disk information: total disk size, used space, and free space (using df -h)

Virtual Machine Stats

Uses virsh to gather details for VMs including:

• Name, state, CPU cores, and maximum memory (in MB)
• Autostart settings
• IP address (using the guest agent)

 

JSON Output

All collected metrics are aggregated into a JSON file (saved to /mnt/user/appdata/Apache-PHP/www/firmware/status.json), which the ESP32 uses for display updates.

 

Hardware & Power Management

ESP32 & ePaper Display

• Driven by the Waveshare ePaper libraries (DEV_Config.h, EPD.h, GUI_Paint.h)
• Uses partial refreshes for efficient display updates

Power Supply

• Powered by a TPS63070 buck‑boost regulator that converts battery voltage to a clean 3.3V
• Uses a 4.2V, 1100mAh battery charged via a TP5100 module
• A push button connected to GPIO39 (with a 10kΩ resistor to ground) wakes the ESP32 from deep sleep

Battery Monitoring Voltage

• 27kΩ resistor from battery voltage & 100kΩ resistor from ground. These are connected to GIO33.

OTA Updates

• The ESP32 checks for firmware updates via HTTP and uses the Update library for over‑the‑air (OTA) updates

 

Software Libraries & Tools

ESP32 Libraries

• WiFi & HTTPClient: For network connectivity
• ArduinoJson: For parsing the JSON status file
• Update: For OTA firmware updates

Bash Script Tools

• Standard Linux utilities: uptime, free, df, grep, awk, etc.
• Docker commands: docker stats and docker inspect for container monitoring
• virsh for Virtual Machine statistics

 

How It Works

1. Data Collection: A bash script (run as a Unraid User Script) collects Unraid system metrics, Docker container stats (including disk size, used, and free space), and VM information, then formats all of the data into a JSON file.
2. Display Update: The ESP32 downloads and parses the JSON file using ArduinoJson, and updates the ePaper display with formatted text and graphical progress bars.
3. Low-Power Operation: The ESP32 is designed for low-power consumption. It uses deep sleep and can be awakened via a push button (GPIO39), ensuring efficient operation.

 

Repository Structure

• ESP32 Firmware:
  Contains the code for the ESP32, which handles fetching, parsing, and displaying the JSON data.
• Bash Script (json_script.sh):
  Collects and formats system, Docker, and VM metrics into a JSON file.

 

Branching Strategy

Due to significant differences between the original ping-based monitor and this new JSON-based Unraid monitoring version (which removes some libraries and functionality), this version is maintained in a separate repository. This clear separation ensures that users can easily choose the version that best fits their needs.

 

License

This project is licensed under the MIT License.

Edited March 31, 20251 yr by error311
TPS63070

20 hours ago, error311 said:

Powered by a TPS3070 buck‑boost regulator

Did you happen to mean tps63070? I couldn't find a reference to your number.

1 hour ago, JonathanM said:

Did you happen to mean tps63070? I couldn't find a reference to your number.

Yes sorry it is a TPS63070. I will update that, thank you.

Hello. I was just thinking of e-ink and how it may be useful for this purpose. You nailed it. My question is, how is it pulling data from Unraid? Wi-fi? Bluetooth? Preferably wireless.

On 2/1/2026 at 9:31 PM, jang430 said:

Hello. I was just thinking of e-ink and how it may be useful for this purpose. You nailed it. My question is, how is it pulling data from Unraid? Wi-fi? Bluetooth? Preferably wireless.

Hey @jang430 thanks was a fun project. It's using the ESP32 WiFi & HTTPClient libraries.

How It Works

1. Data Collection: A bash script (run as a Unraid User Script) collects Unraid system metrics, Docker container stats (including disk size, used, and free space), and VM information, then formats all of the data into a JSON file.

2. Display Update: The ESP32 downloads and parses the JSON file using ArduinoJson, and updates the ePaper display with formatted text and graphical progress bars.

3. Low-Power Operation: The ESP32 is designed for low-power consumption. It uses deep sleep and can be awakened via a push button (GPIO39), ensuring efficient operation.

Thanks @error311 Sorry, forgot to reply. I really like what you've done. I'll see if I can replicate it. Thanks.