API Reference¶

Skill¶

class opsdroid_homeassistant.HassSkill(opsdroid, config, *args, **kwargs)¶

An Opsdroid skill base class with Home Assistant helper methods.

To create a Home Assistant skill for your Opsdroid bot you need to subclass this class and define methods which are decorated with matchers. For triggering skills on Home Assistant events you will likely want to use the opsdroid_homeassistant.match_hass_state_changed() matcher.

This base class also has some helper functions such as turn_on() and turn_off() to make it quick and convenient to control your Home Assistant entities. See the methods below for more information.

Examples

Turning a light on at sunset:

from opsdroid_homeassistant import HassSkill, match_hass_state_changed


class SunriseSkill(HassSkill):

    @match_hass_state_changed("sun.sun", state="below_horizon")
    async def lights_on_at_sunset(self, event):
        await self.turn_on("light.outside")

For detailed information on writing skills check out the Opsdroid skill docs https://docs.opsdroid.dev/en/stable/skills/index.html.

async anyone_home()¶

Check if anyone is home.

Returns: True if any tracker is set to home, else False.

async call_service(domain: str, service: str, *args, **kwargs)¶

Send a service call to Home Assistant.

Build your own service call to any domain and service.

Parameters

domain – The Home Assistant service domain. E.g media_player.
service – The service to call. E.g media_pause
**kwargs – Service parameters are passed as kwargs. E.g entity_id="media_player.living_room_sonos"

Note

For common operations such and turning off and on entities see the turn_on() and turn_off() helper functions.

Examples

Turn off a climate HVAC:

>>> await self.call_service("climate", "set_hvac_mode", entity_id="climate.living_room", hvac_mode="off")

async everyone_home()¶

Check if everyone is home.

Returns: True if all trackers are set to home, else False.

async get_state(entity: str)¶

Get the state of an entity.

Parameters: entity – The ID of the entity to get the state for.
Returns: The state of the entity.

Examples

Get the state of the sun sensor:

>>> await self.get_state("sun.sun")
"above_horizon"

async get_trackers()¶

Get a list of tracker entities from Home Assistant.

Returns: List of tracker dictionary objects.

Examples

>>> await self.get_trackers()
[{
    "attributes": {
        "entity_picture": "https://www.gravatar.com/avatar/00000000000000000000000000000000?s=500&d=mm",
        "friendly_name": "jacob",
        "ip": "192.168.0.2",
        "scanner": "NmapDeviceScanner",
        "source_type": "router"
    },
    "context": {
        "id": "abc123",
        "parent_id": None,
        "user_id": None
    },
    "entity_id": "device_tracker.jacob",
    "last_changed": "2020-01-03T20:27:55.001812+00:00",
    "last_updated": "2020-01-03T20:27:55.001812+00:00",
    "state": "home"
}]

async nobody_home()¶

Check if nobody is home.

Returns: True if all trackers are set to not_home, else False.

async notify(message: str, title='Home Assistant', target='notify', **kwargs)¶

Send a notification to Home Assistant.

Sends a notify.notify service call with the specified title and message.

Parameters

message – A message to notify with.
title (optional) – A title to set in the notification.
target (optional) – The notification target. Defaults to notify which will notify all.

async render_template(template: str) → str¶

Ask Home Assistant to render a template.

Home Assistant has a built in templating engine powered by Jinja2.

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

This method allows you to pass a template string to Home Assistant and it will return the formatted response.

Parameters: template – The template string to be rendered by Home Assistant.
Returns: A formatted string of the template.

Examples

>>> await self.render_template("Jacob is at {{ states('device_tracker.jacob') }}!")
Jacob is at home!

async set_value(entity_id: str, value, **kwargs)¶

Sets an entity to the specified value in Home Assistant.

Depending on the entity type provided one of the following services will be called:

input_number.set_value
input_text.set_value
input_select.select_option

async sun_down()¶

Check whether the sun is down.

Returns: True if sun is down, else False.

async sun_up()¶

Check whether the sun is up.

Returns: True if sun is up, else False.

async sunrise()¶

Get the timestamp for the next sunrise.

Returns: A Datetime object of next sunrise.

async sunset()¶

Get the timestamp for the next sunset.

Returns: A Datetime object of next sunset.

async toggle(entity_id: str, **kwargs)¶

Toggle an entity in Home Assistant.

Sends a homeassistant.toggle service call with the specified entity.

async turn_off(entity_id: str, **kwargs)¶

Turn off an entity in Home Assistant.

Sends a homeassistant.turn_off service call with the specified entity.

async turn_on(entity_id: str, **kwargs)¶

Turn on an entity in Home Assistant.

Sends a homeassistant.turn_on service call with the specified entity.

async update_entity(entity_id: str, **kwargs)¶

Request an entity update in Home Assistant.

Sends a homeassistant.update_entity service call with the specified entity.

Matchers¶

opsdroid_homeassistant.match_hass_state_changed(entity_id: str, **kwargs) → Callable¶

A matcher for state changes in Home Assistant.

When an entity changes state in Home Assistant an event is triggered in Opsdroid. This matcher can be used to watch for a specific entity to change state:

from opsdroid_homeassistant import HassSkill, match_hass_state_changed


class SunriseSkill(HassSkill):

    @match_hass_state_changed("sun.sun", state="below_horizon")
    async def lights_on_at_sunset(self, event):
        await self.turn_on("light.outside")

