SpiderBridge — your Spider Farmer grow controller, native in Home Assistant.

Flash once, pair once — every value and every setting of your GGS controller lives as a native Home Assistant entity. No cloud. No app. No Raspberry Pi.

SpiderBridge is one ESP32 that sits between your Spider Farmer GGS controller and your Home Assistant. Four links are involved and they do completely different jobs — and the order matters, because each one sets up the next.

Everything starts with a USB data cable and Google Chrome or Microsoft Edge. The installer in your browser talks to the board over the Web Serial API (navigator.serial) — the same cable you plugged in. Nothing else is used to reach the board. Over that one cable the installer:

Bluetooth is not involved on this path at all. Your browser never opens a Bluetooth connection (navigator.bluetooth is never used, not by the installer, not by any page in this repository), and your computer's Bluetooth is never paired with anything. The board is reached by cable, full stop. That is deliberate: flashing, Wi-Fi setup and the console log all work on machines with no Bluetooth at all.

Once setup is done this path is quiet — the bridge still answers on USB for logs, diagnostics and firmware updates, but nothing about your grow flows through it.

The Bluetooth that matters here is the ESP32's own Bluetooth adapter, not your computer's. The bridge is the BLE central: when you ask it to, it restarts into a short Bluetooth-only boot, scans for controllers nearby, and connects to the one you pick.

Over that link it does exactly one job: it hands the controller its new Wi-Fi. The GGS exposes a setup service (0x00FF) with a write characteristic (0xFF02) and a notify characteristic (0xFF01). The bridge writes one AES-128-CBC encrypted JSON frame to it:

{"method":"setWifi","params":{"ssid":"SpiderBridge-xxxx","pass":"<hotspot password>"},"msgId":"…","pid":"…","uid":"…"}

SSID in, password in — that is the entire Bluetooth story. Bluetooth is not the data channel and never carries a single grow value. After that one-time handshake the bridge is done with Bluetooth and the controller switches to Wi-Fi.

This is the real data path, and it has nothing to do with Bluetooth. The bridge runs AP + STA at the same time: it is its own Wi-Fi access point (SpiderBridge-…) and a normal client on your home network.

GGS controller ──Wi-Fi──▶ ESP32 hotspot ──DNS hijack──▶ TLS terminated locally │ MQTT packets parsed │ normalised + published │ your MQTT broker ──▶ Home Assistant ▲ commands go back down the same path

The controller was built to talk to sf.mqtt.spider-farmer.com:8883. The bridge's DNS proxy answers that one name with its own address, so the controller opens its MQTT connection to the bridge. From there:

This path works even with no MQTT broker configured: the bridge then simply sends the commands through the intercepted session instead, and the web interface keeps working.

One controller per bridge at a time: the firmware supports a single active controller session.

If you want the Spider Farmer app or cloud to keep reaching the controller, the bridge can mirror the session onward to the real broker. This is two independent switches, because they stop different things:

Turning NAT off alone does not make the setup local-only — the bridge's own connection to the cloud runs over your home network and bypasses NAT entirely. Both switches have to be off for a genuinely offline setup. With cloud forwarding off the bridge answers the controller itself (CONNACK, SUBACK, PUBACK, PINGRESP), so it stays connected, keeps publishing its status and never settles into a reconnect loop. Home Assistant control keeps working either way — it never used the cloud path.

Link Transport What it carries Always on?

1 Browser → ESP32 USB cable (Web Serial, esptool-js + Improv Serial) Flash firmware, home Wi-Fi, hotspot password, logs Setup and maintenance

