Fantom Interio — Smart Home Platform Connections

A complete guide to connecting Fantom Interio with every major smart home platform. All platforms support simulation mode (no setup needed) and live mode (requires configuration).

Platform Comparison

Platform	Protocol	Auth	Local Control	Voice	Free Tier
Home Assistant	REST + WebSocket	Long-lived token	✅ Yes	✅ Yes	✅ Open source
Amazon Alexa	Alexa Smart Home API	OAuth 2.0	❌ Cloud only	✅ Yes	✅ Free skill
Apple Siri / HomeKit	HAP (HomeKit Accessory)	Pairing code	✅ Yes	✅ Siri	✅ Homebridge
Google Home	Google Home SDK	OAuth 2.0	❌ Cloud only	✅ Assistant	⚠️ Limited
MQTT	MQTT 3.1.1 / 5.0	Username + password	✅ Yes	❌ Manual	✅ HiveMQ free
Samsung SmartThings	SmartThings REST	Personal token	❌ Cloud only	✅ Bixby	✅ Free account
Matter / Thread	Matter (IP-based)	Commissioning code	✅ Yes	✅ Multi	✅ Standard

1. Home Assistant (Recommended)

Home Assistant is the best option for local, private, offline-capable control.

Prerequisites

Raspberry Pi 4 (2GB+) or equivalent running Home Assistant OS
Same LAN as your devices
Long-lived access token from your HA profile

Connection Steps

Install Home Assistant OS
```
https://www.home-assistant.io/installation/
```
Flash to SD card with Balena Etcher → boot → open http://homeassistant.local:8123
Create a Long-Lived Access Token
- Open HA → click your profile (bottom-left)
- Scroll to "Long-lived access tokens" → Create token
- Copy and save securely
Configure in Fantom Interio Studio
- Open Studio → Smart Home tab → Integrations
- Click Home Assistant → Configure
- Enter: http://homeassistant.local:8123 and your token
- Or set environment variables:
```
HOMEASSISTANT_URL=http://192.168.1.100:8123
HOMEASSISTANT_TOKEN=your_long_lived_token_here
```

Enable REST API (enabled by default in modern HA)

# configuration.yaml (only if needed for older HA versions)
api:

Test the connection

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://homeassistant.local:8123/api/states

Exposed Fantom Interio Endpoints

GET /api/states — fetch all entity states
POST /api/services/light/turn_on — turn on a light
POST /api/services/switch/turn_off — turn off a switch
POST /api/services/climate/set_temperature — set AC temperature
WebSocket: ws://homeassistant.local:8123/api/websocket — real-time state updates

Firewall Ports

Port	Service
8123	HA REST API + UI
8124	HA WebSocket

2. Amazon Alexa

Alexa integration via the Smart Home Skill API. Fantom Interio runs in simulation mode by default — no Alexa developer account needed for demo use.

Simulation Mode (No Setup)

In Fantom Interio Studio → Smart Home tab → Integrations → Alexa → Configure → Run Type commands like Turn on living room lights — Alexa API responses are simulated locally.

Live Integration (Advanced)

Create an Alexa Smart Home Skill at developer.amazon.com
Set the Endpoint to your Fantom Interio deployment URL
Configure Account Linking with OAuth 2.0
Alexa discovers devices via the Fantom Interio /alexa/discovery endpoint

Add your Alexa skill ARN to:

ALEXA_SKILL_ID=amzn1.ask.skill.your-skill-id
ALEXA_CLIENT_ID=your-oauth-client-id
ALEXA_CLIENT_SECRET=your-oauth-client-secret

Supported Alexa Interfaces

Alexa.PowerController — on/off
Alexa.BrightnessController — light dimming
Alexa.ThermostatController — AC temperature
Alexa.LockController — smart locks
Alexa.SceneController — scenes ("Alexa, activate movie mode")

Example Commands

"Alexa, turn on the living room lights"
"Alexa, set the AC to 24 degrees"
"Alexa, activate movie mode"
"Alexa, turn off everything"
"Alexa, what's the status of my home?"

3. Apple Siri / HomeKit

Siri and HomeKit integration via Homebridge — a lightweight Node.js server that bridges non-HomeKit devices to Apple's ecosystem.

Setup via Homebridge

Install Homebridge on Raspberry Pi or Mac

sudo npm install -g --unsafe-perm homebridge homebridge-ui-x
sudo hb-service install --user homebridge

Open Homebridge UI at http://homebridge.local:8581
Install Fantom Interio plugin (or use homebridge-http for REST bridging)
```
npm install homebridge-http-switch
```

