HASS API Reference

This page provides a list of API calls and specific information related to the HASS plugin.

App Creation

To create apps based on just the AppDaemon base API, use some code like the following:

import hassapi as hass

class MyApp(hass.Hass):

    def initialize(self):

Reference

Services

turn_on(self, entity_id, **kwargs)

Turns on a Home Assistant entity.

This is a convenience function for the homassistant.turn_on function. It can turn on pretty much anything in Home Assistant that can be turned on or run (e.g., Lights, Switches, Scenes, Scripts, etc.).

Parameters:
  • entity_id (str) – Fully qualified id of the thing to be turned on (e.g., light.office_lamp, scene.downstairs_on).
  • **kwargs – Zero or more keyword arguments.
Returns:

None.

Examples

Turn on a switch.

>>> self.turn_on("switch.backyard_lights")

Turn on a scene.

>>> self.turn_on("scene.bedroom_on")

Turn on a light and set its color to green.

>>> self.turn_on("light.office_1", color_name = "green")
turn_off(self, entity_id, **kwargs)

Turns off a Home Assistant entity.

This is a convenience function for the homassistant.turn_off function. It can turn off pretty much anything in Home Assistant that can be turned off (e.g., Lights, Switches, etc.).

Parameters:
  • entity_id (str) – Fully qualified id of the thing to be turned off (e.g., light.office_lamp, scene.downstairs_on).
  • **kwargs – Zero or more keyword arguments.
Returns:

None.

Examples

Turn off a switch.

>>> self.turn_off("switch.backyard_lights")

Turn off a scene.

>>> self.turn_off("scene.bedroom_on")
toggle(self, entity_id, **kwargs)

Toggles between on and off for the selected entity.

This is a convenience function for the homassistant.toggle function. It is able to flip the state of pretty much anything in Home Assistant that can be turned on or off.

Parameters:
  • entity_id (str) – Fully qualified id of the thing to be turned off (e.g., light.office_lamp, scene.downstairs_on).
  • **kwargs – Zero or more keyword arguments.
Returns:

None.

Examples

>>> self.toggle("switch.backyard_lights")
>>> self.toggle("light.office_1", color_name = "green")
set_value(self, entity_id, value, **kwargs)

Sets the value of an input_number.

This is a convenience function for the input_number.set_value function. It can set the value of an input_number in Home Assistant.

Parameters:
  • entity_id (str) – Fully qualified id of input_number to be changed (e.g., input_number.alarm_hour).
  • value (int or float) – The new value to set the input_number to.
  • **kwargs – Zero or more keyword arguments.
Returns:

None.

Examples

>>> self.set_value("input_number.alarm_hour", 6)
set_textvalue(self, entity_id, value, **kwargs)

Sets the value of an input_text.

This is a convenience function for the input_text.set_value function. It can set the value of an input_text in Home Assistant.

Parameters:
  • entity_id (str) – Fully qualified id of input_text to be changed (e.g., input_text.text1).
  • value (str) – The new value to set the input_text to.
  • **kwargs – Zero or more keyword arguments.
Returns:

None.

Examples

>>> self.set_textvalue("input_text.text1", "hello world")
select_option(self, entity_id, option, **kwargs)

Sets the value of an input_option.

This is a convenience function for the input_select.select_option function. It can set the value of an input_select in Home Assistant.

Parameters:
  • entity_id (str) – Fully qualified id of input_select to be changed (e.g., input_select.mode).
  • option (str) – The new value to set the input_select to.
  • **kwargs – Zero or more keyword arguments.
Returns:

None.

Examples

>>> self.select_option("input_select.mode", "Day")
notify(self, message, **kwargs)

Sends a notification.

This is a convenience function for the notify.notify service. It will send a notification to a named notification service. If the name is not specified, it will default to notify/notify.

Parameters:
  • message (str) – Message to be sent to the notification service.
  • **kwargs – Zero or more keyword arguments.
Returns:

None.

Examples

>>> self.notify("Switching mode to Evening")
>>> self.notify("Switching mode to Evening", title = "Some Subject", name = "smtp")
render_template(self, template, **kwargs)

Renders a Home Assistant Template

Parameters:template (str) – The Home Assistant Template to be rendered.
Keyword Arguments:
 None.
Returns:The rendered template in a native Python type.

Examples

>>> self.render_template("{{ states('sun.sun') }}")
Returns (str) above_horizon
>>> self.render_template("{{ is_state('sun.sun', 'above_horizon') }}")
Returns (bool) True
>>> self.render_template("{{ states('sensor.outside_temp') }}")
Returns (float) 97.2

Presence

get_trackers(self, **kwargs)

Returns a list of all device tracker names.

Parameters:**kwargs (optional) – Zero or more keyword arguments.
Keyword Arguments:
 namespace (str, optional) – Namespace to use for the call. See the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter.

Examples

>>> trackers = self.get_trackers()
>>> for tracker in trackers:
>>>     do something
get_tracker_details(self, **kwargs)

