Home Assistant provides a platform for home automation. It does so by having modules that observe and trigger actors to do various tasks.

It is currently able to do the following things:

• Track if devices are home by monitoring connected devices to a wireless router (currently supporting modern Netgear routers or routers running Tomato firmware)
• Track which lights are on
• Track what your Chromecasts are up to
• Turn on the lights when people get home when the sun is setting or has set
• Slowly turn on the lights to compensate for light loss when the sun sets and people are home
• Turn off lights and connected devices when everybody leaves the house
• Start YouTube video’s on the Chromecast
• Quit current running application on a Chromecast
• Download files to the host machine
• Open a url in the default browser at the host machine
• Simulate key presses on the host for Play/Pause, Next track, Prev track, Volume up, Volume Down
• Controllable via a REST API and web interface
• Support for thin client Home Assistant instances that will forward all their commands to the main instance
• Android Tasker project to control Home Assistant from your phone and report charging state. Combine it with AutoVoice to be able to tell your phones to turn the lights off!

Current compatible devices:

• Wireless router running Tomato firmware
• Netgear wireless routers (tested with R6300)
• Philips Hue
• Google Chromecast

The system is built modular so support for other wireless routers, other devices or actions can be implemented easily.

• Install python modules PyEphem, Requests and PHue: pip install pyephem requests phue
• Clone the repository and pull in the submodules git clone --recursive https://github.com/balloob/home-assistant.git
• Copy home-assistant.conf.default to home-assistant.conf and adjust the config values to match your setup.
  • For Tomato you will have to not only setup your host, username and password but also a http_id. The http_id can be retrieved by going to the admin console of your router, view the source of any of the pages and search for http_id.
• Setup PHue by running python -m phue --host HUE_BRIDGE_IP_ADDRESS from the commandline.
• While running the script it will create and maintain a file called known_devices.csv which will contain the detected devices. Adjust the track variable for the devices you want the script to act on and restart the script or call the service device_tracker/reload_devices_csv.

Done. Start it now by running python start.py

Home Assistent runs a webserver accessible on port 8123.

• At http://localhost:8123/ it will provide a debug interface showing the current state of the system and an overview of registered services.
• At http://localhost:8123/api/ it provides a password protected API.

A screenshot of the debug interface:

All API calls have to be accompanied by an 'api_password' parameter (as specified in home-assistant.conf) and will return JSON encoded objects. If successful calls will return status code 200 or 201.

Other status codes that can occur are:

• 400 (Bad Request)
• 401 (Unauthorized)
• 404 (Not Found)
• 405 (Method not allowed)

The api supports the following actions:

/api/states - GET
Returns a list of categories for which a state is available

{
    "categories": [
        "Paulus_Nexus_4", 
        "weather.sun", 
        "all_devices"
    ]
}

/api/events - GET
Returns a dict with as keys the events and as value the number of listeners.

{
    "event_listeners": {
      "state_changed": 5,
      "time_changed": 2
    }  
}

/api/services - GET
Returns a dict with as keys the domain and as value a list of published services.

{
    "services": {
      "browser": [
          "browse_url"
      ],
      "keyboard": [
          "volume_up",
          "volume_down"
      ]
    }  
}

/api/states/<category> - GET
Returns the current state from a category

{
    "attributes": {
        "next_rising": "07:04:15 29-10-2013", 
        "next_setting": "18:00:31 29-10-2013"
    }, 
    "category": "weather.sun", 
    "last_changed": "23:24:33 28-10-2013", 
    "state": "below_horizon"
}

/api/states/<category> - POST
Updates the current state of a category. Returns status code 201 if successful with location header of updated resource and the new state in the body.
parameter: new_state - string
optional parameter: attributes - JSON encoded object

{
    "attributes": {
        "next_rising": "07:04:15 29-10-2013", 
        "next_setting": "18:00:31 29-10-2013"
    }, 
    "category": "weather.sun", 
    "last_changed": "23:24:33 28-10-2013", 
    "state": "below_horizon"
}

/api/events/<event_type> - POST
Fires an event with event_type
optional parameter: event_data - JSON encoded object

{
    "message": "Event download_file fired."
}

/api/services/<domain>/<service> - POST
Calls a service within a specific domain.
optional parameter: service_data - JSON encoded object

{
    "message": "Service keyboard/volume_up called."
}

An app has been built using Tasker for Android that:

• Provides buttons to control the lights and the chromecast
• Reports the charging state and battery level of the phone

The APK and Tasker project XML can be found in /android-tasker/

The core of Home Assistant exists of two components; a Bus for calling services and firing events and a State Machine that keeps track of the state of things.

For example to control the lights there are two components. One is the device tracker that polls the wireless router for connected devices and updates the state of the tracked devices in the State Machine to be either 'Home' or 'Not Home'.

When a state is changed a state_changed event is fired for which the light trigger component is listening. Based on the new state of the device combined with the state of the sun it will decide if it should turn the lights on or off:

In the event that the state of device 'Paulus Nexus 4' changes to the 'Home' state:
  If the sun has set and the lights are not on:
    Turn on the lights

In the event that the combined state of all tracked devices changes to 'Not Home':
  If the lights are on:
    Turn off the lights
    
In the event of the sun setting:
  If the lights are off and the combined state of all tracked device equals 'Home':
    Turn on the lights

The light trigger component also registers the service turn_light_on with the Bus. When this is called it will turn on the lights.

By using the Bus as a central communication hub between components it is easy to replace components or add functionality. For example if you would want to change the way devices are detected you only have to write a component that updates the State Machine and you're good to go.

The components have been categorized into two categories:

1 components that observe (implemented in observers.py) 2 components that act on observations or provide services (implemented in actors.py)

track_sun Tracks the state of the sun and when the next sun rising and setting will occur. Depends on: latitude and longitude Action: maintains state of weather.sun including attributes next_rising and next_setting

TomatoDeviceScanner A device scanner that scans a Tomato-based router and retrieves currently connected devices. To be used by DeviceTracker. Depends on: host, username, password and http_id to login to Tomato Router.

DeviceTracker Keeps track of which devices are currently home. Depends on: a device scanner Action: sets the state per device and maintains a combined state called all_devices. Keeps track of known devices in the file known_devices.csv. Will also provide a service to reload known_devices.csv.

HueLightControl A light control for controlling the Philips Hue lights.

LightTrigger Turns lights on or off using a light control component based on state of the sun and devices that are home. Depends on: light control, track_sun, DeviceTracker Action:

• Turns lights off when all devices leave home.
• Turns lights on when a device is home while sun is setting.
• Turns lights on when a device gets home after sun set.

Registers services light_control/turn_light_on and light_control/turn_light_off to turn a or all lights on or off.

Optional service data:

• light_id - only act on specific light. Else targets all.
• transition_seconds - seconds to take to swithc to new state.

media_buttons Registers services that will simulate key presses on the keyboard. It currently offers the following Buttons as a Service (BaaS): keyboard/volume_up, keyboard/volume_down and keyboard/media_play_pause This actor depends on: PyUserInput

file_downloader Registers service downloader/download_file that will download files. File to download is specified in the url field in the service data.

webbrowser Registers service browser/browse_url that opens url as specified in event_data in the system default browser.

chromecast Registers three services to start playing YouTube video's on the ChromeCast.

Service chromecast/play_youtube_video starts playing the specified video on the YouTube app on the ChromeCast. Specify video using video in service_data.

Service chromecast/start_fireplace will start a YouTube movie simulating a fireplace and the chromecast/start_epic_sax service will start playing Epic Sax Guy 10h version.