Alternatively you can use the opsdroid.matchers.match_event() matcher from the core Opsdroid set of matchers along with the opsdroid_homeassistant.HassEvent class from opsdroid-homeassistant. With this method you much specify the entity with the kwarg entity_id and set changed=True if you only wish for the skill to trigger when the state changes. Sometimes entities send an event even if the state hasn’t changed:

from opsdroid.matchers import match_event
from opsdroid_homeassistant import HassSkill, HassEvent


class SunriseSkill(HassSkill):

    @match_event(HassEvent, entity_id="sun.sun", changed=True, state="below_horizon")
    async def lights_on_at_sunset(self, event):
        await self.turn_on("light.outside")

Note

For sunrise and sunset triggers you can also use the match_sunrise() and match_sunset() helper matchers.

Parameters

entity_id – The full domain and name of the entity you want to watch. e,g sun.sun
state (optional) – The state you want to watch for. e.g on

opsdroid_homeassistant.match_sunrise(func)¶

A matcher to trigger skills on sunrise.

This matcher can be used to run skills when the sun rises:

from opsdroid_homeassistant import HassSkill, match_sunrise


class SunriseSkill(HassSkill):

    @match_sunrise
    async def lights_off_at_sunrise(self, event):
        await self.turn_off("light.outside")

opsdroid_homeassistant.match_sunset(func)¶

A matcher to trigger skills on sunset.

This matcher can be used to run skills when the sun sets:

from opsdroid_homeassistant import HassSkill, match_sunset


class SunsetSkill(HassSkill):

    @match_sunset
    async def lights_on_at_sunset(self, event):
        await self.turn_on("light.outside")

Events¶

class opsdroid_homeassistant.HassEvent(user_id=None, user=None, target=None, connector=None, raw_event=None, raw_parses=None, event_id=None, linked_event=None)¶

Event class to represent a Home Assistant event.

get_entity(name)¶

Get the value of an entity by name.

Parameters: name (string) – Name of entity
Returns: The value of the entity. Returns None if no such entity.

async respond(event)¶

Respond to this event with another event.

This implies no link between the event we are responding with and this event.

update_entity(name, value, confidence=None)¶

Add or update an entitiy.

Adds or updates an entitiy entry for an event.

Parameters

name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct

class opsdroid_homeassistant.HassServiceCall(domain, service, data, *args, **kwargs)¶

Event class to represent making a service call in Home Assistant.

get_entity(name)¶

Get the value of an entity by name.

Parameters: name (string) – Name of entity
Returns: The value of the entity. Returns None if no such entity.

async respond(event)¶

Respond to this event with another event.

This implies no link between the event we are responding with and this event.

update_entity(name, value, confidence=None)¶

Add or update an entitiy.

Adds or updates an entitiy entry for an event.

Parameters

name (string) – Name of entity
value (string) – Value of entity
confidence (float, optional) – Confidence that entity is correct

Connector¶

class opsdroid_homeassistant.HassConnector(config, opsdroid=None)¶

An opsdroid connector for syncing events with the Home Assistant event loop.

property configuration¶: Class property used to access the connector config.

async connect()¶

Connect to chat service.

This method should create a connection to the desired chat service. It should also be possible to call it multiple times in the event of being disconnected.

property default_room¶: The room to send messages to if not specified.

async disconnect()¶

Disconnect from the chat service.

This method is called when opsdroid is exiting, it can be used to close connections or do other cleanup.

async listen()¶

Listen to chat service and parse all messages.

This method should block the thread with an infinite loop and create Message objects for chat messages coming from the service. It should then call await opsdroid.parse(message) on those messages.

As the method should include some kind of while True all messages from the chat service should be “awaited” asyncronously to avoid blocking the thread.

async query_api(endpoint, method='GET', decode_json=True, **params)¶

Query a Home Assistant API endpoint.

The Home Assistant API can be queried at <hass url>/api/<endpoint>. For a full reference of the available endpoints see https://developers.home-assistant.io/docs/en/external_api_rest.html.

Parameters

endpoint – The endpoint that comes after /api/.
method – HTTP method to use
decode_json – Whether JSON should be decoded before returning
**params – Parameters are specified as kwargs. For GET requests these will be sent as url params. For POST requests these will be dumped as a JSON dict and send at the post body.

async react(message, emoji)¶

React to a message.

Not all connectors will have capabilities to react messages, so this method don’t have to be implemented and by default logs a debug message and returns False.

Parameters

message (Message) – A message received by the connector.
emoji (string) – The emoji name with which opsdroid will react

Returns

True for message successfully sent. False otherwise.

Return type

bool

async respond(message, room=None)¶

Send a message back to the chat service.

The message object will have a text property which should be sent back to the chat service. It may also have a room and user property which gives information on where the message should be directed.

Parameters

message (Message) – A message received by the connector.
room (string) – Name of the room to send the message to

Returns

True for message successfully sent. False otherwise.

Return type

bool

async send(event)¶

Send a message to the chat service.

Parameters

event (Event) – A message received by the connector.
target (string) – The name of the room or other place to send the
event. –

Returns

True for event successfully sent. False otherwise.

Return type

bool

API Reference¶

Skill¶

Matchers¶

Events¶

Connector¶

Opsdroid Home Assistant

Navigation

Related Topics