Returns a list of all device trackers and their associated state.

Parameters:**kwargs (optional) – Zero or more keyword arguments.
Keyword Arguments:
 namespace (str, optional) – Namespace to use for the call. See the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter.

Examples

>>> trackers = self.get_tracker_details()
>>> for tracker in trackers:
>>>     do something
get_tracker_state(self, entity_id, **kwargs)

Gets the state of a tracker.

Parameters:entity_id – Fully qualified entity id of the device tracker to query, e.g., device_tracker.andrew.
Keyword Arguments:
 namespace (str, optional) – Namespace to use for the call. See the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter.
Returns:The values returned depend in part on the configuration and type of device trackers in the system. Simpler tracker types like Locative or NMAP will return one of 2 states:
  • home
  • not_home

Some types of device tracker are in addition able to supply locations that have been configured as Geofences, in which case the name of that location can be returned.

Examples

>>> trackers = self.get_trackers()
>>> for tracker in trackers:
>>>     self.log("{} is {}".format(tracker, self.get_tracker_state(tracker)))
anyone_home(self, **kwargs)

Determines if the house/apartment is occupied.

A convenience function to determine if one or more person is home. Use this in preference to getting the state of group.all_devices() as it avoids a race condition when using state change callbacks for device trackers.

Parameters:**kwargs (optional) – Zero or more keyword arguments.
Keyword Arguments:
 namespace (str, optional) – Namespace to use for the call. See the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter.
Returns:Returns True if anyone is at home, False otherwise.

Examples

>>> if self.anyone_home():
>>>     do something
everyone_home(self, **kwargs)

Determine if all family’s members at home.

A convenience function to determine if everyone is home. Use this in preference to getting the state of group.all_devices() as it avoids a race condition when using state change callbacks for device trackers.

Parameters:**kwargs (optional) – Zero or more keyword arguments.
Keyword Arguments:
 namespace (str, optional) – Namespace to use for the call. See the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter.
Returns:Returns True if everyone is at home, False otherwise.

Examples

>>> if self.everyone_home():
>>>    do something
noone_home(self, **kwargs)

Determines if the house/apartment is empty.

A convenience function to determine if no people are at home. Use this in preference to getting the state of group.all_devices() as it avoids a race condition when using state change callbacks for device trackers.

Parameters:**kwargs (optional) – Zero or more keyword arguments.
Keyword Arguments:
 namespace (str, optional) – Namespace to use for the call. See the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter.
Returns:Returns True if no one is home, False otherwise.

Examples

>>> if self.noone_home():
>>>     do something

Database

get_history(self, entity_id='', **kwargs)

Gets access to the HA Database.

This is a convenience function that allows accessing the HA Database, so the history state of a device can be retrieved. It allows for a level of flexibility when retrieving the data, and returns it as a dictionary list. Caution must be taken when using this, as depending on the size of the database, it can take a long time to process.

Parameters:
  • entity_id (str) – Fully qualified id of the device to be querying, e.g., light.office_lamp or scene.downstairs_on This can be any entity_id in the database. If this is left empty, the state of all entities will be retrieved within the specified time. If both end_time and start_time explained below are declared, and entity_id is specified, the specified entity_id will be ignored and the history states of all entity_id in the database will be retrieved within the specified time.
  • **kwargs (optional) – Zero or more keyword arguments.
Keyword Arguments:
 
  • days (int, optional) – The days from the present-day walking backwards that is required from the database.
  • start_time (optional) – The start time from when the data should be retrieved. This should be the furthest time backwards, like if we wanted to get data from now until two days ago. Your start time will be the last two days datetime. start_time time can be either a UTC aware time string like 2019-04-16 12:00:03+01:00 or a datetime.datetime object.
  • end_time (optional) – The end time from when the data should be retrieved. This should be the latest time like if we wanted to get data from now until two days ago. Your end time will be today’s datetime end_time time can be either a UTC aware time string like 2019-04-16 12:00:03+01:00 or a datetime.datetime object. It should be noted that it is not possible to declare only end_time. If only end_time is declared without start_time or days, it will revert to default to the latest history state. When end_time is specified, it is not possible to declare entity_id. If entity_id is specified, end_time will be ignored.
  • namespace (str, optional) – Namespace to use for the call. See the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter.
Returns:

An iterable list of entity_ids and their history state.

Examples

Get device state over the last 5 days.

>>> data = self.get_history("light.office_lamp", days = 5)

Get device state over the last 2 days and walk forward.

>>> import datetime
>>> from datetime import timedelta
>>> start_time = datetime.datetime.now() - timedelta(days = 2)
>>> data = self.get_history("light.office_lamp", start_time = start_time)

Get device state from yesterday and walk 5 days back.

>>> import datetime
>>> from datetime import timedelta
>>> end_time = datetime.datetime.now() - timedelta(days = 1)
>>> data = self.get_history(end_time = end_time, days = 5)

See More

Read the AppDaemon API Reference to learn other inherited helper functions that can be used by Hass applications.