Python Remote API

In the package homeassistant.remote a Python API on top of the HTTP API can be found.

This page is not a full documentation it’s more a collection of some example. A simple way to get all current entities is to visit the “Set State” page in the “Developer Tools”. For the examples below just choose one from the available entries. Here the sensor sensor.office_temperature and the switch switch.livingroom_pin_2 are used.

First import the module and setup the basics.

import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'password')
print(remote.validate_api(api))

This snippets shows how to use the homeassistant.remote package in another way.

import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'password')
hass = remote.HomeAssistant(api)
hass.start()
living_room = hass.states.get('group.living_room')

Get configuration

Get the current configuration of a Home Asssitant instance.

import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'password')

print(remote.get_config(api))

Get details about services, events, and entitites

Similar to the output in the “Developer Tools” of the frontend.

import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'YOUR_PASSWORD')

print('-- Available services:')
services = remote.get_services(api)
for service in services:
    print(service['services'])

print('\n-- Available events:')
events = remote.get_event_listeners(api)
for event in events:
    print(event)

print('\n-- Available entities:')
entities = remote.get_states(api)
for entity in entities:
    print(entity)

Get the state of an entity

To get the details of a single entity the get_state method is used.

import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
office_temperature = remote.get_state(api, 'sensor.office_temperature')
print('{} is {} {}.'.format(office_temperature.attributes['friendly_name'],
                            office_temperature.state,
                            office_temperature.attributes['unit_of_measurement']
                            )
      )

The output is composed out of the details which are stored for this entity.

Office Temperature is 19 °C.

The exact same thing is working for a switch. The difference is that both entities have different attributes.

import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
switch_livingroom = remote.get_state(api, 'switch.livingroom_pin_2')
print('{} is {}.'.format(switch_livingroom.attributes['friendly_name'],
                         switch_livingroom.state
                         )
      )

Set the state of an entity

Of course, it’s possible to set the state.

import homeassistant.remote as remote
from homeassistant.const import STATE_ON

api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
remote.set_state(api, 'sensor.office_temperature', new_state=123)
remote.set_state(api, 'switch.livingroom_pin_2', new_state=STATE_ON)

The state will be set to those value until the next update occurs.

Blinking all entites of a domain

If you want to turn on all entities of a domain, just use a service which was retrieved by get_services.

import time
import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
domain = 'switch'

remote.call_service(api, domain, 'turn_on')
time.sleep(10)
remote.call_service(api, domain, 'turn_off')

Control a single entity

To turn on or off a single switch. The ID of the entity is needed as attribute.

import time
import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
domain = 'switch'
switch_name = 'switch.livingroom_pin_2'

remote.call_service(api, domain, 'turn_on', {'entity_id': '{}'.format(switch_name)})
time.sleep(5)
remote.call_service(api, domain, 'turn_off', {'entity_id': '{}'.format(switch_name)})

Specify a timeout

The default timeout for an API call with call_service is 5 seconds. Service taking longer than this to return will raise homeassistant.exceptions.HomeAssistantError: Timeout unless provided with a longer timeout.

import homeassistant.remote as remote

api = remote.API('host', 'password')
domain = 'switch'

# Assuming switch.timeout_switch takes 10 seconds to return
switch_name = 'switch.timeout_switch'

# Raises homeassistant.exceptions.HomeAssistantError: Timeout when talking to
remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name})

# Runs withous exception
remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name},
                    timeout=11)

Send a notification

The example uses the jabber notification platform to send a single message to the given recipient in the configuration.yaml file.

import homeassistant.remote as remote

api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
domain = 'notify'
data = {"title":"Test", "message":"A simple test message from HA."}

remote.call_service(api, domain, 'jabber', data)

For more details please check the source of homeassistant.remote.