# Deskbuddy Painel inteligente para mesa com ESP32 e touchscreen — firmware, web e instalador em um só repo. - URL: https://fernando.moretes.com/open-source/Deskbuddy - Markdown: https://fernando.moretes.com/open-source/Deskbuddy/guide.md?lang=pt - 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 é um firmware C++ para o ESP32-2432S028R (Cheap Yellow Display) que transforma uma placa de touchscreen barata em um painel de mesa com clima, índice KP, notas, feeds de notícias e configuração por Wi-Fi — tudo sem solda extra. ## O que é e por que existe O ESP32-2432S028R é uma das placas mais baratas com display colorido e toque disponíveis no mercado — menos de US$ 10 na maioria dos fornecedores. O problema é que o ecossistema de firmware para ela é fragmentado: a biblioteca `TFT_eSPI` exige configuração manual de pinos, os exemplos online raramente combinam toque, Wi-Fi e dados externos ao mesmo tempo, e montar algo utilizável do zero leva horas. Deskbuddy resolve isso entregando um firmware completo e opinativo. Ele inicializa, conecta ao Wi-Fi via portal captivo (WiFiManager), busca dados de APIs públicas — Open-Meteo para clima, sunrise-sunset.org para horários solares, NOAA para atividade geomagnética, Quotable para frases e Hacker News Algolia para manchetes de tecnologia — e renderiza tudo em páginas tocáveis. A interface web local (servida pelo próprio ESP32) permite ajustar notas, tema, widgets, localização e brilho sem recompilar. O repositório também inclui um workflow de GitHub Actions que compila o firmware e publica um instalador Web Serial no GitHub Pages, tornando o flash acessível diretamente pelo navegador sem instalar nenhuma ferramenta. ## Funcionalidades principais - Páginas tocáveis: Home, Clima, Notas, Status e Configuração — navegação por toque no ILI9341 via XPT2046. - Dados ao vivo de cinco APIs públicas sem chave: Open-Meteo, sunrise-sunset.org, NOAA KP, Quotable e Hacker News Algolia. - Portal Wi-Fi captivo via WiFiManager — sem credenciais hardcoded; SSID e senha ficam em `arduino_secrets.h` ignorado pelo Git. - Interface web local servida pelo ESP32 para ajuste de notas, tema, widgets, localização, timers e brilho. - CI com GitHub Actions: compila o firmware com arduino-cli e publica instalador Web Serial no GitHub Pages a cada push na `main`. - `User_Setup.h` pré-configurado para o CYD — elimina a etapa mais comum de falha ao usar TFT_eSPI com essa placa. ## Como o sistema funciona Fluxo completo desde o flash até os dados ao vivo no 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) ### Fluxos - arduino_cli -> gh_actions: compila - gh_actions -> gh_pages: publica bin - gh_pages -> web_serial: serve instalador - web_serial -> esp32_fw: flash USB - esp32_fw -> wifi_mgr: sem Wi-Fi → portal - esp32_fw -> web_ui: serve UI local - esp32_fw -> open_meteo: HTTP GET - esp32_fw -> sunrise: HTTP GET - esp32_fw -> noaa: HTTP GET - esp32_fw -> quotable: HTTP GET (opcional) - esp32_fw -> hn: HTTP GET (opcional) - esp32_fw -> tft: SPI render - touch -> esp32_fw: eventos de toque > **O passo mais comum de falha: User_Setup.h:** A biblioteca `TFT_eSPI` usa um arquivo de configuração global que fica dentro da pasta da própria biblioteca, não no projeto. Se você compilar sem substituir esse arquivo pelo `User_Setup.h` deste repositório, o display ficará branco. Copie o arquivo antes de compilar — veja o passo 4 do guia de instalação abaixo. ## Instalação e uso 1. **Clone o repositório** — Execute `git clone https://github.com/fernandofatech/Deskbuddy.git` e entre na pasta do projeto. 2. **Configure as credenciais Wi-Fi** — Copie o arquivo de exemplo e edite com seu SSID e senha: `cp arduino_secrets.example.h arduino_secrets.h`. O arquivo `arduino_secrets.h` está no `.gitignore` — suas credenciais não serão commitadas. 3. **Instale as bibliotecas Arduino** — No Arduino IDE ou via `arduino-cli`, instale: `TFT_eSPI`, `ArduinoJson`, `XPT2046_Touchscreen` e `WiFiManager`. Instale também o pacote de placas ESP32 se ainda não tiver. 4. **Substitua o User_Setup.h da TFT_eSPI** — Copie o `User_Setup.h` deste repositório para dentro da pasta da biblioteca instalada. No macOS com arduino-cli: `cp User_Setup.h ~/Documents/Arduino/libraries/TFT_eSPI/User_Setup.h`. Esse arquivo define os pinos corretos para o CYD (ILI9341_2_DRIVER, HSPI, pinos de toque XPT2046). 5. **Selecione a placa e compile** — No Arduino IDE, selecione a placa `ESP32-2432S028R CYD`, partition scheme `Huge APP (3MB No OTA/1MB SPIFFS)` e velocidade de upload `115200`. Compile e faça o upload para a placa via USB. 6. **Configure o Wi-Fi no dispositivo** — Se o Wi-Fi não estiver configurado, abra a página `Setup` no display e toque no card Wi-Fi. O dispositivo cria um access point chamado `Deskbuddy Setup`. Conecte-se a ele pelo celular ou computador e escolha a rede desejada. 7. **Encontre o IP e acesse a interface web** — Abra o monitor serial a 115200 baud para ver os logs de boot e o endereço IP atribuído. Acesse esse IP no navegador para ajustar notas, tema, widgets, localização, timers e brilho sem recompilar. _Fluxo completo 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 e o instalador Web Serial O workflow `.github/workflows/build-and-pages.yml` faz duas coisas a cada push na branch `main`: compila o firmware com `arduino-cli` e publica o conteúdo da pasta `web/` no GitHub Pages. O resultado é um instalador Web Serial acessível pelo navegador que grava o binário diretamente na placa via USB — sem instalar Arduino IDE, sem drivers adicionais no Windows (exceto o já incluído no Chrome/Edge). O binário gerado é salvo em `firmware/deskbuddy-esp32-2432s028r-cyd.bin`. O instalador web lê esse arquivo e usa a Web Serial API para fazer o flash. Isso torna a distribuição do firmware consideravelmente mais simples: qualquer pessoa com a placa e um cabo USB pode flashar a versão mais recente abrindo uma URL. Para quem quiser modificar o firmware e distribuir a própria versão, basta fazer um fork, ajustar o código, e o CI cuida do resto — compila e publica automaticamente. Não há segredos de build além do `arduino_secrets.h`, que é local e ignorado pelo Git. ## Perguntas frequentes ### O display fica branco após o upload. O que fazer? Quase certamente o `User_Setup.h` da biblioteca `TFT_eSPI` não foi substituído. Copie o arquivo deste repositório para a pasta da biblioteca instalada e recompile. ### Funciona em outras placas ESP32 com display? O firmware foi testado especificamente no ESP32-2432S028R (CYD). Outras placas com ILI9341 podem funcionar, mas exigirão ajustes nos pinos dentro do `User_Setup.h` e possivelmente no código de toque. ### As APIs externas exigem chave? Não. Open-Meteo, sunrise-sunset.org, NOAA KP, Quotable e Hacker News Algolia são todas públicas e sem autenticação nos endpoints usados pelo Deskbuddy. ### Como atualizo o firmware sem reconectar o USB? OTA não está habilitado neste fork (o partition scheme `Huge APP` sacrifica a partição OTA para dar mais espaço ao firmware). O instalador Web Serial via GitHub Pages é o caminho mais prático para re-flash. ## Para quem é este projeto Deskbuddy é um projeto de hardware/firmware bem delimitado: resolve um problema concreto (transformar uma placa barata em algo utilizável) com um conjunto fixo de dependências e APIs sem chave. Se você tem um ESP32-2432S028R na gaveta ou quer um painel de mesa funcional sem montar um stack do zero, este repositório entrega exatamente isso — firmware compilável, configuração de pinos já resolvida, portal Wi-Fi, interface web local e CI com instalador no navegador. Não é um framework extensível nem uma biblioteca; é um produto de firmware opinativo para hardware específico. Quem quiser adaptar para outra placa ou adicionar widgets precisará entrar no código C++, mas a estrutura é clara o suficiente para isso. ## Referências - [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)