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
- appdaemon.plugins.hass.hassapi.Hass.turn_on(self, entity_id: str, **kwargs) None
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")
- appdaemon.plugins.hass.hassapi.Hass.turn_off(self, entity_id: str, **kwargs) None
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")
- appdaemon.plugins.hass.hassapi.Hass.toggle(self, entity_id: str, **kwargs) None
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")
- appdaemon.plugins.hass.hassapi.Hass.set_value(self, entity_id: str, value: Union[int, float], **kwargs) None
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)
- appdaemon.plugins.hass.hassapi.Hass.set_textvalue(self, entity_id: str, value: str, **kwargs) None
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")
- appdaemon.plugins.hass.hassapi.Hass.select_option(self, entity_id: str, option: str, **kwargs) None
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")
- appdaemon.plugins.hass.hassapi.Hass.notify(self, message: str, **kwargs) None
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 (optional) – Zero or more keyword arguments.
- Keyword Arguments
title (str, optional) – Title of the notification.
name (str, optional) – Name of the notification service.
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
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
- appdaemon.plugins.hass.hassapi.Hass.render_template(self, template: str, **kwargs: Optional[Any])
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
- appdaemon.plugins.hass.hassapi.Hass.get_trackers(self, **kwargs) list
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
- appdaemon.plugins.hass.hassapi.Hass.get_tracker_details(self, **kwargs) list
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
- appdaemon.plugins.hass.hassapi.Hass.get_tracker_state(self, entity_id, **kwargs) str
Gets the state of a tracker.
- Parameters
entity_id (str) – Fully qualified entity id of the device tracker or person to query, e.g.,
device_tracker.andrew
orperson.andrew
.**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
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))
- appdaemon.plugins.hass.hassapi.Hass.anyone_home(self, **kwargs) bool
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
- appdaemon.plugins.hass.hassapi.Hass.everyone_home(self, **kwargs) bool
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
- appdaemon.plugins.hass.hassapi.Hass.noone_home(self, **kwargs) bool
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
- appdaemon.plugins.hass.hassapi.Hass.get_history(self, **kwargs) list
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)
See More
Read the AppDaemon API Reference to learn other inherited helper functions that can be used by Hass applications.