Configure ~/.homebridge/config.json:

{
  "accessories": [
    {
      "accessory": "HTTP-SWITCH",
      "name": "Living Room Lights",
      "onUrl": "http://your-fantom-url/api/devices/light-1/on",
      "offUrl": "http://your-fantom-url/api/devices/light-1/off"
    }
  ]
}

Pair with iPhone — open Home app → Add Accessory → scan the Homebridge QR code

Siri Commands

"Hey Siri, turn on the living room lights"
"Hey Siri, set the temperature to 24°C"
"Hey Siri, I'm going to bed" (triggers Night scene)
"Hey Siri, good morning" (triggers Morning scene)

Simulation Mode in Fantom Interio

Studio → Smart Home → Integrations → Siri → Configure → Run Simulates Siri intent parsing and HomeKit accessory protocol responses.

4. Google Home

Google Home integration via Google Home SDK and Smart Home Actions (cloud-to-cloud).

Simulation Mode (No Setup)

Studio → Smart Home → Integrations → Google → Configure → Run Simulates Google Assistant query/execute/disconnect intents.

Live Integration

Create a project at console.actions.google.com
Set fulfillment URL to https://your-fantom-deployment.vercel.app/api/google-home
Enable Smart Home action type
Configure OAuth 2.0 account linking

Set in .env:

GOOGLE_HOME_CLIENT_ID=your-google-client-id
GOOGLE_HOME_CLIENT_SECRET=your-google-client-secret
GOOGLE_HOME_PROJECT_ID=your-project-id

Supported Traits

action.devices.traits.OnOff — lights, fans, switches
action.devices.traits.Brightness — dimmable lights
action.devices.traits.TemperatureSetting — AC, thermostat
action.devices.traits.LockUnlock — smart locks
action.devices.traits.Scene — scenes

Example Commands

"Hey Google, turn on the lights"
"Hey Google, dim the bedroom lights to 50%"
"Hey Google, set the thermostat to 24"
"Hey Google, activate movie mode"

5. MQTT Broker

MQTT is ideal for local, high-speed, low-latency device control. Works with ESP32, Zigbee2MQTT, and Home Assistant.

Topic Schema (Fantom Interio Standard)

fantom/{projectId}/devices/{deviceId}/state     ← subscribe (read device state)
fantom/{projectId}/devices/{deviceId}/command   ← publish (send command)
fantom/{projectId}/scenes/{sceneId}/run         ← publish (trigger scene)
fantom/{projectId}/energy/summary               ← subscribe (energy data)

Example Payloads

// Command payload
{ "action": "turn_on", "value": 80, "timestamp": 1700000000000 }

// State payload
{ "status": true, "brightness": 80, "watts": 12, "updatedAt": 1700000000000 }

HiveMQ Cloud (Free, Hosted)

Register at hivemq.com/mqtt-cloud-broker
Create a free cluster
Get broker URL: your-cluster.s2.eu.hivemq.cloud

Set credentials:

MQTT_BROKER_URL=mqtts://your-cluster.s2.eu.hivemq.cloud:8883
MQTT_USERNAME=your-hivemq-username
MQTT_PASSWORD=your-hivemq-password
MQTT_CLIENT_ID=fantom-interio

Local Mosquitto (Raspberry Pi)

sudo apt install mosquitto mosquitto-clients
sudo systemctl enable mosquitto

Edit /etc/mosquitto/mosquitto.conf:

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

sudo mosquitto_passwd -c /etc/mosquitto/passwd fantom-user

Test MQTT

# Subscribe
mosquitto_sub -h your-broker -t "fantom/#" -u user -P pass

# Publish
mosquitto_pub -h your-broker -t "fantom/proj1/devices/light-1/command" \
  -m '{"action":"turn_on"}' -u user -P pass

Firewall Ports

Port	Protocol
1883	MQTT (unencrypted)
8883	MQTT over TLS
9001	MQTT over WebSocket

6. Samsung SmartThings

SmartThings integration via the SmartThings REST API (cloud-based).

Simulation Mode

Studio → Smart Home → Integrations → SmartThings → Configure → Run Simulates SmartThings device discovery and command execution.

Live Integration

Create account at account.smartthings.com
Go to My SmartApps → Generate a Personal Access Token

Add token to .env:

SMARTTHINGS_TOKEN=your-personal-access-token

Fantom Interio uses https://api.smartthings.com/v1/devices to list devices
Commands sent via POST https://api.smartthings.com/v1/devices/{id}/commands

