Firmware for an ESP32-C3 with a 1.54″ e-paper screen that sits on a
Proxmox host's USB port and shows how the host is doing: CPU, memory,
network, which VMs and containers run, and which disks are spinning. It
asks the host for the numbers over USB; the host side is
ThinkLab-Host (hl-hostmon).
A Dallas sensor adds the case temperature, and a small web page shows the
same and lets you switch pages, drive the case fan and upload new firmware.
| Status | Network | VMs / LXCs | Disks | Debug | No host data |
|---|---|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Pictures rendered on a PC from the page code with made-up data (how).
- Five pages: Status (IP, CPU, RAM, case temperature, both fans, uptime, link), Network (rates, Wi-Fi), VMs/LXCs (running/total, running guests first), Disks (active or asleep), Debug
- Always current: asks the host every minute and redraws the page with each answer, with partial refresh (no flash); a black ! in the header when the host hasn't answered for three minutes
- Touch or auto: one tap refreshes, a second tap within 20 s turns the page, a long press switches to automatic rotation; double tap opens Debug
- No network needed for the screen: data comes over USB from the host; Wi-Fi is only for the web page and updates
- Robust link: brace-framed JSON reader that ignores the board's own log lines; Online/Timeout on the Status page when the host stops answering
- Web page: status, page and mode buttons, fan control (25 %, 50 %,
auto), reboot, firmware upload,
status.json; behind a login - Case fan: 4-pin PWM on a temperature curve from the Dallas sensor, with a start kick, smoothing, on/off hysteresis and a safe speed if the sensor fails; both fans' speeds measured exactly, and a stalled fan is kicked again (and the minimum duty raised if it keeps stalling); tachometer inputs for two fans; manual 25 %/50 % from the web page ends by itself after an hour or at 50 °C
- Safe updates: a new build is kept only once it gets Wi-Fi, otherwise the board goes back to the previous one by itself
- Home Assistant: its own integration, installed through HACS (below)
The web page with made-up values.
| Part | Notes |
|---|---|
| ESP32-C3 board with native USB | e.g. ESP32-C3 SuperMini or DevKitM-1; the ESP32-S3 works similarly |
| 1.54″ e-paper, SSD1681, 200×200 | GxEPD2 model GxEPD2_154_D67 |
| Touch button | TTP223 or any push button |
| DS18B20 | case temperature, 4.7 kΩ pull-up |
| 4-pin PC fan (optional) | PWM through a transistor (open collector), tach with pull-up |
| Signal | GPIO |
|---|---|
| E-paper CS / DC / RST / BUSY | 7 / 1 / 2 / 3 (SPI on the board's default pins) |
| Touch | 10 (active high; TOUCH_ACTIVE_LOW to flip) |
| DS18B20 (1-Wire) | 8 |
| Fan 1 PWM / tach | 9 / 5 |
| Fan 2 tach | 0 |
-
Install the host service on the Proxmox host: ThinkLab-Host.
-
Build and flash the firmware with PlatformIO:
cp secrets.ini.example secrets.ini # Wi-Fi, host name, web login, OTA address pio run -e esp32c3-usb -t upload # over USB
-
Plug the board into the host. It sends
INFOonce and thenGETevery minute; the page redraws with each answer.
secrets.ini key |
Used for |
|---|---|
WIFI_SSID, WIFI_PASS |
Wi-Fi |
HOSTNAME |
Wi-Fi/mDNS name |
WEB_USER, WEB_PASS |
web page login; WEB_PASS is also the ArduinoOTA password |
ota_host, ota_pass |
the esp32c3-ota environment (pio run -e esp32c3-ota -t upload) |
Updating later: build and upload .pio/build/esp32c3-usb/firmware.bin
on the web page under Firmware → Upload (or curl -u user:pass -F update=@firmware.bin http://<board>/update), or pio run -e esp32c3-ota -t upload from a machine on the same network (ArduinoOTA connects back to the
sender, so not through a NAT or VPN gateway). A new build that doesn't get
Wi-Fi within 5 minutes is undone by the bootloader. Use a password of your
own: anyone who knows it can flash the board.
Use the integration ThinkLab Display (HACS custom repository): it finds the board on the network and adds one device with case temperature, fan duty and speed, fan mode and duty controls, the host link, and buttons for the screen and a restart. Needs firmware 0.3.2 or later.
Compile-time settings live in platformio.ini (build_flags), with
defaults in src/config.h:
| Setting | Default | Meaning |
|---|---|---|
POLL_INTERVAL_MS |
60000 | how often to ask the host |
STALE_AFTER_S |
3 polls | after this long without an answer every page shows "!" |
FULL_REFRESH_EVERY |
20 | a full e-paper refresh every N redraws, partial ones in between |
OTA_VERIFY_TIMEOUT_MS |
300000 | a new build must get Wi-Fi within this time or is rolled back |
FAN_MANUAL_MAX_MS, FAN_MANUAL_OVERRIDE_C |
1 h, 50 °C | manual fan duty ends after this long or at this temperature |
LINK_TIMEOUT_S |
600 | Status shows Timeout after this long without an answer |
RX_LINEBUF_BYTES |
12288 | largest answer the reader takes |
JSON_DOC_BYTES |
24576 | ArduinoJson memory for one answer (needs about 1.5× the answer's size) |
USE_WIFI, USE_DALLAS, USE_FAN1, USE_FAN2_TACH, USE_FANCTRL |
on | compile features in or out |
FC_PT1_C … FC_PT5_P |
see platformio.ini |
fan curve: five points of °C → duty % |
DEBUG_IN_ROTATION |
0 | Debug page in the normal rotation |
The board writes GET and a newline; the host answers with one line of
JSON (the full format is in
ThinkLab-Host's README).
The fields the pages use:
{
"schema_version": 1,
"uptime_s": 795600,
"cpu": {"percent": 23.7, "load1": 1.56},
"ram": {"total_bytes": 17179869184, "used_bytes": 7730941132},
"proxmox": {"vm_running": 1, "vm_total": 2, "lxc_running": 7, "lxc_total": 9,
"vms": [{"id": 100, "name": "homeassistant", "status": "running"}],
"lxcs": [{"id": 101, "name": "dns", "status": "running"}]},
"disks": [{"name": "nvme0n1", "state": "active"}, {"name": "sdb", "state": "standby"}],
"ip": {"primary_ipv4": "192.168.1.10/24", "ip_status": "ok"},
"net": {"total_rx_bps": 1364680, "total_tx_bps": 977456}
}Answers with another schema_version, or with an error field, are
ignored. The board keeps up to six guests of each kind, running ones first;
the VMs/LXCs page shows three VMs and four containers and counts the rest
as "+N more".
| Path | What |
|---|---|
src/main.cpp |
set-up, loop, touch handling, page switching |
src/serial_client.* |
the USB link: polling, framing, JSON parsing into HostState |
src/pages/ |
one file per e-paper page |
src/ui_theme.*, src/display_manager.* |
header, alignment and Wi-Fi icon helpers; page registry |
src/modules/ |
Wi-Fi/OTA, web page, Dallas sensor, fan PWM, tach and control |
tools/render/ |
renders the pages on a PC (below) |
docs/screenshots/ |
the pictures in this README |
pio run -e esp32c3-usb # build (needs a secrets.ini; the example works)
pio device monitor # the board's own log, while no host service holds the portThe GitHub checks build the firmware with the example secrets and render the pages.
tools/fansim/build.sh compiles src/modules/fanctrl.cpp with the curve and
fan settings from platformio.ini and runs it through a scripted day (boot
without sensor, cool night, warm-up, the 32 °C edge, sensor lost), printing
the duty, time on, switches and start kicks for each phase. Run it after any
change to the controller.
tools/render/build.sh compiles the page code for the PC against small
stand-ins for Arduino, WiFi and GxEPD2 plus the real Adafruit GFX library,
draws every page with made-up data (tools/render/render.cpp) and writes
docs/screenshots/eink-*.png. Needs g++, git and ImageMagick. Run it
after every visible change to a page.
tools/render/web-screenshot.js takes the web page from a running board
(one GET, with THINKLAB_WEB_USER/THINKLAB_WEB_PASS), replaces every
real value with demo data, answers the page's API calls itself and saves
docs/screenshots/web.png (Node with Playwright; CHROMIUM_PATH to use an
installed browser).
See CHANGELOG.md for what changed.
GPL-3.0 (LICENSE); the libraries keep their own licences (THIRD_PARTY_NOTICES.md).






