QuietCool ESPHome installer

Two paths: (1) replace OEM firmware with custom ESPHome via Web BLE (sections 1–6 below), or (2) open the local firmware page on a hub already running the ESPHome firmware (section at the bottom).

1. Browser check

Checking…

Web BLE works in Chrome / Edge on Android & desktop. Firefox, Safari, and all iOS browsers (including Web-BLE wrappers such as Bluefy) are not supported.

2. What do you want to install?

Both options use the same OEM OTA mechanism — you'll still pick auth, Wi-Fi, etc. below. Both assume the hub is still running OEM firmware. If it's already running the ESPHome firmware, use the device firmware page section at the bottom instead: that firmware still speaks OEM BLE (the stock app keeps working), but its Upgrade command refuses QuietCool's own firmware domains, so this Web-BLE flow can't roll it back to stock.

Flashes the custom ESPHome image hosted alongside this page. Home-Assistant-native, no cloud, and no QuietCool app needed afterwards. Preserves the OEM dual-OTA partition layout so you can still roll back via this same page.

3. How will you authenticate?

The hub rejects every command except Login until a valid pair-id authenticates the session. Pick the path that matches your hub's current state — read this before connecting, because once this page grabs the BLE link, the QuietCool Smart Control app can't talk to the hub at the same time.

Once the QuietCool Smart Control app on Android or iOS pairs with a hub, the factory test ID stops working and the real pair-id isn't user-visible. This path side-steps that by putting the hub into pair mode so we can register a fresh ID.

Pick whichever is easier for you — both end with the hub advertising as pairable for ~tens of seconds:

Method A — physical button
  1. Find the Pair button (KEY2) on the hub. It's the same button used during initial setup.
  2. Press and hold it for 3 or more seconds, then release. LED4 (the pair LED) will change to indicate the hub is pairable.
  3. Come back here and press the Connect & flash button in step 6 below — quickly, the window is short.
Method B — Smart Control app
  1. On a phone with the QuietCool Smart Control app (available on Android and iOS — it needn't be the device running this installer), tap your hub, then tap Pair Mode.
  2. Wait until the app confirms pair mode is active.
  3. Force-close the OEM app (swipe it away in the recents view). The hub only allows one BLE central at a time — leaving the app open will block this page from connecting.
  4. Come back here and press the Connect & flash button in step 6 below.

When you press Connect & flash, this wizard will register a fresh random pair-id with the hub and save it in this browser so you can retry without re-running pair mode if anything goes wrong.

4. Wi-Fi for the hub

The hub will join this network after we connect, then download the new firmware. Fill these in before hitting the button below — once Bluetooth connects, the pair-mode window starts ticking and you want to move fast.

The last-used Pair ID, Wi-Fi SSID, and Wi-Fi password are saved in this browser for future visits when you start a connection. The password is stored unencrypted in this browser profile.

Replacement firmware recovery
If the hub is offline and advertising an Improv setup device, use this recovery action. It only sends the Wi-Fi credentials above—it does not use an OEM pair ID or flash firmware.

5. Firmware URL

6. Flash

Hub must be powered and within ~10 m. If you chose put it into pair mode above, make sure pair mode is active (LED4 indicates this) and the OEM app is force-closed first. The button below opens the Bluetooth device picker, connects, then runs the whole flash sequence without prompting again.

≈3-5 minutes. The hub will disconnect from Bluetooth as soon as flashing begins — that's expected.

Already running the ESPHome firmware?

Open the firmware page served by the hub itself. It can flash a compatible firmware URL or upload a locally saved OEM application .bin. Running the forms on the hub avoids browsers blocking an HTTPS installer from posting to a plain-HTTP LAN device.

For normal project releases, use the Firmware update shown in Home Assistant or at the hub's root page. Shared builds check this site's release manifest automatically. Hubs taken over in ESPHome Device Builder should be updated from Device Builder instead.

No download is required to restore the known OEM V4.1. On the device page, click Use known OEM V4.1, then Download and flash URL; the hub downloads the verified image itself. The local-file form is the version-independent fallback if the vendor URL disappears.

Enter the mDNS name the device announces, or its LAN IP. A port is optional. Do not add a path.

How does this work? / troubleshooting

The button navigates directly to http://<host>/restore-stock. That page uses same-origin requests to the device's /api/flash_url and /api/restore_stock_file endpoints, shows upload progress, and disables its controls while a flash is active.

No auth on this endpoint by default — this is an intentional LAN-trust tradeoff. Home Assistant adoption secures ESPHome API/OTA but does not add web-server authentication. To protect these HTTP endpoints, add auth: { username, password } under web_server: in your build or adopted wrapper.

Common failure modes:

  • Page doesn't open → device hostname doesn't resolve; try the LAN IP instead. The full mDNS name is required, including the MAC suffix (e.g. quietcool-atticfan-abcdef.local, not just quietcool-atticfan).
  • "404 Not Found" → device firmware doesn't have web_server + http_flash_handler wired. Re-flash with a current build that includes them.
  • Update is rejected → the device page shows the endpoint's validation reason. Correct it there and retry.

Caveats

Source & design: quietcool-esphome-native · OEM device QuietCool IT-AF-SMT