GitHub - Bonbon604/spiderfarmer-bridge

Local bridge between the Spider Farmer GGS Controller and Home Assistant via MQTT Discovery.

A Raspberry Pi acts as a Wi-Fi hotspot for the GGS Controller, intercepts the encrypted MQTT traffic, normalizes the data, and exposes it to Home Assistant. The official Spider Farmer app and cloud keep working in parallel.

GGS Controller
     │  Wi-Fi (hotspot from the Pi)
     ▼
Raspberry Pi ──── TLS MITM Proxy :8883
     │                      │
     │  eth0 (LAN)      Mosquitto :1883
     │                      │
     ▼                      ▼
  SF Cloud            Home Assistant
  (app keeps          (entities auto-
   working)            discovered)

What you get

Once the GGS Controller is connected, entities show up in HA automatically — depending on what's plugged into the controller:

Type	Entities
Sensor	Air Temperature, Humidity, VPD, CO₂, PPFD
Sensor	Soil Temperature / Humidity / EC (average + per-sensor)
Light	Light 1, Light 2 (on/off, brightness, modes: Manual / Schedule / PPFD)
Fan	Fan Exhaust (on/off + 0-100 % speed)
Fan	Fan Circulation (on/off + 0-10 speed levels)
Switch	Heater, Humidifier, Dehumidifier
Switch	Outlet 1-10 (count depends on which Power Strip is connected)

Plus every mode-specific setting as its own sub-device entity (schedule brightness, PPFD target, fan cycle run-time, environment submode, …) — there's no setting in the SF App that's not also exposed in HA.

Lovelace Card

Custom HA card that mirrors the SF App's per-device control with a tab per device, a mode dropdown, and the matching settings panel below:

Three install paths (see Card install guide for full details):

HA Addon (Option A below): card auto-installs together with the addon. No extra clicks.
HACS: add this repository as a custom Frontend repo, install Spider Farmer GGS Card.
Manual: npm run build, copy file, register the resource.

In a dashboard:

type: custom:ggs-card
device_id: ggs_1
layout_options:
  grid_columns: 48
  grid_rows: 12
slider_min:
  light: 11
  fan_circulation: 10
  fan_exhaust: 25

Note: the slider_min defaults reflect typical SF GGS hardware. If your setup has different floors (e.g. a different exhaust fan that already spins at 15 %), adjust the values or set them to 0.

What hardware do I need?

Part	What it does
Raspberry Pi with Wi-Fi (Pi 3, Pi 4, Pi 5, or Zero 2 W)	Runs as the bridge between the controller and HA
Ethernet cable	Mandatory — the Pi must reach your network over LAN because the Wi-Fi adapter is dedicated to the GGS hotspot
Spider Farmer GGS Controller	The thing you want to control (CB, PS5, PS10, or LC)
Home Assistant	On the same Pi or a separate device on the same network

Two ways to set the Pi up:

Option A — Pi runs Home Assistant OS and SpiderBridge is installed as an addon. Recommended for most users. Pi and HA are the same device.
Option B — Pi runs Raspberry Pi OS with SpiderBridge as a standalone service. HA runs separately (second Pi, NUC, VM, whatever). The "classic" setup.

Pick one — the rest of the guide is split per option.

Option A — HA Addon setup (recommended)

Prerequisite: You already have Home Assistant OS installed on the Pi. If not yet — see https://www.home-assistant.io/installation/raspberrypi for the initial install, then come back here.

Make sure: the Pi is connected to your router by Ethernet cable. The Wi-Fi interface is going to be used for the hotspot, so cabled internet is required.

Step 1 — Add the repository in HA

