Smart Home

Overview

FERAL integrates with your smart home through two paths: Home Assistant for broad device compatibility, and direct HUP mesh for low-latency local control of supported devices. Both paths let you control hardware via natural language.

Home Assistant Integration

Ensure Home Assistant is running

FERAL connects to Home Assistant’s WebSocket API. Your HA instance must be accessible on the local network.

Create a long-lived access token

In Home Assistant, go to your profile → Long-Lived Access Tokens → Create Token. Copy the token.

Configure FERAL

settings.json

{
  "hardware": {
    "home_assistant": {
      "enabled": true,
      "url": "http://192.168.1.50:8123",
      "token": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

Or via environment variables:

export FERAL_HA_URL="http://192.168.1.50:8123"
export FERAL_HA_TOKEN="eyJhbGciOiJIUzI1NiIs..."

Verify device discovery

feral devices
# …or directly against the brain:
curl http://localhost:9090/api/home-assistant/entities

Home Assistant (192.168.1.50)
  ● light.living_room       Living Room Light       on  brightness: 80%
  ● climate.thermostat       Thermostat             heat  temp: 22°C
  ● lock.front_door          Front Door Lock         locked
  ● switch.coffee_machine    Coffee Machine          off
  ● media_player.tv          Living Room TV          idle

Direct HUP Mesh Control

For supported devices, FERAL can bypass Home Assistant and control hardware directly over the local network or BLE using the Hardware Unified Protocol.

settings.json

{
  "hardware": {
    "hup_port": 9091,
    "mesh_devices": [
      {
        "id": "hue_bridge",
        "type": "philips_hue",
        "host": "192.168.1.42"
      },
      {
        "id": "smart_plug_1",
        "type": "tasmota",
        "host": "192.168.1.88"
      }
    ]
  }
}

Direct mesh control has lower latency than Home Assistant (~50ms vs ~200ms) because it eliminates the middleware hop.

Supported Device Types

Category	Devices	Actions
Lights	Philips Hue, LIFX, Tasmota, any HA light	On/off, brightness, color, color temp, scenes
Thermostat	Nest, Ecobee, any HA climate	Set temp, mode (heat/cool/auto), fan
Locks	August, Yale, any HA lock	Lock, unlock, status check
Appliances	Smart plugs, switches	On/off, power monitoring
Media	TVs, speakers, any HA media_player	Play, pause, volume, source selection
Sensors	Motion, door/window, temperature, humidity	Read-only monitoring and triggers

Natural Language Control

Once connected, you can control devices through conversation:

"Dim the living room lights to 30%"
"Set the bedroom lights to warm white"
"Turn off all lights"

"Set the temperature to 72°F"
"Switch to cooling mode"
"What's the current temperature?"

"Lock the front door"
"Is the back door locked?"

"Movie time" → dims lights, turns on TV, sets volume
"Goodnight" → locks doors, turns off all lights, sets thermostat to 68°F

Scenes and Automations

Define custom scenes in your settings that FERAL can trigger by name:

settings.json

{
  "hardware": {
    "scenes": {
      "movie_time": [
        { "entity": "light.living_room", "action": "turn_on", "brightness": 15 },
        { "entity": "media_player.tv", "action": "turn_on" }
      ],
      "goodnight": [
        { "entity": "lock.front_door", "action": "lock" },
        { "entity": "light.*", "action": "turn_off" },
        { "entity": "climate.thermostat", "action": "set_temperature", "temperature": 20 }
      ]
    }
  }
}

Proactive Smart Home

With the proactive engine enabled, FERAL can act on smart-home devices automatically:

Sleep detected (from wristband) → dim lights, lock doors, lower thermostat
Heart rate spike during rest → adjust lighting to calming colors
Calendar: meeting in 5 min → mute media players
Leaving home (geofence exit) → turn off lights, lock all doors

Proactive smart-home actions respect your autonomy level. In strict mode, you’ll get an approval card before any action executes.

Troubleshooting

Home Assistant connection refused

Verify the URL and token. Ensure HA is running and the API is accessible: curl -H "Authorization: Bearer YOUR_TOKEN" http://HA_IP:8123/api/.

Device not found

Run feral devices (or curl http://localhost:9090/api/home-assistant/entities) to refresh. If using HA, make sure the device is exposed and not hidden in the HA UI.

Commands execute with delay

If latency exceeds 500ms, consider switching to direct HUP mesh control for supported devices.

Overview

Getting Started

Guides

Marketplace

Memory

Hardware

Channels

Connectivity

Security

Native Apps

Operations

SDKs

Reference

Help

Community

Overview

Home Assistant Integration

Direct HUP Mesh Control

Supported Device Types

Natural Language Control

Scenes and Automations

Proactive Smart Home

Troubleshooting

​Overview

​Home Assistant Integration

​Direct HUP Mesh Control

​Supported Device Types

​Natural Language Control

​Scenes and Automations

​Proactive Smart Home

​Troubleshooting

Overview

Home Assistant Integration

Direct HUP Mesh Control

Supported Device Types

Natural Language Control

Scenes and Automations

Proactive Smart Home

Troubleshooting