Helper Functions

The opsdroid_homeassistant.HassSkill has many helper functions to make interacting with Home Assistant easier.

Services

Helper functions for interacting with common Home Assistant services.

turn_on()

async opsdroid_homeassistant.HassSkill.turn_on(self, entity_id: str, **kwargs)

Turn on an entity in Home Assistant.

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

turn_off()

async opsdroid_homeassistant.HassSkill.turn_off(self, entity_id: str, **kwargs)

Turn off an entity in Home Assistant.

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

toggle()

async opsdroid_homeassistant.HassSkill.toggle(self, entity_id: str, **kwargs)

Toggle an entity in Home Assistant.

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

update_entity()

async opsdroid_homeassistant.HassSkill.update_entity(self, entity_id: str, **kwargs)

Request an entity update in Home Assistant.

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

set_value()

async opsdroid_homeassistant.HassSkill.set_value(self, 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

notify()

async opsdroid_homeassistant.HassSkill.notify(self, 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.

call_service()

async opsdroid_homeassistant.HassSkill.call_service(self, 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")

get_state()

async opsdroid_homeassistant.HassSkill.get_state(self, 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"

Sun state

Helpers for getting information about the sun state.

sun_up()

async opsdroid_homeassistant.HassSkill.sun_up(self)

Check whether the sun is up.

Returns

True if sun is up, else False.

sun_down()

async opsdroid_homeassistant.HassSkill.sun_down(self)

Check whether the sun is down.

Returns

True if sun is down, else False.

sunrise()

async opsdroid_homeassistant.HassSkill.sunrise(self)

Get the timestamp for the next sunrise.

Returns

A Datetime object of next sunrise.

sunset()

async opsdroid_homeassistant.HassSkill.sunset(self)

Get the timestamp for the next sunset.

Returns

A Datetime object of next sunset.

Presence

Helper functions for getting info about presence.

anyone_home()

async opsdroid_homeassistant.HassSkill.anyone_home(self)

Check if anyone is home.

Returns

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

everyone_home()

async opsdroid_homeassistant.HassSkill.everyone_home(self)

Check if everyone is home.

Returns

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

nobody_home()

async opsdroid_homeassistant.HassSkill.nobody_home(self)

Check if nobody is home.

Returns

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

get_trackers()

async opsdroid_homeassistant.HassSkill.get_trackers(self)

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"
}]

Misc

render_template()

async opsdroid_homeassistant.HassSkill.render_template(self, 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!