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
homeassistant.turn_on
function. It can turnon
pretty much anything in Home Assistant that can be turnedon
orrun
(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")
- entity_id (str) – Fully qualified id of the thing to be turned
-
turn_off
(self, entity_id, **kwargs)¶ Turns off a Home Assistant entity.
This is a convenience function for the
homeassistant.turn_off
function. It can turnoff
pretty much anything in Home Assistant that can be turnedoff
(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")
- entity_id (str) – Fully qualified id of the thing to be turned
-
toggle
(self, entity_id, **kwargs)¶ Toggles between
on
andoff
for the selected entity.This is a convenience function for the
homeassistant.toggle
function. It is able to flip the state of pretty much anything in Home Assistant that can be turnedon
oroff
.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")
- entity_id (str) – Fully qualified id of the thing to be turned
-
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 aninput_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 tonotify/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") # will send a message through notify.smtp instead of the default notify.notify
-
render_template
(self, template: str, **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: - person (boolean, optional) – If set to True, use person rather than device_tracker as the device type to query
- 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 >>> people = self.get_trackers(person=True) >>> for person in people: >>> 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: - person (boolean, optional) – If set to True, use person rather than device_tracker as the device type to query
- 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 or person to query, e.g., device_tracker.andrew
orperson.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
orNMAP
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
>>> state = self.get_tracker_state("device_tracker.andrew") >>> self.log("state is {}".format(state)) >>> state = self.get_tracker_state("person.andrew") >>> self.log("state is {}".format(state))
-
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: - person (boolean, optional) – If set to True, use person rather than device_tracker as the device type to query
- 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 >>> if self.anyone_home(person=True): >>> 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: - person (boolean, optional) – If set to True, use person rather than device_tracker as the device type to query
- 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 >>> if self.everyone_home(person=True): >>> 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: - person (boolean, optional) – If set to True, use person rather than device_tracker as the device type to query
- 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 >>> if self.noone_home(person=True): >>> do something
Database¶
-
get_history
(self, **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: **kwargs (optional) – Zero or more keyword arguments.
Keyword Arguments: - entity_id (str, optional) – Fully qualified id of the device to be querying, e.g.,
light.office_lamp
orscene.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 bothend_time
andstart_time
explained below are declared, andentity_id
is specified, the specifiedentity_id
will be ignored and the history states of all entity_id in the database will be retrieved within the specified time. - 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 like2019-04-16 12:00:03+01:00
or adatetime.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 like2019-04-16 12:00:03+01:00
or adatetime.datetime
object. It should be noted that it is not possible to declare onlyend_time
. If onlyend_time
is declared withoutstart_time
ordays
, it will revert to default to the latest history state. Whenend_time
is specified, it is not possible to declareentity_id
. Ifentity_id
is specified,end_time
will be ignored. - callback (callable, optional) – If wanting to access the database to get a large amount of data, using a direct call to this function will take a long time to run and lead to AD cancelling the task. To get around this, it is better to pass a function, which will be responsible of receiving the result from the database. The signature of this function follows that of a scheduler call.
- 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)
- entity_id (str, optional) – Fully qualified id of the device to be querying, e.g.,
See More¶
Read the AppDaemon API Reference to learn other inherited helper functions that can be used by Hass applications.