PerfectTemp is a distributed smart thermostat prototype that balances comfort across six rooms using ESP32 room nodes, FreeRTOS task orchestration, ESP-NOW telemetry, I2C temperature sensing, and a central HVAC decision engine written in C/C++.
Status: active prototype / work-in-progress. The current repository contains the firmware architecture, protocol layer, control engine, state machine, test scaffolding, simulator tools, and documentation needed to continue hardware integration.
Most homes rely on a single central thermostat, even though room temperatures can vary significantly. PerfectTemp collects room-level telemetry from six rooms and uses weighted comfort preferences to make smarter heating, cooling, or fan-circulation decisions through a central thermostat interface.
PerfectTemp does not claim to make one central HVAC system independently control six rooms without additional hardware. The current design optimizes whole-home comfort using distributed sensing. Future versions can add smart dampers or vent control.
Room 1 Node ┐
Room 2 Node ┤
Room 3 Node ┤
Room 4 Node ├── ESP-NOW Wireless Telemetry ──> Central Controller ──> Thermostat Interface
Room 5 Node ┤ │
Room 6 Node ┘ └── Logs / Diagnostics / Config
- Six distributed ESP32 room nodes
- FreeRTOS-based central controller task model
- ESP-NOW wireless telemetry design
- I2C temperature/humidity sensor abstraction
- CRC-protected room telemetry packets
- Sequence number tracking and stale-room detection
- Weighted comfort algorithm for room-level preference balancing
- HVAC state machine with hysteresis and anti-short-cycle protection
- Bench-safe thermostat relay simulation layer
- UART diagnostics and structured logging hooks
- Unit tests for protocol, CRC, comfort engine, and HVAC state machine
- Simulator for six virtual rooms
- GitHub Actions scaffolding for formatting/build/test workflows
perfecttemp/
├── firmware/
│ ├── common/ # Shared packet, CRC, logging, error types
│ ├── room_node/ # ESP32 room sensor node firmware skeleton
│ ├── central_controller/ # ESP32 central controller firmware skeleton
│ └── simulator/ # Host-side simulator
├── tests/
│ ├── unit/ # Host-buildable C unit tests
│ ├── integration/ # Manual/system integration test plans
│ └── hardware/ # Bench and calibration test plans
├── docs/ # Architecture, RTOS, protocol, testing docs
├── tools/ # Serial/debug/config helper scripts
├── config/ # Example room profiles and thresholds
└── .github/workflows/ # CI workflow templates
Central controller data flow:
ESP-NOW callback
↓
rx_queue
↓
packet_router_task
↓
room_state_table
↓
control_loop_task
↓
hvac_command_queue
↓
thermostat_task
↓
GPIO / relay simulation
Each room has a preferred temperature and weight.
comfort_error = preferred_temperature - current_temperature
weighted_demand = Σ(error × room_weight) / Σ(room_weight)
For heating, a positive weighted demand means the home is too cold. For cooling, a negative weighted demand means the home is too warm.
The HVAC state machine adds:
- hysteresis band
- minimum heat runtime
- minimum cool runtime
- minimum compressor off-time
- stale sensor rejection
- fault-aware decision handling
Implemented in this repo:
- Project architecture and documentation
- Shared packet format and CRC16 implementation
- Room state and control configuration models
- Weighted comfort engine
- HVAC state machine
- Unit test scaffolding
- Room node firmware skeleton
- Central controller firmware skeleton
- Simulator and helper tools
In progress / next hardware milestones:
- ESP-NOW packet transmission on physical ESP32 boards
- Six-node bench validation
- Thermostat relay board isolation testing
- Temperature sensor calibration workflow
- Enclosure and wiring design
The embedded target is intended for ESP-IDF, but the core algorithm modules can be tested on a normal machine.
cd tests/unit
make
./build/perfecttemp_testspython3 tools/generate_room_config.py
python3 firmware/simulator/room_simulator.py[ROOM 3] temp=20.14C pref=22.00C error=+1.86C battery=3940mV seq=184
[CTRL] weighted_heat_demand=1.21C threshold=0.70C decision=HEAT
[HVAC] state=HEATING runtime=00:04:12 min_runtime=00:05:00
[DIAG] room_5 stale=true last_seen=18.4s packet_loss=3
The current thermostat interface is designed as a bench-safe simulation layer. Real HVAC wiring may involve 24VAC control lines and must use proper isolation, fusing, relay selection, and professional validation before deployment.
- Protocol + CRC + packet parser
- Room node telemetry firmware
- Central controller packet router
- Comfort engine and HVAC state machine
- Bench-safe relay simulation
- Six-node hardware test
- Calibration workflow
- Optional smart damper / smart vent expansion
MIT License. See LICENSE.