Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/will-white/hvac-controller

Locally hosted "smart" HVAC controller
https://github.com/will-white/hvac-controller

Last synced: 10 months ago
JSON representation

Locally hosted "smart" HVAC controller

Awesome Lists containing this project

README 

          
# ESP32-C6 Smart HVAC Thermostat



This project is a feature-rich, single-zone HVAC thermostat built on the ESP32-C6 microcontroller. It is designed to be a robust and intelligent replacement for standard programmable thermostats, incorporating advanced safety, efficiency, and learning features typically found in high-end commercial products. All logic is processed locally on the device, ensuring privacy and offline functionality.



## Key Features



### Core Control

* **7-Day Programmable Schedule**: Independent schedules for weekdays and weekends with up to 10 custom periods per day (e.g., Wake, Away, Home, Sleep).

* **Multi-Mode Operation**: Supports Heating, Cooling, Auto-Changeover, and Fan-Only modes.

* **Fan Control**: Includes `AUTO` (runs with system), `ON` (always on), and `CIRCULATE` (runs periodically for a set time, e.g., 15 minutes every hour).

* **Unit Selection**: Supports both Fahrenheit and Celsius for all temperature settings and readouts.



### Efficiency & Smart Features

* **Economizer (Free Cooling/Heating)**: Automatically uses the fresh air intake instead of the furnace or A/C when outdoor temperature is favorable, significantly reducing energy consumption.

* **Time to Temperature (Smart Recovery)**: Proactively learns the thermal performance of your home and starts heating or cooling *before* a scheduled change to reach the target temperature precisely *at* the scheduled time.

* **Seasonal Performance Learning**: The smart recovery feature learns and stores separate performance data for all four seasons, allowing it to make more accurate predictions as outdoor conditions change throughout the year.

* **Local Learning Framework**: A system for logging manual user adjustments to the onboard filesystem (SPIFFS/LittleFS), enabling future implementation of algorithms that can automatically adjust the schedule based on user behavior.



### Safety & Reliability

* **Cycle Protection**: Enforces configurable minimum run times and minimum off times for both heating and cooling equipment to prevent short-cycling and protect the HVAC compressor and components.

* **Maximum Run Time Protection**: A critical safety feature that shuts down a heating or cooling cycle if it runs for an excessively long time (e.g., 90 minutes), preventing runaway operation due to a fault or open window.

* **System Lockout**: If the maximum run time is triggered multiple times within a set period, the thermostat will enter a full system lockout to protect the HVAC from major damage, requiring a manual reset.

* **Sensor Fault Detection**: Validates that sensor readings are within a plausible range. If a fault is detected, the system enters a safe fault state, shutting down all relays.

* **Hardware Watchdog Timer**: Utilizes the ESP32's built-in watchdog to automatically reboot the device if the main code ever freezes, ensuring the system never gets stuck with a relay on.

* **Power-On Delay**: Waits for a few seconds after booting before starting any HVAC operations to protect against power surges.

* **Persistent Storage (NVS)**: All user settings, including the full schedule and learned performance data, are saved to the ESP32's Non-Volatile Storage, ensuring all configurations are retained through power outages.



## Software Architecture



The project is organized into a clean, modular, multi-file structure to separate concerns and improve maintainability.



### `main.cpp` / `main.h`

* **Role**: The main application entry point and coordinator.

* **Responsibilities**:

  * Initializes all hardware and software modules (`Serial`, NVS, Watchdog, Filesystem).

  * Loads settings from NVS on boot.

  * Runs the main `loop()`, which orchestrates calls to all other modules.

  * Handles top-level logic like sensor fault detection and smart recovery calculations.

  * Contains the hardware abstraction layer (e.g., `readRelay`, `writeRelay`) to facilitate testing.



### `config.h`

* **Role**: A centralized header for all system-wide configurations.

* **Responsibilities**:

  * Defines all user-configurable settings (default temperature unit, cycle times, etc.).

  * Contains all hardware pin assignments and data structures like `Schedule` and `HvacPerformance`.

  * Holds all `enum` definitions for modes like `SystemMode` and `FanMode`.



### `hvac_logic.cpp` / `hvac_logic.h`

* **Role**: The core HVAC control engine.

* **Responsibilities**:

  * Contains the primary `controlTemperature`, `controlFan`, and `controlHumidity` functions.

  * Implements all the rules-based logic for when to turn relays on or off.

  * Manages all cycle protection timers and the safety lockout logic.

  * Contains the logic for measuring and learning HVAC performance data after each cycle.



### `learning.cpp` / `learning.h`

* **Role**: The module for on-device machine learning.

* **Responsibilities**:

  * Initializes the SPIFFS/LittleFS filesystem.

  * Provides the `log_manual_adjustment()` function to write user overrides to a log file.

  * Contains the placeholder `analyze_and_learn_if_needed()` function.



### `hvac_tests.cpp` / `hvac_tests.h`

* **Role**: A self-contained suite for unit and logic testing.

* **Responsibilities**:

  * Contains the `runTests()` function, which is called from `setup()` on boot.

  * Includes specific test functions for every major feature.

  * Uses a mocking framework to simulate time, sensor inputs, and relay states.



## Setup & Installation

1. **IDE**: This project is designed to be built with an IDE that supports the ESP-IDF framework, such as **VS Code with the PlatformIO extension**.

2. **File Structure**: In PlatformIO, place `.h` files in the `include` directory and `.cpp` files in the `src` directory.

3. **Libraries**: No external libraries are required beyond what is included with the standard ESP-IDF.

4. **Configuration**: Modify the settings in `include/config.h` to match your HVAC system.

5. **Build & Upload**: Use PlatformIO to build and upload the project to your ESP32-C6 board.

6. **Monitor**: Open the Serial Monitor at `115200` baud to view the test suite results and status logs.