Fix naming, first version of PID simulator

zeroflow · zeroflow · commit ad258ad22fbe · 2026-03-06T12:52:05.000Z
diff --git a/.gitignore b/.gitignore
@@ -15,4 +15,8 @@ static/.bundle/
 static/vendor/
 
 # Ruby gems
-gems/
+gems/
+
+# Claude
+CLAUDE.md
+agents/*
diff --git a/README.md b/README.md
@@ -85,7 +85,7 @@ Flash pre-built firmware directly from your browser at **[fancontroller.arthofer
 Reliable flashing method, especially for ESP32-S2 boards:
 
 1. Install [esptool](https://github.com/espressif/esptool): `pip install esptool`
-2. Download prebuilt binary from [fancontroller.arthofer.dev/firmware](https://fancontroller.arthofer.dev/firmware/)
+2. Download prebuilt binary from [GitHub Releases](https://github.com/zeroflow/wifi-fancontroller/releases/)
 3. Connect board via USB-C, hold BOOT button, press RESET
 4. Flash: `esptool.py --chip esp32s2 write_flash 0x0 firmware.bin`
 5. Press RESET to boot
diff --git a/README_LOCAL_DEV.md b/README_LOCAL_DEV.md
@@ -1,6 +1,6 @@
 # Local Development Setup
 
-This document describes how to run the ESPHome Fancontroller website locally for development.
+This document describes how to run the WiFi Fancontroller website locally for development.
 
 ## Option 1: Docker (Recommended)
 
diff --git a/examples/README.md b/examples/README.md
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Example Configurations
+# WiFi Fan Controller - Example Configurations
 
 This directory contains example configurations showing how to use the hardware packages.
 
diff --git a/fancontroller-rev1.0-esp32.factory.yaml b/fancontroller-rev1.0-esp32.factory.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 1.0 (ESP32) - Factory Configuration
+# WiFi Fan Controller - Revision 1.0 (ESP32) - Factory Configuration
 # This configuration is used for initial device provisioning and flashing.
 #
 # It includes additional features for first-time setup:
diff --git a/fancontroller-rev1.0-esp32.yaml b/fancontroller-rev1.0-esp32.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 1.0 (ESP32)
+# WiFi Fan Controller - Revision 1.0 (ESP32)
 # Base configuration file for production use
 #
 # This file contains the core ESPHome configuration and includes
diff --git a/fancontroller-rev2.0-esp32s2.factory.yaml b/fancontroller-rev2.0-esp32s2.factory.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 2.0 (ESP32-S2) - Factory Configuration
+# WiFi Fan Controller - Revision 2.0 (ESP32-S2) - Factory Configuration
 # This configuration is used for initial device provisioning and flashing.
 #
 # It includes additional features for first-time setup:
diff --git a/fancontroller-rev2.0-esp32s2.yaml b/fancontroller-rev2.0-esp32s2.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 2.0 (ESP32-S2)
+# WiFi Fan Controller - Revision 2.0 (ESP32-S2)
 # Base configuration file for production use
 #
 # This file contains the core ESPHome configuration and includes
diff --git a/fancontroller-rev3.0-esp32s2.factory.yaml b/fancontroller-rev3.0-esp32s2.factory.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 3.0 (ESP32-S2) - Factory Configuration
+# WiFi Fan Controller - Revision 3.0 (ESP32-S2) - Factory Configuration
 # This configuration is used for initial device provisioning and flashing.
 #
 # It includes additional features for first-time setup:
diff --git a/fancontroller-rev3.0-esp32s2.yaml b/fancontroller-rev3.0-esp32s2.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 3.0 (ESP32-S2)
+# WiFi Fan Controller - Revision 3.0 (ESP32-S2)
 # Base configuration file for production use
 #
 # This file contains the core ESPHome configuration and includes
diff --git a/fancontroller-rev3.1-esp32s2.factory.yaml b/fancontroller-rev3.1-esp32s2.factory.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 3.1 (ESP32-S2) - Factory Configuration
+# WiFi Fan Controller - Revision 3.1 (ESP32-S2) - Factory Configuration
 # This configuration is used for initial device provisioning and flashing.
 #
 # It includes additional features for first-time setup:
diff --git a/fancontroller-rev3.1-esp32s2.yaml b/fancontroller-rev3.1-esp32s2.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 3.1 (ESP32-S2)
+# WiFi Fan Controller - Revision 3.1 (ESP32-S2)
 # Base configuration file for production use
 #
 # This file contains the core ESPHome configuration and includes
diff --git a/fancontroller-rev3.2-esp32s2.factory.yaml b/fancontroller-rev3.2-esp32s2.factory.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 3.2 (ESP32-S2) - Factory Configuration
+# WiFi Fan Controller - Revision 3.2 (ESP32-S2) - Factory Configuration
 # This configuration is used for initial device provisioning and flashing.
 #
 # It includes additional features for first-time setup:
diff --git a/fancontroller-rev3.2-esp32s2.yaml b/fancontroller-rev3.2-esp32s2.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 3.2 (ESP32-S2)
+# WiFi Fan Controller - Revision 3.2 (ESP32-S2)
 # Base configuration file for production use
 #
 # This file contains the core ESPHome configuration and includes
diff --git a/fancontroller-rev3.3-esp32s2.factory.yaml b/fancontroller-rev3.3-esp32s2.factory.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 3.3 (ESP32-S2) - Factory Configuration
+# WiFi Fan Controller - Revision 3.3 (ESP32-S2) - Factory Configuration
 # This configuration is used for initial device provisioning and flashing.
 #
 # It includes additional features for first-time setup:
diff --git a/fancontroller-rev3.3-esp32s2.yaml b/fancontroller-rev3.3-esp32s2.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller - Revision 3.3 (ESP32-S2)
+# WiFi Fan Controller - Revision 3.3 (ESP32-S2)
 # Base configuration file for production use
 #
 # This file contains the core ESPHome configuration and includes
diff --git a/hardware-rev-1.0.yaml b/hardware-rev-1.0.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller Hardware Package - Revision 1.0
+# WiFi Fan Controller Hardware Package - Revision 1.0
 # Hardware: ESP32 (standard), esp32dev board
 # This package contains all hardware-specific configuration
 #
@@ -75,7 +75,7 @@ sensor:
     humidity:
       name: "Humidity"
       id: fancontroller_humidity
-    update_interval: 60s
+    update_interval: 10s
 
   # Fan 1 Speed
   - platform: pulse_counter
diff --git a/hardware-rev-2.0.yaml b/hardware-rev-2.0.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller Hardware Package - Revision 2.0
+# WiFi Fan Controller Hardware Package - Revision 2.0
 # Hardware: ESP32-S2, esp32-s2-saola-1 board
 # This package contains all hardware-specific configuration
 #
@@ -75,7 +75,7 @@ sensor:
     humidity:
       name: "Humidity"
       id: fancontroller_humidity
-    update_interval: 60s
+    update_interval: 10s
 
   # Fan 1 Speed
   - platform: pulse_counter
diff --git a/hardware-rev-3.0.yaml b/hardware-rev-3.0.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller Hardware Package - Revision 3.0
+# WiFi Fan Controller Hardware Package - Revision 3.0
 # Hardware: ESP32-S2, esp32-s2-saola-1 board
 # This package contains all hardware-specific configuration
 #
@@ -115,7 +115,7 @@ sensor:
     humidity:
       name: "Humidity"
       id: fancontroller_humidity
-    update_interval: 60s
+    update_interval: 10s
 
   # Fan 1 Speed
   - platform: pulse_counter
diff --git a/hardware-rev-3.1.yaml b/hardware-rev-3.1.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller Hardware Package - Revision 3.1
+# WiFi Fan Controller Hardware Package - Revision 3.1
 # Hardware: ESP32-S2, esp32-s2-saola-1 board
 # This package contains all hardware-specific configuration
 #
@@ -127,6 +127,7 @@ sensor:
     humidity:
       name: "Humidity"
       id: fancontroller_humidity
+    update_interval: 10s
 
   # Fan 1 Speed
   - platform: pulse_counter
diff --git a/hardware-rev-3.2.yaml b/hardware-rev-3.2.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller Hardware Package - Revision 3.2
+# WiFi Fan Controller Hardware Package - Revision 3.2
 # Hardware: ESP32-S2, esp32-s2-saola-1 board
 # This package contains all hardware-specific configuration
 #
diff --git a/hardware-rev-3.3.yaml b/hardware-rev-3.3.yaml
@@ -1,4 +1,4 @@
-# ESPHome Fan Controller Hardware Package - Revision 3.3
+# WiFi Fan Controller Hardware Package - Revision 3.3
 # Hardware: ESP32-S2, esp32-s2-saola-1 board
 # This package contains all hardware-specific configuration
 #
diff --git a/modules/temperature_pid.yaml b/modules/temperature_pid.yaml
@@ -13,18 +13,18 @@
 #       ref: main
 #       vars:
 #         friendly_name: "My Fan Controller"
-#         kp: "0.39509"                      # Proportional gain
-#         ki: "0.00470"                      # Integral gain
-#         kd: "20.74267"                     # Derivative gain
+#         kp: "3.0"                          # Proportional gain (UI scale ×100: % fan per °C)
+#         ki: "0.005"                        # Integral gain     (UI scale ×100)
+#         kd: "0.0"                          # Derivative gain   (UI scale ×100)
 #         max_integral: "0.0"                # Maximum integral term
 #         output_averaging_samples: "1"      # Output smoothing samples
 #         derivative_averaging_samples: "5"  # Derivative smoothing samples
 #
 # Configuration Variables:
 #   - friendly_name: Device name prefix (default: "Fancontroller")
-#   - kp: Proportional gain coefficient (default: 0.39509)
-#   - ki: Integral gain coefficient (default: 0.00470)
-#   - kd: Derivative gain coefficient (default: 20.74267)
+#   - kp: Proportional gain coefficient (default: 0.03)
+#   - ki: Integral gain coefficient (default: 0.00005)
+#   - kd: Derivative gain coefficient (default: 0.0)
 #   - max_integral: Max integral term value (default: 0.0)
 #   - output_averaging_samples: Output averaging samples (default: 1)
 #   - derivative_averaging_samples: Derivative averaging samples (default: 5)
@@ -45,12 +45,12 @@
 #
 substitutions:
   friendly_name: "Fancontroller" # default
-  kp: 0.39509 # kp: 0.3
-  ki: 0.00470 # ki: 0.0015
-  kd: 20.74267 # kd: 0
-  max_integral: 0.0
-  output_averaging_samples: 1
-  derivative_averaging_samples: 5
+  kp: "3.0"   # UI scale (×100): 3 ≈ 3% fan per °C
+  ki: "0.005" # UI scale (×100)
+  kd: "0.0"   # UI scale (×100)
+  max_integral: "0.0"
+  output_averaging_samples: "1"
+  derivative_averaging_samples: "5"
 
 number:
   ## OPTIONAL:
@@ -59,48 +59,48 @@ number:
   # These helper values will get saved to flash thus permanently over-riding 
   # the initial values set in the PID below.
 
-  # KP
+  # KP (scaled x100: 1.0 = 1% fan speed per °C error)
   - platform: template
     name: PID kp
     id: pid_kp_number
     icon: mdi:chart-bell-curve
     restore_value: true
-    initial_value: 0.3
+    initial_value: ${kp}
     min_value: 0
-    max_value: 5
-    step: 0.001
+    max_value: 500
+    step: 0.1
     optimistic: true
     set_action:
       lambda: |-
-        id(console_thermostat).set_kp( x );
+        id(console_thermostat).set_kp( x / 100.0 );
 
-  # KI
+  # KI (scaled x100)
   - platform: template
     name: PID ki
     id: pid_ki_number
     icon: mdi:chart-bell-curve
     restore_value: true
-    initial_value: 0.0015
+    initial_value: ${ki}
     min_value: 0
-    max_value: 1
-    step: 0.0001
+    max_value: 100
+    step: 0.01
     optimistic: true
     set_action:
-      lambda: id(console_thermostat).set_ki( x );
+      lambda: id(console_thermostat).set_ki( x / 100.0 );
 
-  # KD
+  # KD (scaled x100)
   - platform: template
     name: PID kd
     id: pid_kd_number
     icon: mdi:chart-bell-curve
     restore_value: true
-    initial_value: 0.0
-    min_value: -50
-    max_value: 50
-    step: 0.001
+    initial_value: ${kd}
+    min_value: -5000
+    max_value: 5000
+    step: 0.1
     optimistic: true
     set_action:
-      lambda: id(console_thermostat).set_kd( x );
+      lambda: id(console_thermostat).set_kd( x / 100.0 );
 
   # Set threshold low
   - platform: template
@@ -320,12 +320,14 @@ climate:
       min_temperature: 20 °C
       max_temperature: 50 °C
   
-    # See the README for setting up these parameters.
-    # These are over ridden by the number templates above.
+    # Boot-time fallback only (internal 0-1 scale).
+    # Overridden within milliseconds by the number entities above (which
+    # restore from flash and call set_kp/ki/kd via set_action on boot).
+    # Tune via the HA sliders — substitutions kp/ki/kd set those initial values.
     control_parameters:
-      kp: ${kp} # kp: 0.3
-      ki: ${ki} # ki: 0.0015
-      kd: ${kd} # kd: 0
+      kp: 0.03     # = kp default / 100
+      ki: 0.00005  # = ki default / 100
+      kd: 0.0      # = kd default / 100
       max_integral: 0.0
       output_averaging_samples: 1
       derivative_averaging_samples: 5
@@ -344,4 +346,4 @@ button:
   name: "PID Climate Autotune"
   id: pid_autotune
   on_press:
-    - climate.pid.autotune: console_thermostat
+    - climate.pid.autotune: console_thermostat
diff --git a/setup_local.sh b/setup_local.sh
@@ -1,5 +1,5 @@
 #!/bin/bash
-# Local Jekyll development setup for ESPHome Fancontroller website
+# Local Jekyll development setup for WiFi Fancontroller website
 
 set -e
 
diff --git a/static/_config.yml b/static/_config.yml
@@ -1,4 +1,4 @@
-title: ESPHome Fancontroller
+title: WiFi Fancontroller
 description: 4xPWM Fan Controller Powered by ESPHome and ESP Web Tools
 remote_theme: mmistakes/minimal-mistakes@4.24.0
 
diff --git a/static/index.md b/static/index.md
@@ -85,6 +85,37 @@ A CE-certified, ESP32-based PWM fan controller designed for home server racks, m
 
 Flash pre-built firmware directly from your browser. Connect your board via USB-C and click the button for your hardware revision below.
 
+## ESPHome Modules
+
+The fan controller firmware is built around reusable ESPHome packages. Drop any module into your configuration with a single `packages:` entry — no copy-pasting required. All parameters have sensible defaults and can be tuned live from Home Assistant.
+
+| Module | File | Description |
+|--------|------|-------------|
+| <i class="fa-solid fa-sliders"></i> **Temperature PID** | `modules/temperature_pid.yaml` | Full PID thermostat with Home Assistant climate entity. Live kp/ki/kd tuning, one-click autotune, and deadband to prevent oscillation. [→ PID Simulator](pid-simulator) |
+| <i class="fa-solid fa-chart-line"></i> **Temperature Curve** | `modules/temperature_curve.yaml` | Up to 5 configurable temperature/speed points with linear interpolation. Points are editable from Home Assistant and auto-sorted at runtime. |
+| <i class="fa-solid fa-temperature-half"></i> **Temperature Linear** | `modules/temperature_linear.yaml` | Simple three-zone control: off below a threshold, constant minimum speed, then linear ramp to full speed. |
+| <i class="fa-solid fa-gauge-high"></i> **RPM PI Control** | `modules/rpm_pi_control.yaml` | Holds each fan at a target RPM using a PI controller. Includes anti-windup, deadband, and per-fan debug sensors. |
+| <i class="fa-solid fa-circle-dot"></i> **RPM Status LEDs** | `modules/rpm_status_leds.yaml` | Colors each fan's RGB LED from red (stopped) to green (full speed) based on live RPM. Configurable max RPM scale. |
+
+### Usage Example
+
+Add any module to your ESPHome config via the `packages` key:
+
+```yaml
+packages:
+  hardware: !include hardware-rev-3.3.yaml
+  temperature_pid:
+    url: https://github.com/zeroflow/wifi-fancontroller
+    files: [modules/temperature_pid.yaml]
+    ref: main
+    vars:
+      friendly_name: "Server Rack"
+      kp: "3.0"
+      ki: "0.005"
+```
+
+Modules can be combined — for example, pair `temperature_pid` for automatic control with `rpm_status_leds` for visual feedback.
+
 ## Hardware Revisions
 
 {% include feature_row id="feature_row_rev3" type="left" %}
diff --git a/static/pid-simulator.html b/static/pid-simulator.html
diff --git a/static/site.webmanifest b/static/site.webmanifest

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# ESPHome Fan Controller - Example Configurations`
	`1`	`+# WiFi Fan Controller - Example Configurations`
`2`	`2`
`3`	`3`	`This directory contains example configurations showing how to use the hardware packages.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# ESPHome Fan Controller - Revision 1.0 (ESP32) - Factory Configuration`
	`1`	`+# WiFi Fan Controller - Revision 1.0 (ESP32) - Factory Configuration`
`2`	`2`	`# This configuration is used for initial device provisioning and flashing.`
`3`	`3`	`#`
`4`	`4`	`# It includes additional features for first-time setup:`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# ESPHome Fan Controller - Revision 2.0 (ESP32-S2) - Factory Configuration`
	`1`	`+# WiFi Fan Controller - Revision 2.0 (ESP32-S2) - Factory Configuration`
`2`	`2`	`# This configuration is used for initial device provisioning and flashing.`
`3`	`3`	`#`
`4`	`4`	`# It includes additional features for first-time setup:`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# ESPHome Fan Controller - Revision 3.0 (ESP32-S2) - Factory Configuration`
	`1`	`+# WiFi Fan Controller - Revision 3.0 (ESP32-S2) - Factory Configuration`
`2`	`2`	`# This configuration is used for initial device provisioning and flashing.`
`3`	`3`	`#`
`4`	`4`	`# It includes additional features for first-time setup:`