# ESP32-C3 Fan Controller

An automatic server fan controller built on the ESP32-C3, featuring temperature-based relay control, OLED status display, and Home Assistant integration via MQTT.

## Features

- **Auto fan control** — relay switches ON/OFF based on temperature thresholds with hysteresis
- **DHT22 sensor** — reads temperature and humidity every second
- **SSD1306 OLED** — displays live temp, humidity, and fan state
- **MQTT publishing** — streams sensor data and fan state to Home Assistant
- **WiFi** — connects on boot, auto-reconnects if MQTT drops

## Hardware

| Component | Details |
|---|---|
| Microcontroller | ESP32-C3 (with onboard OLED) |
| Sensor | DHT22 (temperature + humidity) |
| Relay | 5V relay module (active-LOW) |
| Fan | USB 5V fan |
| Display | SSD1306 128×64 OLED (I2C) |

## Wiring

| ESP32-C3 Pin | Connected To |
|---|---|
| `GPIO2` | DHT22 DATA (+ 4.7kΩ pullup to 3V3) |
| `GPIO3` | Relay IN |
| `GPIO5` (SDA) | OLED SDA |
| `GPIO6` (SCL) | OLED SCL |
| `3V3` | DHT22 VCC, OLED VCC |
| `GND` | DHT22 GND, OLED GND, Relay GND |

Relay wiring:

- **COM** → USB 5V
- **NO** → Fan + (red wire)
- Fan − (black wire) → GND

## Configuration

Copy `secrets.h.example` to `secrets.h` and fill in your values:

```cpp
#define WIFI_SSID  "your_wifi_ssid"
#define WIFI_PASS  "your_wifi_password"
#define MQTT_HOST  "192.168.1.X"   // Home Assistant IP
#define MQTT_USER  "mqtt_user"
#define MQTT_PASS  "mqtt_pass"
```

### Temperature Thresholds

Edit these defines in `fan_controller.ino`:

```cpp
#define TEMP_ON   28.0   // Fan turns ON above this (°C)
#define TEMP_OFF  25.0   // Fan turns OFF below this (°C)
```

## MQTT Topics

| Topic | Direction | Payload |
|---|---|---|
| `esp32c3_fan/temperature` | Publish | `23.5` (°C) |
| `esp32c3_fan/humidity` | Publish | `41` (%) |
| `esp32c3_fan/fan/state` | Publish | `ON` / `OFF` |

## Home Assistant Setup

Add to `configuration.yaml`:

```yaml
mqtt:
  sensor:
    - name: "Room Temperature"
      unique_id: "esp32c3_temperature"
      state_topic: "esp32c3_fan/temperature"
      unit_of_measurement: "°C"
      device_class: temperature

    - name: "Room Humidity"
      unique_id: "esp32c3_humidity"
      state_topic: "esp32c3_fan/humidity"
      unit_of_measurement: "%"
      device_class: humidity

  binary_sensor:
    - name: "Server Fan"
      unique_id: "esp32c3_fan"
      state_topic: "esp32c3_fan/fan/state"
      payload_on: "ON"
      payload_off: "OFF"
      device_class: running
```

Restart HA after saving. Requires the **Mosquitto broker** add-on installed and running.

## Dependencies

Install via Arduino IDE Library Manager:

- [U8g2](https://github.com/olikraus/u8g2) — OLED display
- [DHT sensor library](https://github.com/adafruit/DHT-sensor-library) — DHT22
- [PubSubClient](https://github.com/knolleary/pubsubclient) — MQTT client
- WiFi (built-in with ESP32 board package)

## Project Structure

```
esp32c3-fan-controller/
├── fan_controller.ino   # Main sketch
├── secrets.h            # WiFi & MQTT credentials (gitignored)
├── secrets.h.example    # Credentials template
├── .gitignore
└── README.md
```

## License

MIT