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, namespace: str | None = None, **kwargs) → dict

Turns on a Home Assistant entity.

This is a convenience function for the homeassistant.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.).

Note that Home Assistant will return a success even if the entity name is invalid.

Parameters:

  • entity_id (str) –

    Fully qualified id of the thing to be turned on (e.g.,

    light.office_lamp, scene.downstairs_on).

    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.

  • **kwargs (optional) – Zero or more keyword arguments that get passed to the service call.

Returns:

Result of the turn_on function if any, see service call notes for more details.

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, namespace: str | None = None, **kwargs) → dict

Turns off a Home Assistant entity.

This is a convenience function for the homeassistant.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).

  • 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.

  • **kwargs (optional) – Zero or more keyword arguments that get passed to the service call.

Returns:

Result of the turn_off function if any, see service call notes for more details.

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, namespace: str | None = None, **kwargs) → dict

Toggles between on and off 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 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).

  • 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.

  • **kwargs (optional) – Zero or more keyword arguments that get passed to the service call.

Returns:

Result of the toggle function if any, see service call notes for more details.

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: int | float, namespace: str | None = None) → 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 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.

  • 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.

  • **kwargs (optional) – Zero or more keyword arguments that get passed to the service call.

Returns:

Result of the set_value function if any, see service call notes for more details.

Examples

>>> self.set_value("input_number.alarm_hour", 6)
appdaemon.plugins.hass.hassapi.Hass.set_textvalue(self, entity_id: str, value: str, namespace: str | None = None) → 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.

  • 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:

Result of the set_textvalue function if any, see service call notes for more details.

Examples

>>> self.set_textvalue("input_text.text1", "hello world")
appdaemon.plugins.hass.hassapi.Hass.select_option(self, entity_id: str, option: str, namespace: str | None = None) → 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.

  • 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.

  • **kwargs (optional) – Zero or more keyword arguments that get passed to the service call.

Returns:

Result of the select_option function if any, see service call notes for more details.

Examples

>>> self.select_option("input_select.mode", "Day")
appdaemon.plugins.hass.hassapi.Hass.notify(self, message: str, title: str = None, name: str = None, namespace: str | None = None) → 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 to notify/notify.

Parameters:

  • message (str) – Message to be sent to the notification service.

  • 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:

Result of the notify function if any, see service call notes for more details.

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, namespace: str | None = None) → Any

Renders a Home Assistant Template

https://www.home-assistant.io/docs/configuration/templating https://www.home-assistant.io/integrations/template

Parameters:

  • template (str) – The Home Assistant template to be rendered.

  • 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 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, person: bool = True, namespace: str | None = None) → list[str]

Returns a list of all device tracker names.

Parameters:

  • 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, person: bool = True, namespace: str | None = None, copy: bool = True) → dict[str, Any]

Returns a list of all device tracker and the associated states.

Parameters:

  • 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.

  • copy (bool, optional) – Whether to return a copy of the state dictionary. This is usually the desired behavior because it prevents accidental modification of the internal AD data structures. Defaults to True.

Examples

>>> trackers = self.get_tracker_details()
>>> for tracker in trackers:
>>>     do something
appdaemon.plugins.hass.hassapi.Hass.get_tracker_state(self, *args, **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 or person.andrew.

  • attribute (str, optional) – Name of the attribute to return

  • default (Any, optional) – Default value to return when the attribute isn’t found

  • 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.

  • copy (bool, optional) – Whether to return a copy of the state dictionary. This is usually the desired behavior because it prevents accidental modification of the internal AD data structures. Defaults to True.

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

>>> state = self.get_tracker_state("device_tracker.andrew")
>>>     self.log(f"state is {state}")
>>> state = self.get_tracker_state("person.andrew")
>>>     self.log(f"state is {state}")
appdaemon.plugins.hass.hassapi.Hass.anyone_home(self, person: bool = True, namespace: str | None = None) → 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:

  • 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, person: bool = True, namespace: str | None = None) → 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:

  • 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, person: bool = True, namespace: str | None = None) → 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:

  • 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.

  • **kwargs (optional) – Zero or more keyword arguments.

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, entity_id: str | list[str], days: int | None = None, start_time: datetime | str | None = None, end_time: datetime | str | None = None, minimal_response: bool | None = None, no_attributes: bool | None = None, significant_changes_only: bool | None = None, callback: Callable | None = None, namespace: str | None = None) → list[list[dict[str, Any]]]

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.

Hits the /api/history/period/<timestamp> endpoint. See https://developers.home-assistant.io/docs/api/rest for more information

Parameters:

  • entity_id (str, optional) – 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.

  • 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.

  • minimal_response (bool, optional)

  • no_attributes (bool, optional)

  • significant_changes_only (bool, optional)

  • 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(entity_id = "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(entity_id = "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.