ESP32 Thermostat

A smart thermostat built on the ESP32 platform featuring environmental sensing, e-paper/LVGL display, deep sleep power management, and multiple connectivity options (WiFi, Bluetooth, Blynk IoT).

Designed to fit inside an existing thermostat housing, this project includes both the firmware and KiCad hardware design files.

Features

• Environmental sensing via Bosch BME680 (temperature, humidity, pressure, air quality)
• Display options: E-paper (GxEPD2) or LVGL-based display
• Deep sleep with RTC memory persistence for battery efficiency
• Task scheduler that survives deep sleep cycles
• Multiple connectivity: WiFi with static IP, Bluetooth LE GATT, Blynk IoT
• Bistable relay control via DRV8837 H-bridge (no continuous power needed)
• Serial CLI for debugging and configuration
• OTA updates support

Project Structure

esp32-thermostat/
├── hardware/                 # KiCad PCB design files
│   ├── thermo_v2_266.kicad_sch    # Schematic
│   ├── thermo_v2_266.kicad_pcb    # PCB layout
│   └── pins.ods                    # Pin mapping spreadsheet
├── software/                 # PlatformIO firmware project
│   ├── src/                  # Implementation files
│   ├── include/              # Header files
│   ├── lib/                  # Libraries (BSEC, LVGL submodule)
│   └── platformio.ini        # Build configuration
└── README.md

Getting Started

Prerequisites

• PlatformIO (VS Code extension or CLI)
• ESP32 development board (tested with LILYGO TTGO T5 V2.66)

Clone and Initialize

git clone https://github.com/your-username/esp32-thermostat.git
cd esp32-thermostat
git submodule update --init --recursive

Configuration

1. Copy the secrets template and fill in your credentials:

cp software/include/secrets.h.example software/include/secrets.h

2. Edit software/include/secrets.h with your WiFi credentials and Blynk tokens.

3. Configure features in software/include/config.h:

// Display type (choose one)
//#define DISPLAY_EPD      // E-paper display
#define DISPLAY_LVGL       // LVGL-based display

// Optional features
#define HAS_SENSOR           // Enable BME680 sensor
#define SENSOR_SAMPLERATE 3  // Sample rate: 3 or 300 seconds
#define COMMANDS             // Extended CLI commands
//#define BLUETOOTH          // Bluetooth LE support
//#define OTA                // WiFi OTA updates
#define BLYNK                // Blynk IoT platform

Build and Upload

cd software
pio run -t upload
pio device monitor

For OTA updates (after initial flash):

pio run -e mhetesp32devkit-ota -t upload

Firmware Architecture

The firmware is organized into namespaces, each handling a specific subsystem:

Core Services

Namespace	File	Description
Power	power.cpp/h	Deep sleep management, battery monitoring, wake source handling
Tasks	tasks.cpp/h	RTC-persistent task scheduler that survives deep sleep
RTC	rtc.cpp/h	Real-time clock and timestamp management
CLI	cli.cpp/h	Serial command interface for debugging
Commands	commands.cpp/h	Extended CLI command set

I/O Subsystems

Namespace	File	Description
Sensor	sensor.cpp/h	BME680 environmental sensor via BSEC library
Display	display.cpp/h	Display abstraction (EPD or LVGL backend)
Input	input.cpp/h	Button handling via AceButton library
Peripherals::LED	peripherals.cpp/h	Status LED control
Peripherals::Thermo	peripherals.cpp/h	Bistable relay control via DRV8837
Pins	pins.cpp/h	GPIO pin definitions and initialization

Network Services

Namespace	File	Description
Wifi	wifi.cpp/h	WiFi with static IP, NTP sync, HTTP client, OTA
Bluetooth	bluetooth.cpp/h	BLE GATT server (Environmental Sensing, Thermostat, Battery services)
_Blynk	blynk.cpp/h	Blynk IoT platform integration

Boot Sequence

First boot:

1. Full initialization of all subsystems
2. Register scheduled tasks
3. Display boot screen
4. Enter main loop

Wake from deep sleep:

1. Minimal initialization (pins, power, RTC, input)
2. Restore task scheduler from RTC memory
3. Run due tasks based on wake source
4. Return to deep sleep

RTC-Persisted State

Variables marked with RTC_DATA_ATTR survive deep sleep:

• Boot count
• Last sensor reading
• BSEC sensor calibration state
• Task schedules and next run times
• Temperature target setpoint
• Heating state

Dependencies

Managed via PlatformIO:

• espressif32 - ESP32 platform
• zinggjm/GxEPD2 - E-paper display driver
• bxparks/AceButton - Button debouncing
• blynkkk/Blynk - IoT platform
• lvgl/lvgl - Graphics library (git submodule)
• BSEC library (Bosch) - BME680 sensor processing

Hardware

The hardware/ directory contains KiCad 8 project files for a custom PCB designed to fit inside an existing thermostat housing. Key components:

• ESP32 module (LILYGO TTGO T5 V2.66 compatible pinout)
• BME680 environmental sensor
• DRV8837 H-bridge for bistable relay control
• Multiple button inputs with pull-up resistors
• Two red leds to illuminate the display indirectly

License

MIT