FIFantom Interio
Docs/ESP32_CONNECT_GUIDE.md
← All docs
MarkdownHTML Render

ESP32 Quick Connect

5-step Mac → Chrome → ESP32 connection guide with voice control setup.

Quick Connect Guide — ESP Board to Fantom Interio Smart Home Hub

Works for: ESP8266 NodeMCU, Wemos D1 Mini, ESP32 DevKit V1, and ALL ESP32-S2/S3/C3/C6/H2 boards Time: 5 minutes (after firmware is uploaded)

Before You Start

Make sure you've done these:

  • ESP board has the Fantom Interio firmware uploaded (see ESP32_QUICKSTART.md)
  • Both the board AND your phone/computer are on the same WiFi
  • You're using Google Chrome or Microsoft Edge (not Firefox/Safari)

5-Step Connection

Step 1 — Go to Smart Home Hub

In the Fantom Interio app, click Smart Home Hub in the navigation.

Step 2 — Click "Connections" Tab

You'll see connection panels for different platforms.

Step 3 — Expand "ESP32 / ESP8266"

Click on it to see the connection options. You'll see a chip strip showing all supported boards.

Step 4 — Choose How to Connect

Option 0 — 🤖 Smart Auto Agent (Recommended — Does Everything For You)

  • At the top of the Connections tab, find the "Smart Auto Agent" section
  • Enter the admin PIN (default: 1234) to unlock
  • Click "Start Full Auto-Setup"
  • The agent automatically:
    1. Scans USB, network, MQTT, and Home Assistant for your boards
    2. Connects to the best available board with real signal verification
    3. Discovers all devices attached to the board
    4. Tests relays one by one with visual confirmation
    5. Creates rooms and assigns devices automatically
    6. Binds voice commands so you can say "lights on" instantly
  • A live green pulse confirms real connection — no fake "connected" status
  • On-screen overlay hints guide you if wiring or permission steps are needed

Option A — ⚡ Auto-Find (Easiest, try this first!)

  • Just click "⚡ Auto-Find & Connect"
  • The app tries USB detection, then scans your WiFi
  • Board type is shown automatically (ESP8266 NodeMCU / ESP32 DevKit V1 / etc.)

Option B — 🔌 USB Detect (Board plugged in via USB)

  • Keep the USB cable connected to your computer
  • Click the USB Detect tab → click "Detect Board via USB"
  • Chrome shows a port picker — select your board
  • App reads IP directly from the board and connects

Option C — 📡 Network Scan

  • Click the Network Scan tab → click "Scan 192.168.1.0/24"
  • App scans your local network for the board

Option D — ✏️ Manual IP (If all else fails)

  • Click the Manual IP tab
  • Select your board type from the selector
  • Type the IP address you saw in Serial Monitor (like 192.168.1.107)
  • Click Connect

Step 5 — You're Connected!

  • Status dot goes green
  • Board name badge appears (e.g. "ESP8266 NodeMCU" or "ESP32 DevKit V1")
  • Devices are imported automatically
  • Try toggling a device to test!

Say Voice Commands

Go to Control tab → click "🎤 Start Voice Command" → say:

Say What Happens
"Lights on" All lights on
"Lights off" All lights off
"Fan on" / "Fan off" Fan control
"All off" Everything off
"Good morning" Morning scene
"Good night" Evening scene
"Movie mode" Entertainment scene

Offline vs Online

Everything works without internet — your board talks directly to your browser over your home WiFi. Voice control also works offline (Chrome processes it locally).

Only MQTT cloud mode requires internet, and that's optional.

Connection Problems?

Symptom Solution
Auto-find fails Board and device on different WiFi networks? Use same network.
"Port already open" error Fixed in latest code — the app now closes ports before reopening. If you still see this, refresh the page.
"WebSerial not available" Switch to Chrome or Edge
Status stuck at "Connecting" Try Manual IP with the number from Serial Monitor
Smart Auto Agent shows "error" Check that your board is powered and on the same WiFi. Click retry to restart discovery.
Voice says "Demo mode" Click mic button and allow microphone permission
Devices missing after connect Firmware must support the list command — use latest firmware from ESP32_QUICKSTART.md
Connection drops Firmware has WiFi.setSleep(false) — re-upload if needed

How It Works (For the Curious)

[ Chrome / Fantom Interio App ]  ←── WebSocket (ws://192.168.x.x:81) ──→  [ ESP Board ]
       |                                                                  |
  You tap a device                                               Relay clicks
  in the app                                                     Light goes on/off
  
  All on your local WiFi — no cloud, no internet needed!

The app sends a tiny JSON message to the board:

{ "deviceId": "d1", "isOn": true }

The board switches the relay and sends back:

{ "deviceId": "d1", "isOn": true, "watts": 12 }

That's it. Super simple, super fast (under 10ms response time on local WiFi).

Need Help?

Tap the glowing orb on any screen to ask the Fantom Interio AI assistant! It knows everything about setting up ESP boards and smart home devices.

← Back to all docsDownload Markdown ↗