# Deskbuddy

ESP32 touchscreen smart desk dashboard — firmware, web UI, and browser installer in one repo.

- URL: https://fernando.moretes.com/open-source/Deskbuddy

- Markdown: https://fernando.moretes.com/open-source/Deskbuddy/guide.md?lang=en

- GitHub: https://github.com/fernandofatech/Deskbuddy

- Homepage: https://fernando.moretes.com

- Language: C++

- Topics: fork, moretes, portfolio

- Stars: 1

- Forks: 0

- Updated: 2026-05-16T01:21:12Z

---

Deskbuddy 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

- Touch pages: Home, Weather, Notes, Status, and Setup — tap navigation on the ILI9341 via XPT2046.
- Live data from five keyless public APIs: Open-Meteo, sunrise-sunset.org, NOAA KP, Quotable, and Hacker News Algolia.
- Captive-portal Wi-Fi onboarding via WiFiManager — no hardcoded credentials; SSID and password live in a Git-ignored `arduino_secrets.h`.
- Local web interface served by the ESP32 for adjusting notes, theme, widgets, location, timers, and brightness.
- GitHub Actions CI: compiles firmware with arduino-cli and publishes a Web Serial installer to GitHub Pages on every push to `main`.
- Pre-configured `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.

### 💻 Dev Machine

- arduino-cli build (ci)
- Web Serial Installer (frontend)

### ☁️ CI / GitHub

- GitHub Actions build-and-pages (ci)
- GitHub Pages web/ installer (frontend)

### 📟 ESP32 Device

- Deskbuddy Firmware (C++) (compute)
- WiFiManager captive portal (network)
- Local Web UI (browser settings) (frontend)
- ILI9341 TFT 240×320 (edge)
- XPT2046 Touch (edge)

### 🌐 External APIs

- Open-Meteo Weather (external)
- sunrise-sunset.org Solar times (external)
- NOAA KP Index (external)
- Quotable Quotes (external)
- HN Algolia Tech headlines (external)

### Flows

- arduino_cli -> gh_actions: compiles
- gh_actions -> gh_pages: publishes bin
- gh_pages -> web_serial: serves installer
- web_serial -> esp32_fw: USB flash
- esp32_fw -> wifi_mgr: no Wi-Fi → portal
- esp32_fw -> web_ui: serves local UI
- esp32_fw -> open_meteo: HTTP GET
- esp32_fw -> sunrise: HTTP GET
- esp32_fw -> noaa: HTTP GET
- esp32_fw -> quotable: HTTP GET (optional)
- esp32_fw -> hn: HTTP GET (optional)
- esp32_fw -> tft: SPI render
- touch -> esp32_fw: touch events

> **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.git` and 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 file `arduino_secrets.h` is 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`, and `WiFiManager`. Also install the ESP32 board package if not already present.

4. **Replace TFT_eSPI's User_Setup.h** — Copy this repo's `User_Setup.h` into 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 scheme `Huge APP (3MB No OTA/1MB SPIFFS)`, and upload speed `115200`. Compile and upload to the board via USB.

6. **Configure Wi-Fi on the device** — If Wi-Fi is not configured, open the `Setup` page on the display and tap the Wi-Fi card. The device creates an access point named `Deskbuddy 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.

_Full flow via arduino-cli (macOS/Linux)_

```bash
# 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=115200
```

## CI, 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.

## References

- [fernandofatech/Deskbuddy — GitHub](https://github.com/fernandofatech/Deskbuddy)
- [Live installer — fernando.moretes.com](https://fernando.moretes.com)
- [TFT_eSPI library — Bodmer/TFT_eSPI](https://github.com/Bodmer/TFT_eSPI)
- [WiFiManager — tzapu/WiFiManager](https://github.com/tzapu/WiFiManager)
- [Open-Meteo — Free Weather API](https://open-meteo.com)
- [NOAA KP Index — Space Weather](https://www.swpc.noaa.gov)
- [Hacker News Algolia API](https://hn.algolia.com/api)

## Links

- [GitHub repository](https://github.com/fernandofatech/Deskbuddy)
- [Homepage](https://fernando.moretes.com)