ESP32/Thermostat/README.md

Thermostat Project for Sonoff Basic R2

This project implements a WiFi thermostat using a Sonoff Basic R2, designed for integration with Home Assistant via MQTT. It supports preset modes (confort, eco, off, boost), receives room temperature from an MQTT gateway, and provides a fallback WiFi configuration portal for setup.

Features

• MQTT-based Home Assistant integration as a thermostat device (with preset modes)
• Receives room temperature from an external MQTT sensor (e.g., Xiaomi)
• Fallback WiFi configuration page for setting WiFi, MQTT server, preset temperatures, and device ID
• Configurable preset temperatures (confort, eco, boost, hors gel)
• Clean code structure for maintainability

Project Structure

• src/ : Main application logic
• include/ : Header files
• data/ : Static files for web configuration portal
• platformio.ini : PlatformIO project configuration
• README.md : This documentation

Getting Started

1. Prerequisites

• PlatformIO extension for VS Code
• Sonoff Basic R2 device
• MQTT broker (e.g., Mosquitto)
• Home Assistant instance

2. Build & Upload

1. Clone this repository or copy the folder to your PlatformIO workspace.
2. Edit platformio.ini if needed (WiFi/MQTT credentials can be set via the web portal after first boot).
3. Build and upload the firmware to your Sonoff Basic R2.

3. First Boot & Configuration

• On first boot (or if WiFi/MQTT fails), the device starts a WiFi AP for configuration.
• Connect to the AP and open the captive portal to set:
  • WiFi SSID/password
  • MQTT server/port/credentials
  • Preset temperatures (confort, eco, boost, hors gel)
  • Device ID for temperature sensor

4. Home Assistant Integration

• The device publishes/receives via MQTT using the Home Assistant climate platform.
• Preset modes (confort, eco, off, boost) are supported and can be set from Home Assistant.
• The device subscribes to a temperature topic (e.g., from a Xiaomi sensor via Zigbee2MQTT).

5. File Overview

• src/main.cpp : Main application entry point
• src/thermostat.cpp / include/thermostat.h : Thermostat logic
• src/mqtt_handler.cpp / include/mqtt_handler.h : MQTT communication
• src/web_config.cpp / include/web_config.h : WiFi/MQTT/web config portal
• src/preset.cpp / include/preset.h : Preset management
• data/ : HTML/CSS/JS for configuration portal

Example MQTT Topics

• Temperature: home/room/temperature/<device_id>
• State: home/thermostat/<device_id>/state
• Command: home/thermostat/<device_id>/set

Advanced

• Fallback to AP mode if WiFi or MQTT fails
• All configuration is stored in flash and can be reset via the web portal

License

MIT