Open Home Assistant in your browser.
Click your profile icon (bottom left) → make sure "Advanced Mode" is on (otherwise you can't see the full Add-on Store).
Sidebar: Settings → Add-ons → bottom right click "Add-on Store".
Top right click ⋮ (three dots) → "Repositories".
In the popup paste this URL: https://github.com/iceboerg00/spiderfarmer-bridge
Click Add → Close.

Step 2 — Install the addon

Scroll down in the Add-on Store → find the "SpiderBridge Add-ons" section → click SpiderBridge.
Click Install (takes 1-2 min — the Pi builds the card too).

Step 3 — Configure

On the addon page open the Configuration tab. Fields:

Field	What to enter
`ssid`	Name of the Wi-Fi for the GGS Controller, freely chosen (e.g. `GGS-Tent`)
`password`	Wi-Fi password, at least 8 characters (e.g. `SuperSafe123`)
`channel`	`6` is a safe default (any number from 1 to 11)
`hotspot_ip`	Leave at `192.168.10.1`, change only if that subnet is already used in your network
`hotspot_enabled`	Leave at `true` (Pi runs the hotspot itself — recommended)

The HA device name is hardcoded to GGS so entity IDs end up as light.ggs_light_1, fan.ggs_fan_circulation, … This is what the Lovelace card expects — renaming it would break the card.

Click Save (top right).

Step 4 — Start the addon

Open the Info tab → click Start.
Enable Watchdog and Start on boot (so it comes back up automatically after a reboot).
Open the Log tab — you should see lines like Hotspot enabled, Proxy listening on 0.0.0.0:8883. If you see errors, jump to Troubleshooting.

Step 5 — Configure the MQTT integration

After the addon starts, Home Assistant shows a notification: "SpiderBridge offers an MQTT broker — configure?"

Click it → Submit. That's it. Internally this configures HA's standard MQTT integration to point at the addon's local Mosquitto, and MQTT Discovery handles the rest — every Spider Farmer device the bridge sees becomes a HA entity automatically.

If you don't see the notification: Settings → Devices & services → Add Integration → MQTT → Submit (HA prefills the broker details from the addon).

Step 6 — Connect the GGS Controller

In the Spider Farmer app on your phone, switch the GGS Controller's Wi-Fi over to the network you created in Step 3 (the SSID + password from there). On first connect the MAC is auto-detected.

In the addon log you should see something like:

🕷  SpiderBridge — device detected
   MAC: 7C2C67F03DAC
   ID:  GGS Tent

Entities appear in HA from that moment on — usually within 10-20 seconds.

Step 7 — Add the card to a dashboard

Hard-refresh the browser — Ctrl+F5 (Mac: Cmd+Shift+R) — so HA loads the freshly installed card.
Open a dashboard → Edit Dashboard → + Add Card → search "Spider Farmer" → done.

Option B — Standalone Pi running Raspberry Pi OS

Prerequisite: You have Raspberry Pi OS (64-bit) installed on the Pi and SSH access. If not yet — https://www.raspberrypi.com/software/ for the imager. Enable SSH in the imager options or by dropping an empty ssh file on the SD card.

Make sure: Pi is connected to your router by Ethernet cable. Same reason as Option A.

Step 1 — SSH to the Pi

On your main computer open a terminal:

ssh pi@<pi-ip>

(IP from your router's device list or via nmap. Default user is usually pi or whatever you set in the imager.)

Step 2 — Run the one-line installer

On the Pi (in the SSH terminal):

curl -sSL https://raw.githubusercontent.com/iceboerg00/spiderfarmer-bridge/master/setup/bootstrap.sh | sudo bash

The installer:

Clones the repo to /opt/spiderfarmer-bridge.
Starts a setup wizard that asks for:
- SSID — name of the Wi-Fi for the GGS Controller (e.g. GGS-Tent)
- Password — at least 8 characters
Sets up Mosquitto, Python venv, TLS certificates, and the pm2-managed services (sf-proxy, sf-discovery). The device name is hardcoded to GGS so entity IDs end up consistent (light.ggs_light_1, fan.ggs_fan_circulation, …) — required for the Lovelace card to find them.
Configures the Wi-Fi hotspot with the stability tweaks the GGS Controller needs (powersave off, PMF disabled).

Takes 3-5 minutes. When it's done, sudo pm2 status should show two services online.

Step 3 — Connect HA to the Pi

On your HA device:

Settings → Devices & services.
If MQTT isn't set up yet: + Add Integration → MQTT → click.
In the configuration popup:
- Broker: IP of the Pi (its Ethernet address, e.g. 192.168.1.100)
- Port: 1883
- Username/Password: leave empty
Submit.

If MQTT is already wired to a different broker: you can run two brokers in parallel, or define the Pi's broker as an additional one in YAML — see HA's MQTT docs.

Step 4 — Connect the GGS Controller

In the Spider Farmer app, switch the controller's Wi-Fi to the network from the wizard.

Watch the logs on the Pi:

sudo pm2 logs sf-proxy --lines 50

A line like 🕷 SpiderBridge — device detected MAC: ... confirms it's working.

A few seconds later the entities show up in HA under the device named GGS.

Step 5 — Card on the dashboard

In Option B the card does not auto-install — use HACS or the manual route. See Card install guide Option B or C.

Updates

Option A (addon)

Settings → Add-ons → SpiderBridge → if "Update available" shows, click Update.
Click Restart.
Ctrl+F5 in the browser (the card may have updated too).

Option B (standalone)

sudo /opt/spiderfarmer-bridge/update.sh

update.sh handles git fetch, git pull (only if the remote moved), and the pm2 restart in one step. It always restarts the services even if nothing was pulled, so a previously-failed restart doesn't leave you stuck on stale code.

For the card after an update: HACS → "Spider Farmer GGS Card" → Update, or manually npm run build + copy the file again.

Troubleshooting

Controller doesn't connect to the hotspot

The GGS Controller is 2.4 GHz only — pick a channel between 1 and 11.
Option A: check the addon log for AP-ENABLED.
Option B: nmcli con show SF-Bridge-Hotspot | grep band. Make sure 802-11-wireless.powersave is 2 (disabled) — otherwise the controller drops daily.

No data in Home Assistant

Option A: addon log → look for Proxy listening on 0.0.0.0:8883.
Option B: sudo pm2 logs sf-proxy --lines 100.

Inspect MQTT topics directly:

mosquitto_sub -h <pi-ip> -p 1883 -t 'spiderfarmer/#' -v

HA outlet toggle doesn't switch the PS5/PS10

The proxy needs to see one cloud→device packet first to learn the controller's MQTT topic prefix. Easiest trigger: tap one outlet once in the SF App on your phone — afterwards the prefix is locked for the session.
sudo pm2 logs sf-proxy | grep "DOWN topic prefix" — once the line DOWN topic prefix learned: PS (was CB) appears, it's ready.

Entities show as "unavailable"

Heater / Humidifier / Dehumidifier appear only after the controller reports their state.
Option A: Restart the addon.
Option B: sudo pm2 restart sf-discovery.

Card doesn't appear under "+ Add Card"

Hard-refresh the browser — Ctrl+F5.
HA → Settings → Dashboards → ⋮ → Resources → check that /local/ggs-card.js is listed as a JavaScript Module. If not: add it manually (URL /local/ggs-card.js, type "JavaScript Module").

MQTT integration not configured after addon install (Option A)

HA usually shows a "SpiderBridge offers an MQTT broker" notification right after the addon starts. If you missed it: Settings → Devices & services → + Add Integration → MQTT and submit; the broker details are prefilled.
If you previously had the addon installed in 1.5.x or earlier, remove the old "SpiderBridge" custom integration entry under Settings → Devices & services before adding MQTT — the old shim is gone in 1.6.0.

Pro tips (Option B)

Services are managed by pm2, not systemd:

sudo pm2 status                       # service state
sudo pm2 logs sf-proxy                # live log
sudo pm2 logs sf-proxy --lines 200    # last 200 lines
sudo pm2 restart sf-proxy             # restart proxy
sudo pm2 restart sf-discovery         # restart discovery service

See every MQTT topic the bridge publishes:

mosquitto_sub -h localhost -p 1883 -t 'spiderfarmer/#' -v

Run the backend tests:

cd /opt/spiderfarmer-bridge
.venv/bin/pytest tests/ -v

Supported modules

Module	Sensors / Lights	Outlets	HA control
Control Box (CB)	Air, soil, CO₂, PPFD, lights, fans, climate accessories	—	full
Power Strip 5 (PS5)	Air sensors, lights, blower / fan	5	full
Power Strip 10 (PS10)	Air sensors, lights, blower / fan	10	full
Light Controller (LC)	2 light channels with brightness, mode, PPFD	—	partial

Multiple modules on the same controller work simultaneously — entities are auto-discovered for each.

Project structure

spiderfarmer-bridge/
├── proxy/                 # MQTT parser, normalizer, command handler, MITM proxy
├── ha/                    # HA Discovery payloads + publisher
├── config/                # config.yaml, mosquitto.conf
├── setup/                 # bootstrap.sh, install.sh, wizard.sh, hotspot.sh
├── certs/                 # TLS certificates
├── tests/                 # backend tests (pytest)
├── docs/                  # README assets (screenshot, etc.)
├── spiderbridge/          # HA addon (Option A)
│   ├── config.yaml
│   ├── Dockerfile         # multi-stage build that includes the frontend
│   ├── app/               # Python code for the container
│   ├── frontend/          # Lovelace card (TypeScript + Lit)
│   └── rootfs/            # s6 service scripts + auto-install of the card
├── hacs.json              # HACS Frontend repo metadata
└── repository.yaml        # HA custom-repository metadata

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
certs		certs
config		config
docs		docs
ha		ha
proxy		proxy
setup		setup
spiderbridge		spiderbridge
tests		tests
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
ecosystem.config.js		ecosystem.config.js
hacs.json		hacs.json
logo.png		logo.png
main_discovery.py		main_discovery.py
main_proxy.py		main_proxy.py
repository.yaml		repository.yaml
requirements.txt		requirements.txt
start.sh		start.sh
stop.sh		stop.sh
update.sh		update.sh

Navigation Menu

Repository files navigation

What you get

Lovelace Card

What hardware do I need?

Option A — HA Addon setup (recommended)

Step 1 — Add the repository in HA

Step 2 — Install the addon

Step 3 — Configure

Step 4 — Start the addon

Step 5 — Configure the MQTT integration

Step 6 — Connect the GGS Controller

Step 7 — Add the card to a dashboard

Option B — Standalone Pi running Raspberry Pi OS

Step 1 — SSH to the Pi

Step 2 — Run the one-line installer

Step 3 — Connect HA to the Pi

Step 4 — Connect the GGS Controller

Step 5 — Card on the dashboard

Updates

Option A (addon)

Option B (standalone)

Troubleshooting

Controller doesn't connect to the hotspot

No data in Home Assistant

HA outlet toggle doesn't switch the PS5/PS10

Entities show as "unavailable"

Card doesn't appear under "+ Add Card"

MQTT integration not configured after addon install (Option A)

Pro tips (Option B)

Supported modules

Project structure

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

What you get

Lovelace Card

What hardware do I need?

Option A — HA Addon setup (recommended)

Step 1 — Add the repository in HA

Step 2 — Install the addon

Step 3 — Configure

Step 4 — Start the addon

Step 5 — Configure the MQTT integration

Step 6 — Connect the GGS Controller

Step 7 — Add the card to a dashboard

Option B — Standalone Pi running Raspberry Pi OS

Step 1 — SSH to the Pi

Step 2 — Run the one-line installer

Step 3 — Connect HA to the Pi

Step 4 — Connect the GGS Controller

Step 5 — Card on the dashboard

Updates

Option A (addon)

Option B (standalone)

Troubleshooting

Controller doesn't connect to the hotspot

No data in Home Assistant

HA outlet toggle doesn't switch the PS5/PS10

Entities show as "unavailable"

Card doesn't appear under "+ Add Card"

MQTT integration not configured after addon install (Option A)

Pro tips (Option B)

Supported modules

Project structure

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages