Deskbuddy
ESP32 touchscreen smart desk dashboard — firmware, web UI, and browser installer in one repo.
git clone https://github.com/fernandofatech/Deskbuddy.gitDeskbuddy is a C++ firmware for the ESP32-2432S028R (Cheap Yellow Display) that turns an inexpensive touchscreen board into a desk dashboard showing weather, KP index, notes, news feeds, and Wi-Fi configuration — no extra soldering required.
What it is and why it exists
The ESP32-2432S028R is one of the cheapest colour touchscreen boards available — under US$10 from most suppliers. The problem is that the firmware ecosystem around it is fragmented: the TFT_eSPI library requires manual pin configuration, online examples rarely combine touch, Wi-Fi, and live external data at the same time, and building something usable from scratch takes hours.
Deskbuddy solves that by delivering a complete, opinionated firmware. It boots, connects to Wi-Fi via a captive portal (WiFiManager), fetches data from public APIs — Open-Meteo for weather, sunrise-sunset.org for solar times, NOAA for geomagnetic activity, Quotable for quotes, and Hacker News Algolia for tech headlines — and renders everything across tappable pages.
A local web interface served by the ESP32 itself lets you adjust notes, theme, widgets, location, and brightness without recompiling. The repo also ships a GitHub Actions workflow that compiles the firmware and publishes a Web Serial installer to GitHub Pages, making flashing accessible directly from the browser with no local tooling required.
Key features
arduino_secrets.h.main.User_Setup.h for the CYD — eliminates the most common failure point when using TFT_eSPI with this board.How the system works
Full flow from flashing to live data on the display.
- arduino-cli · build
- Web Serial · Installer
- GitHub Actions · build-and-pages
- GitHub Pages · web/ installer
- Deskbuddy · Firmware (C++)
- WiFiManager · captive portal
- Local Web UI · (browser settings)
- ILI9341 TFT · 240×320
- XPT2046 · Touch
- Open-Meteo · Weather
- sunrise-sunset.org · Solar times
- NOAA · KP Index
- Quotable · Quotes
- HN Algolia · Tech headlines
The most common failure point: User_Setup.h
The TFT_eSPI library uses a global configuration file that lives inside the library folder itself, not in your project. If you compile without replacing that file with this repo's User_Setup.h, the display will stay white. Copy the file before compiling — see step 4 in the installation guide below.
Installation and use
- 1
Clone the repository
Run
git clone https://github.com/fernandofatech/Deskbuddy.gitand change into the project directory. - 2
Configure Wi-Fi credentials
Copy the example file and edit it with your SSID and password:
cp arduino_secrets.example.h arduino_secrets.h. The filearduino_secrets.his in.gitignore— your credentials will not be committed. - 3
Install Arduino libraries
In Arduino IDE or via
arduino-cli, install:TFT_eSPI,ArduinoJson,XPT2046_Touchscreen, andWiFiManager. Also install the ESP32 board package if not already present. - 4
Replace TFT_eSPI's User_Setup.h
Copy this repo's
User_Setup.hinto the installed library folder. On macOS with arduino-cli:cp User_Setup.h ~/Documents/Arduino/libraries/TFT_eSPI/User_Setup.h. This file defines the correct pins for the CYD (ILI9341_2_DRIVER, HSPI, XPT2046 touch pins). - 5
Select the board and compile
In Arduino IDE, select board
ESP32-2432S028R CYD, partition schemeHuge APP (3MB No OTA/1MB SPIFFS), and upload speed115200. Compile and upload to the board via USB. - 6
Configure Wi-Fi on the device
If Wi-Fi is not configured, open the
Setuppage on the display and tap the Wi-Fi card. The device creates an access point namedDeskbuddy Setup. Connect to it from a phone or computer and select your network. - 7
Find the IP and open the web interface
Open the serial monitor at 115200 baud to see boot logs and the assigned IP address. Navigate to that IP in a browser to adjust notes, theme, widgets, location, timers, and brightness without recompiling.
# 1. Clone
git clone https://github.com/fernandofatech/Deskbuddy.git
cd Deskbuddy
# 2. Credenciais Wi-Fi
cp arduino_secrets.example.h arduino_secrets.h
# Edite arduino_secrets.h com seu SSID e senha
# 3. Instale o pacote de placas ESP32 e as bibliotecas
arduino-cli core install esp32:esp32
arduino-cli lib install "TFT_eSPI" "ArduinoJson" "XPT2046_Touchscreen" "WiFiManager"
# 4. Substitua o User_Setup.h da TFT_eSPI (OBRIGATÓRIO)
cp User_Setup.h ~/Documents/Arduino/libraries/TFT_eSPI/User_Setup.h
# 5. Compile
arduino-cli compile \
--fqbn esp32:esp32:esp32 \
--build-property "build.partitions=huge_app" \
.
# 6. Upload (ajuste a porta conforme seu sistema, ex: /dev/cu.usbserial-*)
arduino-cli upload \
--fqbn esp32:esp32:esp32 \
--port /dev/cu.usbserial-0001 \
.
# 7. Monitor serial para ver o IP atribuído
arduino-cli monitor --port /dev/cu.usbserial-0001 --config baudrate=115200CI, GitHub Pages, and the Web Serial installer
The workflow .github/workflows/build-and-pages.yml does two things on every push to main: it compiles the firmware with arduino-cli and publishes the contents of the web/ folder to GitHub Pages. The result is a browser-accessible Web Serial installer that flashes the binary directly to the board over USB — no Arduino IDE install, no extra drivers on Windows (beyond what Chrome/Edge already include).
The generated binary is saved to firmware/deskbuddy-esp32-2432s028r-cyd.bin. The web installer reads that file and uses the Web Serial API to perform the flash. This makes firmware distribution considerably simpler: anyone with the board and a USB cable can flash the latest version by opening a URL.
For those who want to modify the firmware and distribute their own build, forking and adjusting the code is enough — CI handles the rest, compiling and publishing automatically. There are no build secrets beyond arduino_secrets.h, which is local and Git-ignored.
Frequently asked questions
The display stays white after upload. What do I do?
Almost certainly the TFT_eSPI library's User_Setup.h was not replaced. Copy this repo's file into the installed library folder and recompile.
Does it work on other ESP32 display boards?
The firmware has been tested specifically on the ESP32-2432S028R (CYD). Other boards with ILI9341 may work but will require pin adjustments in User_Setup.h and possibly in the touch code.
Do the external APIs require a key?
No. Open-Meteo, sunrise-sunset.org, NOAA KP, Quotable, and Hacker News Algolia are all public and unauthenticated at the endpoints Deskbuddy uses.
How do I update the firmware without reconnecting USB?
OTA is not enabled in this fork (the Huge APP partition scheme trades the OTA partition for more firmware space). The Web Serial installer via GitHub Pages is the most practical path for re-flashing.
Who this project is for
Deskbuddy is a well-scoped hardware/firmware project: it solves a concrete problem (turning a cheap board into something usable) with a fixed set of dependencies and keyless APIs. If you have an ESP32-2432S028R sitting in a drawer or want a functional desk dashboard without assembling a stack from scratch, this repo delivers exactly that — compilable firmware, already-solved pin configuration, Wi-Fi portal, local web interface, and CI with a browser-based installer. It is not an extensible framework or a library; it is an opinionated firmware product for specific hardware. Anyone wanting to adapt it for another board or add widgets will need to work in the C++ code, but the structure is clear enough to make that tractable.