commit 0596b659036b57d9e163575910f99e4ad37d3693
Author: dtoro <d.toro.v@pm.me>
Date:   Sun Mar 29 22:19:17 2026 +0200

    chore: v1

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..a101992
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,41 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+*.swp
+*.swo
+*~
+.vscode/
+
+# Arduino
+build/
+.clang-format
+*.o
+*.a
+*.so
+*.so.*
+*.dylib
+*.dll
+*.exe
+
+# Arduino IDE
+.pioenvs/
+.piolibdeps/
+.pio/
+.vscode-pio
+
+# PlatformIO
+.platformio/
+platformio.ini
+
+# Build directories
+bin/
+obj/
+
+# Editor backups
+*.bak
+*.tmp
+
+# Dependencies and libraries
+node_modules/
+dist/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..db8e877
--- /dev/null
+++ b/README.md
@@ -0,0 +1,120 @@
+# 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/temperature` | Publish | `23.5` (°C) |
+| `esp32c3/humidity` | Publish | `41` (%) |
+| `esp32c3/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/temperature"
+      unit_of_measurement: "°C"
+      device_class: temperature
+
+    - name: "Room Humidity"
+      unique_id: "esp32c3_humidity"
+      state_topic: "esp32c3/humidity"
+      unit_of_measurement: "%"
+      device_class: humidity
+
+  binary_sensor:
+    - name: "Server Fan"
+      unique_id: "esp32c3_fan"
+      state_topic: "esp32c3/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