ESP32 Framework

A shared Arduino/ESP32 C++ framework library plus three production applications built on top of it. The framework provides an IoC module host, hardware abstractions, reusable services (WiFi, HTTP, display, sensors, relays, RTC, NTP), a GUI system for SSD1306 OLED, a state machine base, NVS persistence helpers, and logging. Apps compose framework services into a typed context and drive application behavior through a state machine — the framework knows nothing about any specific app.

---

Apps

App	Board	Description
smartsprouter	ESP32 WROOM 32 (upesy_wroom)	Plant growth chamber controller — SSD1306 OLED, rotary encoder + button, 6 relays, DHT11 sensor, DS3231 RTC
hydrofert	Seeed XIAO ESP32-C6 (seeed_xiao_esp32c6)	Hydroponics fertilizer scheduler — 2 relay pumps, DS3231 RTC, web UI
anothermenora	Seeed XIAO ESP32-C6 (seeed_xiao_esp32c6)	Hanukkah menorah controller — 9 LED outputs, NTP time sync, Hebcal API, web UI

---

Environment Setup

Starting from a fresh Windows machine:

1. Install Visual Studio Code
2. In VSCode, install the PlatformIO IDE extension (search "PlatformIO" in the Extensions panel)
3. Install the C/C++ Extension Pack from Microsoft — provides IntelliSense and ALT+SHIFT+F auto-formatting
4. Install the CH340 USB-UART driver (required for flashing on most ESP32 dev boards): Resources/Software/Windows-CH340-Driver.zip — extract and run the installer
5. Open the workspace file in VSCode: Software/PlatformIO/app/esp32-framework.code-workspace

---

Quick Start — Build & Flash

Interactive tool (recommended):

.\Software\PlatformIO\app\tools\pio-app.ps1

Presents menus for selecting the app, serial port, and action (build / flash / monitor / erase).

Or directly from the app directory:

cd Software/PlatformIO/app/apps/<app>
platformio run --target upload --upload-port COM<N>

Serial monitor baud rate: 115200

---

Repo Layout

Folder	Contents
Hardware/	Component datasheets and pinout references for all hardware used across apps
Documents/	Design documents and test logs (per app, in subdirectories)
Resources/	Branding assets, driver installers
Software/PlatformIO/app/	Framework library + all apps — the main codebase
Software/Python/	Developer utility scripts (crash decoder, bitmap generator)

Full framework developer guide: Software/PlatformIO/app/docs/esp32-framework-guide.md

---

Developer Tools

Tool	Location	Purpose
pio-app.ps1	Software/PlatformIO/app/tools/	Interactive build / flash / monitor / erase menu
BacktraceResolver.py	Software/Python/BacktraceResolver/	GUI for decoding ESP32 panic stack traces to source lines
GenerateBitmapFromMonochromeImage.py	Software/Python/GenerateBitmap/	Converts an image to a uint8_t C bitmap header (Adafruit GFX)

---

VSCode Tips

• Vertical column selection: Alt+Shift+ mouse drag
• Auto-format C++ file: Alt+Shift+F
• Formatting config lives in Software/PlatformIO/app/.editorconfig (regenerate: Ctrl+Shift+P → "C/C++: Generate EditorConfig")
• State machine reference links: draw.io UML · StateSmith fundamentals