Fantom Interio — Client Onboarding Field Guide

For Fantom Interio technicians visiting client sites. This guide walks you through the full setup process from arrival to handing over the client app.

---

1. Before You Arrive — Checklist

Item	Notes
✅ ESP32-DevKit V1	Flashed with Fantom Interio firmware (see ESP32 Quickstart)
✅ USB-A cable	For initial serial connection via Chrome
✅ Client WiFi credentials	SSID + password for the local network
✅ Laptop (Chrome/Edge)	Required for WebSerial USB auto-detect
✅ Fantom Interio Hub URL	Your deployed URL or local network address
✅ Admin PIN	Default 1234 — change on first login

Firmware flash (if not pre-flashed):

# Install PlatformIO, then:
pio run --target upload
# Serial monitor → note the assigned IP address

---

2. At the Client Site — First 10 Minutes

Step 1: Connect to client WiFi

Connect your laptop and ESP32 to the same network the client will use.

Step 2: Open Fantom Interio Hub

Navigate to your Fantom Interio deployment URL and open Smart Home Hub.

Step 3: Enter Admin Mode

Click the 🔐 lock icon in the top-right header. Enter PIN: 1234 (default) → press Unlock. The header badge will show 🔐 Admin in red.

⚠️ Change the admin PIN immediately on every new site: Click the admin badge → "Change PIN" tab → enter new 4-digit PIN → Save. Write down the new PIN and keep it in your job notes.

Step 4: Run the Setup Wizard

Click 🧭 Setup in the header. Follow the 4-step wizard:

1. Site Info — Enter client name, address, project label
2. Choose Hub — Select ESP32 DevKit V1 (recommended)
3. Connect & Scan — Connect the ESP32, then scan for devices
4. Done — Export setup JSON + install client app

---

3. ESP32 Connection Options

Option A: USB Auto-Detect (fastest)

1. Connect ESP32 via USB to your laptop
2. In ESP32 panel → select USB Auto-Detect
3. Click 🔌 Auto-Detect via USB — Chrome/Edge prompts for port selection
4. Select the COM/ttyUSB port → reads IP from serial automatically
5. Panel connects and shows Connected status

Requires Chrome 89+ or Edge 89+. Won't work in Firefox/Safari.

Option B: Network Scan

1. Connect ESP32 to WiFi, note the subnet (e.g., 192.168.1.x)
2. In ESP32 panel → select Network Scan
3. Click 🔍 Scan Network — scans 192.168.1.1–254 over 5 seconds
4. Found IP populates automatically → click Connect

Option C: Manual IP

1. Flash firmware, open serial monitor (115200 baud)
2. Connect ESP32 to WiFi → note assigned IP (e.g., 192.168.1.105)
3. In ESP32 panel → select Manual IP
4. Enter IP + port (default: 81) → click Connect

---

4. Home Assistant Integration (existing HA installs)

1. Open HA → Profile → Long-Lived Access Tokens → Create Token
2. Copy the token (shown only once)
3. In Fantom Interio Hub → Connections → Home Assistant (admin only)
4. Enter http://homeassistant.local:8123 and paste the token
5. Click Test Connection → on success click Discover Devices
6. Review devices in the discovery modal → select all → Import X Devices

⚠️ Requires admin mode to see HA credentials fields.

---

5. MQTT Broker Connection (admin only)

Free public broker (no account):

Broker: broker.hivemq.com
Port: 8000 (WebSocket)
TLS: off

Local Mosquitto:

Broker: ws://192.168.1.x:9001
Port: 9001

Steps:

1. Connections → MQTT Broker → expand
2. Enter broker URL, port, username (optional)
3. Click 📡 Connect
4. Click Discover Devices → subscribes to fantom/devices/# for 5 seconds
5. Review discovered devices → import selected

---

6. Installing the Client App (Android)

Method A: Chrome "Add to Home Screen" (instant)

1. On the client's Android phone, open Chrome
2. Navigate to: https://your-domain.com/smart-home-hub
3. Tap the ⋮ menu → "Add to Home screen"
4. Tap Add → app icon appears on home screen
5. Tap the icon → opens as full-screen standalone app

The app works offline for device status viewing. Commands require the hub to be reachable on the network.

Method B: Generate real .apk (optional)

For clients who want to install via APK or use the Play Store:

1. Visit pwabuilder.com
2. Enter your Fantom Interio Hub URL → click Start
3. Select Android → click Generate Package
4. Download the .apk (free, no account required)
5. Transfer .apk to client phone → Settings → Allow unknown sources → Install

---

7. Admin vs Client Access

Feature	Admin Mode 🔐	Client Mode (default)
Device controls (on/off, dim, temp)	✅	✅
Scene activation	✅	✅
Voice commands	✅	✅
Add/remove devices	✅	❌
View connection credentials	✅	❌
Configure ESP32 / HA / MQTT	✅	❌
Change admin PIN	✅	❌
AI automation rules creation	✅	View only
Energy history	✅	✅

Leave the client in User Mode (locked) when you hand over the device. The client sees a clean control dashboard with no configuration clutter.

---

8. Exporting & Saving the Setup

After setup is complete:

1. In the Onboarding Wizard Step 4 → click 📋 Export Setup
2. Save the JSON file to your records (includes device list + project info)
3. Email or WhatsApp this file to the client for backup reference

The hub state is also saved automatically in browser localStorage (fantom-hub-storage). No external server required.

---

9. Troubleshooting — Top 8 Issues

Problem	Likely Cause	Fix
USB Auto-Detect fails	Firefox/Safari	Use Chrome 89+ or Edge
ESP32 not found on scan	Different subnet	Check IP range; use Manual IP
HA "Connection refused"	Wrong URL or port	Try http:// not https://; check port 8123
HA token invalid	Token expired or wrong	Re-generate Long-Lived Token in HA
MQTT "Connection failed"	WebSocket port	Use port 8000 for HiveMQ, 9001 for Mosquitto
PWA not installable	No HTTPS	Must be served over HTTPS (except localhost)
Admin PIN forgotten	—	Clear localStorage: localStorage.clear() in DevTools → reload
Devices not persisting	Private/incognito mode	Use regular browser window

---

10. Quick Reference

Default Admin PIN:    1234
Hub localStorage key: fantom-hub-storage
ESP32 WebSocket port: 81 (default)
MQTT public broker:   broker.hivemq.com:8000
HA local URL:         http://homeassistant.local:8123
HA token path:        Profile → Long-Lived Access Tokens
PWA builder:          https://www.pwabuilder.com

---

Fantom Interio — Smart Home Division · Hyderabad