Add warning to flashing, reword readme.

zeroflow · zeroflow · commit f5d49bce222a · 2026-03-06T14:26:22.000Z
diff --git a/README.md b/README.md
@@ -16,6 +16,16 @@ A CE-certified, ESP32-based PWM fan controller designed for home server racks, m
 
 **Professional Quality**: CE certified hardware with RGB status LEDs showing system status at a glance. Standard 12V barrel jack power input works with commonly available power supplies.
 
+## Get Your Board
+
+**Ready to upgrade your setup?**
+
+**[Buy on Elecrow - $35.99](https://www.elecrow.com/wifi-fancontroller1.html)** - Boards and 3D-printed cases available
+
+**[Complete Documentation & Web Installer](https://fancontroller.arthofer.dev/)** - Flash firmware directly from your browser
+
+**DIY Case**: Print your own case using the [WiFi Fancontroller Case](https://www.printables.com/model/987263-wifi-fancontroller-case) design on Printables.com.
+
 ## Specifications
 
 * **Power**
@@ -36,25 +46,37 @@ A CE-certified, ESP32-based PWM fan controller designed for home server racks, m
   * WiFi (ESP32/ESP32-S2)
   * USB-C for programming and power (Rev 2.0+)
 
-## Get Your Board
+## Power Draw
 
-**Ready to upgrade your setup?**
+The power usage of the device is dominated by the fans.
+As a standalone device, these are the measured power figures in different operation modes.
 
-**[Buy on Elecrow - $35,99](https://www.elecrow.com/wifi-fancontroller1.html)** - Boards and 3D-printed cases available
+Mode | Power Draw
+---- | ----------
+Active Wifi Transfer (e.g. OTA Upload) | 0.6W
+Wifi connected, power save mode deactivated (not default) | 0.52W
+```Default``` Wifi connected, LEDs showing status (one-colored) | 0.25W
+Wifi connected, LEDs off | 0.2W
+Deep Sleep | 0.07W
 
-**[Complete Documentation & Web Installer](https://fancontroller.arthofer.dev/)** - Flash firmware directly from your browser
+Disabling Wifi while not in deep sleep does not reduce power consumption, as the default light power save mode already does a good job.
 
-**DIY Case**: Print your own case using the [WiFi Fancontroller Case](https://www.printables.com/model/987263-wifi-fancontroller-case) design on Printables.com.
+These values have been measured via a DPS3005 power supply, therefore, their accuracy cannot be guaranteed.
+
+---
 
 ## Quick Start
 
 All boards come pre-flashed with an ESPHome factory image that's ready to use:
 
-1. **Power up the board** via USB-C or 12V DC
+1. **Power up the board** via USB-C or 12V DC (USB-C is for flashing only, power via 12V DC barrel jack is required for fans)
 2. **Connect to the WiFi hotspot** (e.g. `fancontroller-r3-1-abcdef`)
 3. **Configure your WiFi** through the captive portal
 4. **Done!** Board appears in Home Assistant via ESPHome
 
+**What you get out of the box:**
+The factory firmware exposes all 4 fan channels as speed controls in Home Assistant, along with temperature and humidity readings from the onboard sensor. Fan speeds can be adjusted manually from 0–100% or automated via Home Assistant. RPM monitoring is available for each fan port.
+
 For custom firmware or troubleshooting, see [Installation Methods](#installation-methods) below.
 
 ### Identifying Your Board Revision
@@ -67,8 +89,8 @@ Revision | Left                      | Fan Ports             | Right   | Details
 2.0  | DC 12V, Status LED            | Fans                  | USB-C   | [Link](https://fancontroller.arthofer.dev/fancontroller-rev2.0) |
 3.0  | DC 12V, Status LED, QWIIC     | Fans                  | USB-C   | [Link](https://fancontroller.arthofer.dev/fancontroller-rev3.0) |
 3.1  | DC 12V, RGB Status LED, QWIIC | Fans, RGB Status LEDs | USB-C   | [Link](https://fancontroller.arthofer.dev/fancontroller-rev3.1) |
-3.2  | DC 12V, RGB Status LED, QWIIC | Fans, RGB Status LEDs | USB-C   | [Link](https://fancontroller.arthofer.dev/fancontroller-rev3.2) | Functionally identical to Rev 3.1
-3.3  | DC 12V, RGB Status LED, QWIIC | Fans, RGB Status LEDs | USB-C   | [Link](https://fancontroller.arthofer.dev/fancontroller-rev3.3) | Functionally identical to Rev 3.1
+3.2  | DC 12V, RGB Status LED, QWIIC | Fans, RGB Status LEDs | USB-C   | [Link](https://fancontroller.arthofer.dev/fancontroller-rev3.2) | Compatible firmware and pinout — hardware-only revisions
+3.3  | DC 12V, RGB Status LED, QWIIC | Fans, RGB Status LEDs | USB-C   | [Link](https://fancontroller.arthofer.dev/fancontroller-rev3.3) | Compatible firmware and pinout — hardware-only revisions
 
 ---
 
@@ -78,7 +100,7 @@ Revision | Left                      | Fan Ports             | Right   | Details
 
 Flash pre-built firmware directly from your browser at **[fancontroller.arthofer.dev](https://fancontroller.arthofer.dev/)**
 
-**Note for ESP32-S2 boards (Rev 2.0, 3.x):** Web-based flashing may have connectivity issues. Currently (4.3.2025) the most reliable web tool is [ESPWEBTOOL by Spacehuhn](https://esptool.spacehuhn.com/). If the browser flash fails, use Method 2 (esptool) instead. 
+Note for ESP32-S2 boards (Rev 2.0, 3.x): Web-based flashing may have connectivity issues. The most reliable web tool is [ESPWEBTOOL by Spacehuhn](https://esptool.spacehuhn.com/). If the browser flash fails, use Method 2 (esptool) instead.
 
 ### Method 2: esptool (Alternative for ESP32-S2)
 
@@ -167,6 +189,9 @@ No manual pin configuration needed - just import the package and customize your
 
 ---
 
+<details>
+<summary><strong>Fan Control Modules (advanced — click to expand)</strong></summary>
+
 ## Fan Control Modules
 
 Beyond the basic hardware configuration, this project includes optional control modules that implement different fan control strategies. These modules can be imported into your configuration to add temperature-based fan control or status displays.
@@ -348,24 +373,7 @@ You can combine multiple modules in your configuration. For example:
 - Use RPM PI control with temperature sensors to create a custom automation that sets target RPM based on temperature thresholds
 - Combine linear temperature control with RPM status LEDs for simple automatic control with visual feedback
 
----
-
-## Power Draw
-
-The power usage of the device is dominated by the fans.
-As a standalone device, these are the measured power figures in different operation modes.
-
-Mode | Power Draw
----- | ----------
-Active Wifi Transfer (e.g. OTA Upload) | 0.6W
-Wifi connected, power save mode deactivated (not default) | 0.52W
-```Default``` Wifi connected, LEDs showing status (one-colored) | 0.25W
-Wifi connected, LEDs off | 0.2W
-Deep Sleep | 0.07W
-
-Disabling Wifi while not in deep sleep does not reduce power consumption, as the default light power save mode already does a good job.
-
-These values have been measured via a DPS3005 power supply, therefore, their accuracy cannot be guaranteed.
+</details>
 
 ---
 
@@ -377,17 +385,6 @@ These values have been measured via a DPS3005 power supply, therefore, their acc
 
 **Need Help?** Open an issue on [GitHub](https://github.com/zeroflow/wifi-fancontroller/issues) or consult the ESPHome documentation.
 
----
-
-## Resources
-
-- **Documentation & Web Installer**: [fancontroller.arthofer.dev](https://fancontroller.arthofer.dev/)
-- **Purchase Boards**: [Elecrow Store - $35,99](https://www.elecrow.com/wifi-fancontroller1.html)
-- **3D Printable Case**: [Printables.com](https://www.printables.com/model/987263-wifi-fancontroller-case)
-- **Hardware Packages**: Available in this repository under `hardware-rev-*.yaml`
-- **ESPHome Documentation**: [esphome.io](https://esphome.io/)
-- **Home Assistant**: [home-assistant.io](https://home-assistant.io/)
-
 ## Contributing
 
 Found a bug or have a feature request? Open an issue or submit a pull request on [GitHub](https://github.com/zeroflow/wifi-fancontroller).
diff --git a/static/fancontroller-rev2.0.md b/static/fancontroller-rev2.0.md
@@ -31,13 +31,19 @@ toc_icon: "microchip"
 
 <esp-web-install-button manifest="firmware/fancontroller-r2-0.manifest.json"></esp-web-install-button>
 
-> **Note:** ESP32-S2 boards may have connectivity issues with web-based flashing. If browser flash fails, use [esptool](https://github.com/espressif/esptool) for reliable flashing:
->
-> ```bash
-> esptool.py --chip esp32s2 write_flash 0x0 firmware.bin
-> ```
->
-> [Download prebuilt binary](/firmware/fancontroller-r2-0-esp32s2.factory.bin)
+<details>
+<summary>⚠️ USB flashing not working? (ESP32-S2 known issue)</summary>
+<p>The ESP32-S2 has known USB reliability issues — there is no permanent fix. If the browser installer fails, use <a href="https://esptool.spacehuhn.com/">ESPWEBTOOL by Spacehuhn</a> as a fallback:</p>
+<ol>
+<li>Connect the board via USB-C</li>
+<li>Hold BOOT, press RESET to enter boot mode</li>
+<li>Click "Connect" in ESPWEBTOOL</li>
+<li>Remove all flash entries except one</li>
+<li>Flash the <code>.bin</code> file at address <code>0x0</code></li>
+</ol>
+<p>Alternatively, use <a href="https://github.com/espressif/esptool">esptool</a> from the command line: <code>esptool.py --chip esp32s2 write_flash 0x0 firmware.bin</code></p>
+<p><a href="/firmware/fancontroller-r2-0-esp32s2.factory.bin">Download prebuilt binary</a></p>
+</details>
 
 ## Example Configurations
 
diff --git a/static/fancontroller-rev3.0.md b/static/fancontroller-rev3.0.md
@@ -36,13 +36,19 @@ toc_icon: "microchip"
 
 <esp-web-install-button manifest="firmware/fancontroller-r3-0.manifest.json"></esp-web-install-button>
 
-> **Note:** ESP32-S2 boards may have connectivity issues with web-based flashing. If browser flash fails, use [esptool](https://github.com/espressif/esptool) for reliable flashing:
->
-> ```bash
-> esptool.py --chip esp32s2 write_flash 0x0 firmware.bin
-> ```
->
-> [Download prebuilt binary](/firmware/fancontroller-r3-0-esp32s2.factory.bin)
+<details>
+<summary>⚠️ USB flashing not working? (ESP32-S2 known issue)</summary>
+<p>The ESP32-S2 has known USB reliability issues — there is no permanent fix. If the browser installer fails, use <a href="https://esptool.spacehuhn.com/">ESPWEBTOOL by Spacehuhn</a> as a fallback:</p>
+<ol>
+<li>Connect the board via USB-C</li>
+<li>Hold BOOT, press RESET to enter boot mode</li>
+<li>Click "Connect" in ESPWEBTOOL</li>
+<li>Remove all flash entries except one</li>
+<li>Flash the <code>.bin</code> file at address <code>0x0</code></li>
+</ol>
+<p>Alternatively, use <a href="https://github.com/espressif/esptool">esptool</a> from the command line: <code>esptool.py --chip esp32s2 write_flash 0x0 firmware.bin</code></p>
+<p><a href="/firmware/fancontroller-r3-0-esp32s2.factory.bin">Download prebuilt binary</a></p>
+</details>
 
 ## Example Configurations
 
diff --git a/static/fancontroller-rev3.1.md b/static/fancontroller-rev3.1.md
@@ -43,13 +43,19 @@ Rev 3.1 builds upon Rev 3.0 with visual feedback improvements:
 
 <esp-web-install-button manifest="firmware/fancontroller-r3-1.manifest.json"></esp-web-install-button>
 
-> **Note:** ESP32-S2 boards may have connectivity issues with web-based flashing. If browser flash fails, use [esptool](https://github.com/espressif/esptool) for reliable flashing:
->
-> ```bash
-> esptool.py --chip esp32s2 write_flash 0x0 firmware.bin
-> ```
->
-> [Download prebuilt binary](/firmware/fancontroller-r3-1-esp32s2.factory.bin)
+<details>
+<summary>⚠️ USB flashing not working? (ESP32-S2 known issue)</summary>
+<p>The ESP32-S2 has known USB reliability issues — there is no permanent fix. If the browser installer fails, use <a href="https://esptool.spacehuhn.com/">ESPWEBTOOL by Spacehuhn</a> as a fallback:</p>
+<ol>
+<li>Connect the board via USB-C</li>
+<li>Hold BOOT, press RESET to enter boot mode</li>
+<li>Click "Connect" in ESPWEBTOOL</li>
+<li>Remove all flash entries except one</li>
+<li>Flash the <code>.bin</code> file at address <code>0x0</code></li>
+</ol>
+<p>Alternatively, use <a href="https://github.com/espressif/esptool">esptool</a> from the command line: <code>esptool.py --chip esp32s2 write_flash 0x0 firmware.bin</code></p>
+<p><a href="/firmware/fancontroller-r3-1-esp32s2.factory.bin">Download prebuilt binary</a></p>
+</details>
 
 ## Example Configurations
 
diff --git a/static/fancontroller-rev3.2.md b/static/fancontroller-rev3.2.md
@@ -37,19 +37,25 @@ toc_icon: "microchip"
 Rev 3.2 improves upon Rev 3.1 with enhanced USB protection:
 - Improved USB-C fuse for better overcurrent protection
 - Enhanced USB resilience and safety
-- Same firmware and pin configuration as Rev 3.1
+- Compatible firmware and pinout — hardware improvements only
 
 ## Generic Firmware Installation
 
 <esp-web-install-button manifest="firmware/fancontroller-r3-1.manifest.json"></esp-web-install-button>
 
-> **Note:** ESP32-S2 boards may have connectivity issues with web-based flashing. If browser flash fails, use [esptool](https://github.com/espressif/esptool) for reliable flashing:
->
-> ```bash
-> esptool.py --chip esp32s2 write_flash 0x0 firmware.bin
-> ```
->
-> [Download prebuilt binary](/firmware/fancontroller-r3-1-esp32s2.factory.bin)
+<details>
+<summary>⚠️ USB flashing not working? (ESP32-S2 known issue)</summary>
+<p>The ESP32-S2 has known USB reliability issues — there is no permanent fix. If the browser installer fails, use <a href="https://esptool.spacehuhn.com/">ESPWEBTOOL by Spacehuhn</a> as a fallback:</p>
+<ol>
+<li>Connect the board via USB-C</li>
+<li>Hold BOOT, press RESET to enter boot mode</li>
+<li>Click "Connect" in ESPWEBTOOL</li>
+<li>Remove all flash entries except one</li>
+<li>Flash the <code>.bin</code> file at address <code>0x0</code></li>
+</ol>
+<p>Alternatively, use <a href="https://github.com/espressif/esptool">esptool</a> from the command line: <code>esptool.py --chip esp32s2 write_flash 0x0 firmware.bin</code></p>
+<p><a href="/firmware/fancontroller-r3-1-esp32s2.factory.bin">Download prebuilt binary</a></p>
+</details>
 
 ## Example Configurations
 
diff --git a/static/fancontroller-rev3.3.md b/static/fancontroller-rev3.3.md
@@ -38,21 +38,27 @@ Rev 3.3 includes hardware improvements over Rev 3.2:
 - Open-drain fan outputs instead of push-pull for better fan compatibility
 - Optimized component selection for better availability
 - Enhanced power supply stability
-- Same firmware and pin configuration as Rev 3.1 and 3.2
+- Compatible firmware and pinout — hardware improvements only
 
-All three revisions (3.1, 3.2, 3.3) share identical firmware and functionality.
+Rev 3.1, 3.2, and 3.3 share the same firmware and pinout — differences are hardware-only.
 
 ## Generic Firmware Installation
 
 <esp-web-install-button manifest="firmware/fancontroller-r3-1.manifest.json"></esp-web-install-button>
 
-> **Note:** ESP32-S2 boards may have connectivity issues with web-based flashing. If browser flash fails, use [esptool](https://github.com/espressif/esptool) for reliable flashing:
->
-> ```bash
-> esptool.py --chip esp32s2 write_flash 0x0 firmware.bin
-> ```
->
-> [Download prebuilt binary](/firmware/fancontroller-r3-1-esp32s2.factory.bin)
+<details>
+<summary>⚠️ USB flashing not working? (ESP32-S2 known issue)</summary>
+<p>The ESP32-S2 has known USB reliability issues — there is no permanent fix. If the browser installer fails, use <a href="https://esptool.spacehuhn.com/">ESPWEBTOOL by Spacehuhn</a> as a fallback:</p>
+<ol>
+<li>Connect the board via USB-C</li>
+<li>Hold BOOT, press RESET to enter boot mode</li>
+<li>Click "Connect" in ESPWEBTOOL</li>
+<li>Remove all flash entries except one</li>
+<li>Flash the <code>.bin</code> file at address <code>0x0</code></li>
+</ol>
+<p>Alternatively, use <a href="https://github.com/espressif/esptool">esptool</a> from the command line: <code>esptool.py --chip esp32s2 write_flash 0x0 firmware.bin</code></p>
+<p><a href="/firmware/fancontroller-r3-1-esp32s2.factory.bin">Download prebuilt binary</a></p>
+</details>
 
 ## Example Configurations
 
diff --git a/static/index.md b/static/index.md