Example API Call

# List devices
curl -H "Authorization: Bearer $SMARTTHINGS_TOKEN" \
     https://api.smartthings.com/v1/devices

# Turn on a device
curl -X POST \
     -H "Authorization: Bearer $SMARTTHINGS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"commands":[{"component":"main","capability":"switch","command":"on"}]}' \
     https://api.smartthings.com/v1/devices/{deviceId}/commands

7. Matter / Thread (Next-Gen Standard)

Matter is the new universal smart home standard — supported by Apple, Google, Amazon, and Samsung.

Requirements

Matter controller (Apple HomePod mini, Google Nest Hub, Amazon Echo 4th gen, or Home Assistant with Matter server)
Thread border router for Thread-based devices

Commissioning a Matter Device

Open Fantom Interio Studio → Smart Home → Add Device → Matter
Click Commission — enter the 11-digit setup code from the device box
Or scan the QR code on the device

Home Assistant + Matter Server

# Add Matter Server integration in HA
Settings → Add-ons → Matter Server → Install → Start

# Then in HA Integrations
Settings → Devices & Services → Add Integration → Matter

Firewall Ports

Port	Use
5540	Matter secure channel
5683	COAP for Thread

Offline Modes (No Internet Required)

Mode	Requirement	Latency
ESP32 Direct WebSocket	Same WiFi as ESP32	<5ms
Local MQTT (Mosquitto)	Raspberry Pi on LAN	<10ms
Home Assistant (local)	HA on LAN	<20ms
Homebridge (local)	HomeKit hub on LAN	<30ms
Demo Mode	No devices at all	Instant

Environment Variables Reference

# Home Assistant
HOMEASSISTANT_URL=http://homeassistant.local:8123
HOMEASSISTANT_TOKEN=your_long_lived_token

# MQTT
MQTT_BROKER_URL=mqtts://broker.example.com:8883
MQTT_USERNAME=fantom-user
MQTT_PASSWORD=your-password
MQTT_CLIENT_ID=fantom-interio-app

# Amazon Alexa
ALEXA_SKILL_ID=amzn1.ask.skill.xxxx
ALEXA_CLIENT_ID=your-oauth-client-id
ALEXA_CLIENT_SECRET=your-oauth-client-secret

# Google Home
GOOGLE_HOME_CLIENT_ID=your-client-id
GOOGLE_HOME_CLIENT_SECRET=your-client-secret
GOOGLE_HOME_PROJECT_ID=your-project-id

# Samsung SmartThings
SMARTTHINGS_TOKEN=your-personal-access-token

# Gemini (for voice parsing)
GEMINI_API_KEY=your-gemini-api-key

Troubleshooting

Problem	Likely Cause	Fix
HA connection refused	Wrong IP or port	Try `http://192.168.x.x:8123` instead of hostname
HA token invalid	Token expired or copied wrong	Generate a new long-lived token
MQTT not connecting	Firewall or wrong port	Check port 1883/8883, try `mosquitto_pub` from CLI
Alexa not discovering	Skill not published or wrong ARN	Re-link account in Alexa app
HomeKit not pairing	Homebridge not running	`sudo hb-service status`
Matter commissioning fails	Thread not available	Use WiFi-based Matter device instead

Fantom Interio — Made in Hyderabad 🇮🇳 · All integrations run in simulation mode out of the box.

Smart Home Connections

Fantom Interio — Smart Home Platform Connections

Platform Comparison

1. Home Assistant (Recommended)

Prerequisites

Connection Steps

Exposed Fantom Interio Endpoints

Firewall Ports

2. Amazon Alexa

Simulation Mode (No Setup)

Live Integration (Advanced)

Supported Alexa Interfaces

Example Commands

3. Apple Siri / HomeKit

Setup via Homebridge

Siri Commands

Simulation Mode in Fantom Interio

4. Google Home

Simulation Mode (No Setup)

Live Integration

Supported Traits

Example Commands

5. MQTT Broker

Topic Schema (Fantom Interio Standard)

Example Payloads

HiveMQ Cloud (Free, Hosted)

Local Mosquitto (Raspberry Pi)

Test MQTT

Firewall Ports

6. Samsung SmartThings

Simulation Mode

Live Integration

Example API Call

7. Matter / Thread (Next-Gen Standard)

Requirements

Commissioning a Matter Device

Home Assistant + Matter Server

Firewall Ports

Offline Modes (No Internet Required)

Environment Variables Reference

Troubleshooting