HASS API Reference¶

A list of API calls and information specific to the HASS plugin.

Services¶

call_service()¶

Call service is the basic way of calling a HASS service within AppDaemon. It can call any service and provide any required parameters. Available services can be found using the developer tools in the UI. For listed services, the part before the first period is the domain, and the part after is the service name. For instance, light/turn_on has a domain of light and a service name of turn_on.

Synopsis¶

self.call_service(self, service, **kwargs)

Returns¶

None

Parameters¶

service¶

The service name, e.g. light/turn_on.

namespace = (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¶

Each service has different parameter requirements. This argument allows you to specify a comma separated list of keyword value pairs, e.g. entity_id = light.office_1. These parameters will be different for every service and can be discovered using the developer tools. Most if not all service calls require an entity_id however, so use of the above example is very common with this call.

Examples¶

self.call_service("light/turn_on", entity_id = "light.office_lamp", color_name = "red")
self.call_service("notify/notify", title = "Hello", message = "Hello World")

turn_on()¶

This is a convenience function for the homassistant.turn_on function. It is able to turn on pretty much anything in Home Assistant that can be turned on or run:

Lights
Switches
Scenes
Scripts

And many more.

Synopsis¶

self.turn_on(entity_id, **kwargs)

Returns¶

None

Parameters¶

entity_id¶

Fully qualified entity_id of the thing to be turned on, e.g. light.office_lamp or scene.downstairs_on

namespace = (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¶

A comma separated list of key value pairs to allow specification of parameters over and above entity_id.

Examples¶

self.turn_on("switch.patio_lights")
self.turn_on("scene.bedrrom_on")
self.turn_on("light.office_1", color_name = "green")

turn_off()¶

This is a convenience function for the homassistant.turn_off function. Like homeassistant.turn_on, it is able to turn off pretty much anything in Home Assistant that can be turned off.

Synopsis¶

self.turn_off(entity_id)

Returns¶

None

Parameters¶

entity_id¶

Fully qualified entity_id of the thing to be turned off, e.g. light.office_lamp or scene.downstairs_on.

namespace = (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¶

self.turn_off("switch.patio_lights")
self.turn_off("light.office_1")

toggle()¶

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.

Synopsis¶

self.toggle(entity_id)

Returns¶

None

Parameters¶

entity_id¶

Fully qualified entity_id of the thing to be toggled, e.g. light.office_lamp or scene.downstairs_on.

namespace = (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¶

self.toggle("switch.patio_lights")
self.toggle("light.office_1", color_name = "green")

set_value()¶

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

Synopsis¶

self.set_value(entity_id, value)

Returns¶

None

Parameters¶

entity_id¶

Fully qualified entity_id of the input_number to be changed, e.g. input_number.alarm_hour.

value¶

The new value to set the input number to.

namespace = (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¶

self.set_value("input_number.alarm_hour", 6)

set_textvalue()¶

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

Synopsis¶

self.set_textvalue(entity_id, value)

Returns¶

None

Parameters¶

entity_id¶

Fully qualified entity_id of the input_text to be changed, e.g. input_text.text1.

value¶

The new value to set the input text to.

namespace = (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¶

self.set_textvalue("input_text.text1", "hello world")

select_option()¶

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

Synopsis¶

self.select_option(entity_id, option)

Returns¶

None

Parameters¶

entity_id¶

Fully qualified entity_id of the input_select to be changed, e.g. input_select.mode.

value¶

The new value to set the input slider to.

namespace = (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¶

self.select_option("input_select.mode", "Day")

notify()¶

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.

Synopsis¶

notify(message, **kwargs)

Returns¶

None

Parameters¶

message¶

Message to be sent to the notification service.

title = (optional)¶

Title of the notification - optional.

name = (optional)¶

Name of the notification service - optional.

namespace = (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¶

self.notify("Switching mode to Evening")
self.notify("Switching mode to Evening", title = "Some Subject", name = "smtp")

Presence¶

get_trackers()¶

Return a list of all device tracker names. This is designed to be iterated over.

Synopsis¶

tracker_list = get_trackers()

Parameters¶

namespace = (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 all device trackers.

Examples¶

trackers = self.get_trackers()
for tracker in trackers:
    do something

get_tracker_details()¶

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

Synopsis¶

tracker_list = get_tracker_details()

Parameters¶

namespace = (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¶

A list of all device trackers with their associated state.

Examples¶

trackers = self.get_tracker_details()
for tracker in trackers:
    do something

get_tracker_state()¶

Get the state of a tracker. 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.

Synopsis¶

location = self.get_tracker_state(tracker_id)

Returns¶

A string representing the location of the tracker.

Parameters¶

tracker_id¶

Fully qualified entity_id of the device tracker to query, e.g. device_tracker.andrew.

namespace = (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:
  self.log("{} is {}".format(tracker, self.get_tracker_state(tracker)))

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

Synopsis¶

result = self.everyone_home()

Returns¶

Returns True if everyone is at home, False otherwise.

Parameters¶

namespace = (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¶

if self.everyone_home():
    do something

anyone_home()¶

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.

Synopsis¶

result = self.anyone_home()

Returns¶

Returns True if anyone is at home, False otherwise.

Parameters¶

namespace = (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¶

if self.anyone_home():
    do something

noone_home()¶

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.

Synopsis¶

result = self.noone_home()

Returns¶

Returns True if no one is home, False otherwise.

Parameters¶

namespace = (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¶

if self.noone_home():
    do something

Miscellaneous Helper Functions¶

friendly_name()¶

frindly_name() will return the Friendly Name of an entity if it has one.

Synopsis¶

Name = self.friendly_name(entity_id)

Returns¶

The friendly name of the entity if it exists or the entity id if not.

Example¶

tracker = "device_tracker.andrew"
self.log("{}  ({}) is {}".format(tracker, self.friendly_name(tracker), self.get_tracker_state(tracker)))

split_entity()¶

split_entity() will take a fully qualified entity id of the form light.hall_light and split it into 2 values, the device and the entity, e.g. light and hall_light.

Synopsis¶

device, entity = self.split_entity(entity_id)

Parameters¶

entity_id¶

Fully qualified entity id to be split.

Returns¶

A list with 2 entries, the device and entity respectively.

Example¶

device, entity = self.split_entity(entity_id)
if device == "scene":
    do something specific to scenes

Home Assistant Config¶

get_hass_config()¶

Get Home Assistant configuration data such as latitude and longitude.

Synopsis¶

get_hass_config()

Returns¶

A dictionary containing all the configuration information available from the Home Assistant /api/config endpoint.

Examples¶

config = self.get_hass_config()
self.log("My current position is {}(Lat), {}(Long)".format(config["latitude"], config["longitude"]))