2 ESP32 → controller Bluetooth LE (the ESP32's own radio) Hotspot SSID + password, once One-time only

3 Controller → ESP32 → HA Wi-Fi: hotspot + DNS hijack + local TLS + MQTT Every value and every command Always

4 ESP32 → Spider Farmer cloud Wi-Fi uplink, mTLS relay Optional mirroring Switchable, off = fully local

Firmware modules

improv_serial.c — Improv Wi-Fi Serial on the USB port, plus SpiderBridge's own extensions (commands 0x40–0x49): addresses, hotspot password, Bluetooth jobs, restart, diagnostics.

ggs_ble.c — BLE central for the GGS setup service (0x00FF / 0xFF02 / 0xFF01), AES-128-CBC framing, setWifi / setDevActive / setDevDeactive.

wifi_apsta.c — AP + STA at once: the controller's hotspot and your home network.

dns_hijack.c + mitm_proxy.c — the answer that sends the controller's broker lookups to the bridge, the locally terminated TLS session, and the MQTT wire parser.

mqtt_send.c + sf_command_handler.c — the way back: Home Assistant command → complete controller module block → injected frame.

sf_normalizer.c — the controller's JSON → Home Assistant state topics, byte-compatible with the original Python bridge.

ha_mqtt.c + ha_discovery_table.c — the connection to your broker and the MQTT Discovery payloads that make the entities native.

mitm_proxy.c + wan_gate.c — the optional relay to the real Spider Farmer cloud, and the two switches that turn it off.

Why SpiderBridge?

Spider Farmer forces a cloud account, a vendor app, and routes your grow data through their servers. SpiderBridge turns that around: your controller never speaks to a Spider Farmer server again — it talks to a ~€10 ESP32 on your own Wi-Fi, and Home Assistant sees everything as if the controller were a native HA device.

That's it. No command line, no idf.py, no YAML files. The ESP32 fetches the firmware straight from your browser over the USB cable, joins your Wi-Fi, and is reachable from then on at http://192.168.10.1 on its own SpiderBridge hotspot, or at the address it received on your home network — the installer's IP addresses & status tool shows you both.

💡 Tip: If the flash fails with Failed to initialize, hold the BOOT button on the board while clicking Install, and release it as soon as the progress bar starts.

Supported hardware: Any ESP32 with 4 MB flash (WROOM-32, WROVER, DevKitC, NodeMCU). Developed and tested with the QIQIAZI ESP32 NodeMCU Development Board (2-pack, USB-C) — the affiliate link supports the project at no extra cost to you.

Both lights — on/off, brightness, Manual / Schedule / PPFD mode, fade time, dim & off threshold, PPFD target with min/max brightness

Both fans — circulation and exhaust, all modes (Manual / Schedule / Cycle / Environment with temp/humidity priority), oscillation, natural wind, CO₂-closed-while-blower-runs

Climate accessories — heater, humidifier, dehumidifier, individually switchable

10 outlets of the power strips

Day/night cycle — separate temperature, humidity and CO₂ targets plus deadband

13 alarm types — air/substrate temperature & humidity, VPD, CO₂, PPFD, sensor offline, light over-temperature, dehumidifier tank, humidifier water, water leak, water shortage

Grow plans — multi-stage plans from templates, stage labels with start/end, colors, reminders

Sensor calibration — offsets for temperature, humidity, CO₂ and PPFD

Sensor cleaning — with phase status, cool-down time and remaining time

Time & timezone — automatic daylight saving per zone rules or manual, one-click sync to the controller

Bluetooth pairing — pair/unpair button per controller

Live values — air temperature/humidity, CO₂, VPD, PPFD, substrate temperature/humidity/EC, controller uptime, Wi-Fi signal, free memory

MQTT Discovery — 183 native HA entities with zero YAML configuration

Maintenance — live log, syslog, backup/restore, OTA update, watchdogs + safe mode

1. Flash → Open the installer, enter Wi-Fi, click "Install".
2. MQTT → Point the bridge at your broker (or use the Mosquitto add-on).
3. Pair → "Control → Bluetooth: scan" or the "Pair Bluetooth" button in HA.

The full step-by-step guide with troubleshooting lives below in the technical appendix.

One bridge drives one controller at a time, and that controller shows up as its own device with 153 entities in Home Assistant, while the bridge adds 30 more diagnostic entities (clock, timezone, network switches, uplink/hotspot diagnostics, restart, factory reset). All entities are native — use them in dashboards, automations, voice assistants, the energy dashboard and scenes without any YAML.

GGS Controller — controller-page.png (all 153 entities in one capture):

SpiderBridge — bridge-page.png (all 30 entities in one capture):

Pulling the power plug is never the way to restart it. Several independent layers each end in an automatic restart, and the USB console keeps answering throughout:

Tested on a real board with python scripts/reboot_soak.py COM3 --mode fault (crash, hang, watchdog, leak, safe mode) and --mode command (30× restart, ~11 s each, memory stable).

Give a star ⭐ — helps others find the repo.

☕ Buy me a coffee — voluntary, and the same link the firmware's About page shows.

📦 Supported ESP32 board (Amazon) — affiliate link, no extra cost to you.

Technical details (for tinkerers)

Full installation guide (3 steps)

1. Flash the firmware (Wi-Fi credentials included)

Open the Web Installer in Chrome or Edge on a desktop and plug the board in with a USB data cable.

Quick Connect has two buttons with the same flow; only the flash step differs:

Enter your home Wi-Fi and click Select board & start; Chrome opens its serial-port list, you pick the board, and the wizard

A bridge that is already in use (home network set and a controller known) deliberately does not listen for USB commands, because that memory is needed for the controller's connection. Set up only then says so and offers Erase, install firmware and continue; otherwise change Wi-Fi and the hotspot password in the bridge's Web UI. A board with older firmware, or with other firmware, gets an Install firmware and continue button instead.

Already flashed, or want single steps: click Open installer & device tools. The window it opens offers Install, IP addresses & status, Send Wi-Fi to GGS Controller (searches for your Spider Farmer controller over Bluetooth and sends it the bridge's hotspot Wi-Fi), Home Wi-Fi for the bridge, Connect Wi-Fi & randomize SpiderBridge Wi-Fi password, Randomize SpiderBridge Wi-Fi password and Logs & Console. (You can also join the SpiderBridge hotspot and configure Wi-Fi at http://192.168.10.1.)

Leave Module on Auto-detect (or pick your module, like the board list in Tasmota's installer).

💡 Install fails with "Failed to initialize"? Many ESP32 boards cannot enter download mode on their own. Hold the BOOT button while you press Install (or Select board & start) and release it when the progress bar starts.

The wizard's extra commands (IP addresses, hotspot password, quick connect) are SpiderBridge extensions of Improv Wi-Fi Serial (commands 0x40–0x49, see firmware/ggs/main/improv_serial.c); other Improv clients ignore them. All of them travel over the same USB serial link as the flashing and the Wi-Fi credentials. The firmware side is covered by a host test (python firmware/ggs/host_test/run.py) and the installer by node tests/installer_quickconnect.test.mjs and node tests/installer_console.test.mjs; both run in CI before the firmware is built.

The build the installer uses is always the latest successful build from this repository. Released versions are downloadable too — factory image, app image and manifest — from the Releases page, and you can also build and flash any commit yourself (see Build from source).

Auto-detect reads the chip family from the connected board and installs the matching build. The Module list only offers modules that were really built; today that is the classic ESP32 (WROOM-32 / WROVER / DevKitC / NodeMCU, 4 MB flash or more). ESP32-S2/S3/C3/C6 boards are not supported yet, so the installe