chenkuansun/mobileclaw/smart-home

Smart Home (Home Assistant) Integration

Role

You help the user control their smart home devices through Home Assistant's REST API. Turn lights on/off, adjust thermostats, check sensor states, and run automations. Keywords: "turn on light", "turn off light", "smart home", "home assistant", "開燈", "關燈", "關冷氣", "開冷氣", "set temperature", "溫度", "device", "sensor"

Setup

The user needs:

1. A running Home Assistant instance (local or Nabu Casa cloud)
2. A long-lived access token: HA > Profile > Long-Lived Access Tokens > Create Token
3. Configure in MobileClaw Settings:

• HA URL: e.g., http://192.168.1.100:8123 or https://xxxxx.ui.nabu.casa
• HA Token: the long-lived access token

API Configuration

• Base URL: {HA_URL}/api
• Required headers on every request:
• Authorization: Bearer {HA_TOKEN}
• Content-Type: application/json

Standard Workflows

Check API Connection

Verify Home Assistant is reachable.

1. Use http tool:

`` http GET {HA_URL}/api/ Headers: Authorization: Bearer {HA_TOKEN} ``

1. Should return {"message": "API running."}

List All Devices and States

Get current state of all entities.

1. Use http tool:

`` http GET {HA_URL}/api/states Headers: Authorization: Bearer {HA_TOKEN} ``

1. Response is an array of entity objects, each with:

• entity_id: e.g., light.living_room, switch.fan, climate.bedroom
• state: e.g., "on", "off", "21.5", "unavailable"
• attributes: brightness, color_temp, friendly_name, etc.

1. Filter by domain prefix to find specific device types:

• Lights: light.*
• Switches: switch.*
• Climate/AC: climate.*
• Sensors: sensor.*
• Covers/blinds: cover.*
• Media players: media_player.*

1. Present a summary: device name, current state, key attributes

Get Single Device State

1. Use http tool:

`` http GET {HA_URL}/api/states/{entity_id} Headers: Authorization: Bearer {HA_TOKEN} ` Example: http GET {HA_URL}/api/states/light.living_room`

1. Returns full state object with attributes

Turn On a Light

1. Use http tool:

`` http POST {HA_URL}/api/services/light/turn_on Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "light.living_room"} ``

1. With brightness (0-255) and color:

`` http POST {HA_URL}/api/services/light/turn_on Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: { "entity_id": "light.living_room", "brightness": 200, "color_temp": 350 } ``

1. With RGB color:

`` Body: { "entity_id": "light.bedroom_strip", "rgb_color": [255, 150, 50], "brightness": 180 } ``

Turn Off a Light

1. Use http tool:

`` http POST {HA_URL}/api/services/light/turn_off Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "light.living_room"} ``

Toggle a Switch

1. Turn on:

`` http POST {HA_URL}/api/services/switch/turn_on Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "switch.bedroom_fan"} ``

1. Turn off:

`` http POST {HA_URL}/api/services/switch/turn_off Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "switch.bedroom_fan"} ``

1. Toggle (flip current state):

`` http POST {HA_URL}/api/services/switch/toggle Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "switch.bedroom_fan"} ``

Set Air Conditioner / Climate Temperature

1. Set target temperature:

`` http POST {HA_URL}/api/services/climate/set_temperature Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: { "entity_id": "climate.living_room_ac", "temperature": 24 } ``

1. Set HVAC mode (cool, heat, auto, off):

`` http POST {HA_URL}/api/services/climate/set_hvac_mode Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: { "entity_id": "climate.living_room_ac", "hvac_mode": "cool" } ``

1. Turn off AC:

`` http POST {HA_URL}/api/services/climate/set_hvac_mode Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: { "entity_id": "climate.living_room_ac", "hvac_mode": "off" } ``

Control Covers (Blinds/Curtains)

1. Open:

`` http POST {HA_URL}/api/services/cover/open_cover Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "cover.living_room_blinds"} ``

1. Close:

`` http POST {HA_URL}/api/services/cover/close_cover Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "cover.living_room_blinds"} ``

1. Set position (0=closed, 100=open):

`` http POST {HA_URL}/api/services/cover/set_cover_position Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "cover.living_room_blinds", "position": 50} ``

Run an Automation or Script

1. Trigger automation:

`` http POST {HA_URL}/api/services/automation/trigger Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "automation.good_night_routine"} ``

1. Run script:

`` http POST {HA_URL}/api/services/script/turn_on Headers: Authorization: Bearer {HA_TOKEN}, Content-Type: application/json Body: {"entity_id": "script.movie_mode"} ``

Read Sensor Data

1. Get a sensor value (temperature, humidity, power, etc.):

`` http GET {HA_URL}/api/states/sensor.living_room_temperature Headers: Authorization: Bearer {HA_TOKEN} ``

1. Response state field contains the value, attributes.unit_of_measurement has the unit
2. Common sensors: temperature, humidity, power_consumption, door/window (binary_sensor), motion (binary_sensor)

Guidelines

• Entity IDs follow the pattern {domain}.{object_id}, e.g., light.kitchen, climate.bedroom_ac
• If the user says a device name like "living room light", search the states list for matching friendly_name
• Always confirm destructive actions (e.g., turning off all lights, locking doors)
• If HA is unreachable, check if the user is on the same network (for local installs)
• Common entity_id prefixes to know: light, switch, climate, cover, media_player, sensor, binary_sensor, automation, script, fan, lock, vacuum
• Temperature units depend on HA config (Celsius or Fahrenheit) — check attributes.unit_of_measurement
• If an entity is "unavailable", the device may be offline or disconnected