Skip to main content

​
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

1

Ensure Home Assistant is running

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

Create a long-lived access token

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

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..."
4

Verify device discovery

feral hardware list

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

CategoryDevicesActions
LightsPhilips Hue, LIFX, Tasmota, any HA lightOn/off, brightness, color, color temp, scenes
ThermostatNest, Ecobee, any HA climateSet temp, mode (heat/cool/auto), fan
LocksAugust, Yale, any HA lockLock, unlock, status check
AppliancesSmart plugs, switchesOn/off, power monitoring
MediaTVs, speakers, any HA media_playerPlay, pause, volume, source selection
SensorsMotion, door/window, temperature, humidityRead-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"

​
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

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/.
Run feral hardware list to refresh. If using HA, make sure the device is exposed and not hidden in the HA UI.
If latency exceeds 500ms, consider switching to direct HUP mesh control for supported devices.