{"id":30267357,"url":"https://github.com/will-white/hvac-controller","last_synced_at":"2025-08-15T23:38:13.573Z","repository":{"id":308749793,"uuid":"1033951828","full_name":"will-white/hvac-controller","owner":"will-white","description":"Locally hosted \"smart\" HVAC controller","archived":false,"fork":false,"pushed_at":"2025-08-07T17:51:45.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-07T18:19:18.023Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/will-white.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-07T15:48:12.000Z","updated_at":"2025-08-07T17:51:48.000Z","dependencies_parsed_at":"2025-08-07T18:35:58.260Z","dependency_job_id":null,"html_url":"https://github.com/will-white/hvac-controller","commit_stats":null,"previous_names":["will-white/hvac-controller"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/will-white/hvac-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-white%2Fhvac-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-white%2Fhvac-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-white%2Fhvac-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-white%2Fhvac-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/will-white","download_url":"https://codeload.github.com/will-white/hvac-controller/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will-white%2Fhvac-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270646496,"owners_count":24621669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-15T23:38:09.179Z","updated_at":"2025-08-15T23:38:13.547Z","avatar_url":"https://github.com/will-white.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP32-C6 Smart HVAC Thermostat\n\nThis 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.\n\n## Key Features\n\n### Core Control\n* **7-Day Programmable Schedule**: Independent schedules for weekdays and weekends with up to 10 custom periods per day (e.g., Wake, Away, Home, Sleep).\n* **Multi-Mode Operation**: Supports Heating, Cooling, Auto-Changeover, and Fan-Only modes.\n* **Fan Control**: Includes `AUTO` (runs with system), `ON` (always on), and `CIRCULATE` (runs periodically for a set time, e.g., 15 minutes every hour).\n* **Unit Selection**: Supports both Fahrenheit and Celsius for all temperature settings and readouts.\n\n### Efficiency \u0026 Smart Features\n* **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.\n* **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.\n* **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.\n* **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.\n\n### Safety \u0026 Reliability\n* **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.\n* **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.\n* **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.\n* **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.\n* **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.\n* **Power-On Delay**: Waits for a few seconds after booting before starting any HVAC operations to protect against power surges.\n* **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.\n\n## Software Architecture\n\nThe project is organized into a clean, modular, multi-file structure to separate concerns and improve maintainability.\n\n### `main.cpp` / `main.h`\n* **Role**: The main application entry point and coordinator.\n* **Responsibilities**:\n  * Initializes all hardware and software modules (`Serial`, NVS, Watchdog, Filesystem).\n  * Loads settings from NVS on boot.\n  * Runs the main `loop()`, which orchestrates calls to all other modules.\n  * Handles top-level logic like sensor fault detection and smart recovery calculations.\n  * Contains the hardware abstraction layer (e.g., `readRelay`, `writeRelay`) to facilitate testing.\n\n### `config.h`\n* **Role**: A centralized header for all system-wide configurations.\n* **Responsibilities**:\n  * Defines all user-configurable settings (default temperature unit, cycle times, etc.).\n  * Contains all hardware pin assignments and data structures like `Schedule` and `HvacPerformance`.\n  * Holds all `enum` definitions for modes like `SystemMode` and `FanMode`.\n\n### `hvac_logic.cpp` / `hvac_logic.h`\n* **Role**: The core HVAC control engine.\n* **Responsibilities**:\n  * Contains the primary `controlTemperature`, `controlFan`, and `controlHumidity` functions.\n  * Implements all the rules-based logic for when to turn relays on or off.\n  * Manages all cycle protection timers and the safety lockout logic.\n  * Contains the logic for measuring and learning HVAC performance data after each cycle.\n\n### `learning.cpp` / `learning.h`\n* **Role**: The module for on-device machine learning.\n* **Responsibilities**:\n  * Initializes the SPIFFS/LittleFS filesystem.\n  * Provides the `log_manual_adjustment()` function to write user overrides to a log file.\n  * Contains the placeholder `analyze_and_learn_if_needed()` function.\n\n### `hvac_tests.cpp` / `hvac_tests.h`\n* **Role**: A self-contained suite for unit and logic testing.\n* **Responsibilities**:\n  * Contains the `runTests()` function, which is called from `setup()` on boot.\n  * Includes specific test functions for every major feature.\n  * Uses a mocking framework to simulate time, sensor inputs, and relay states.\n\n## Setup \u0026 Installation\n1. **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**.\n2. **File Structure**: In PlatformIO, place `.h` files in the `include` directory and `.cpp` files in the `src` directory.\n3. **Libraries**: No external libraries are required beyond what is included with the standard ESP-IDF.\n4. **Configuration**: Modify the settings in `include/config.h` to match your HVAC system.\n5. **Build \u0026 Upload**: Use PlatformIO to build and upload the project to your ESP32-C6 board.\n6. **Monitor**: Open the Serial Monitor at `115200` baud to view the test suite results and status logs.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwill-white%2Fhvac-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwill-white%2Fhvac-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwill-white%2Fhvac-controller/lists"}