TaskerHA

A Tasker plugin to fully integrate HomeAssistant into your workflow!

You can respond to entity state changes, call any HA service, or retrieve an entity's state.

TaskerHA lets you:

• Call any Home Assistant service from a Tasker action
• Read the state and attributes of any entity
• Trigger Tasker profiles when an entity (or a specific attribute of an entity) changes state over a websocket connection
• Send direct messages from HA to tasker and back with a custom event (uses websocket)

Table of contents:

• TaskerHA
  • Requirements
  • Download
  • Quick start
  • Usage
    • Setup
    • Call service action
      • Response in tasker
      • Error codes
    • Get State action
      • Response in tasker
      • Error codes
    • Direct message from ha profile
      • Response in tasker
      • Error codes
    • Trigger state change profile
      • Response in tasker
      • Error codes
  • Support

Requirements

• Tasker
• Home assistant

Download

Quick start

1. Create a Create a Long-lived access token in your Home Assistant user profile.
2. Download and install the APK.
3. Open the TaskerHA app and configure your Home Assistant URL and token.
4. In Tasker, add an "HA Call service" or "HA Get state" action.
5. (Optional) Enable websockets in the app and create an "HA On trigger state" profile to react to entity changes.

Usage

Setup

1. Create a Long-lived access token in your Homeassistant. And save it for later in the process.
2. Install the app. The APK is available here in releases, and here on f-droid
3. Open the app (outside of tasker) and fill in your Homeassistant server details. This works both over localhost and remote
   • Use the scheme and optionally the port in the url. Example: http://192.168.1.xxx:8123 for a local instance. Or https://ha.yourdomain.com. For proxy servers you do not need to use a port.
   • Do not use a trailing backslash in the host.
   • NOTE: Turning on the websocket will prompt you to turn off battery optimization. Without it the websocket connection might be killed by android and profiles will no longer fire.
   • Turning off websockets in TaskerHa also means any profiles active will never fire.
   • All tasks will use the same server. Maybe a future enhancement will be multi server support but I am not sure how useful that would be.
4. Test the server. If it's correct, save!

Call service action

1. Create a new task in tasker
2. Add action -> plugin -> taskerHa -> HA Call service
3. In the configuration of the task, there are searching and filtering options for all available services in your Homeassistant.
   1. Pick a service to call (filter through domains to make this easier to find)
   2. Once a service is picked. Any fields that need to be filled in will appear.
   3. If an entity_id is needed, an entity picker with searching options will apear. It will already be filtered by the domain of the picked service
   4. Any optional extra data (think light transition for example), can be turned off/on with the checkboxes. If it's turned off the value is not pushed to Homeassistant at all.

This should work for every single service in your Homeassistant, if there are issues with specific services you come accross, please create an issue!

Extra data where you usually see dropdowns in the Homeassistant UI will also have dropdowns here.

You can use tasker variables in any of the text fields and they will be replaced automatically. This includes all optional data.

Example

Turn on a light from Tasker:

• Action: Plugin -> TaskerHA -> HA Call service
• Service: light.turn_on
• Entity: light.living_room
• Optional data: set brightness: 200

Response in tasker

The following variables are available from within tasker after the action

Variable	Function
%ha_data	Complete API response (JSON), this will usually contain the new updated state of a called entity. But it's inconsistent from HA
%err	Error code, is 0 if no error occured. Check below for a complete list of error codes. If an error occurs it will also error the task itself unless you have "continue after error" turned on on the action
%errmsg	Error message. Usually contains a friendly error message, with some java exception next to it.

Error codes

Error code	Description
1	Can't connect to Home Assistant. This means the app could not ping HA. The error will contain more details depending on the reason. But usually this means it can't reach the host
2	Invalid input. This means domain or service cannot be empty
3	Service call failed. This means that it can connect correctly with Homeassistant but the service call itself failed. %errmsg will contain more details
9999	Unknown error occured. %errmsg will contain more details (java error)

Get State action

1. Create a new task in tasker
2. Add action -> plugin -> taskerHa -> HA Get State
3. In the task configuration, there's an entity picker to search with. And you can filter by domain (fuzzy search)

You can use tasker variables for the entity ID, make sure to use the "%" for any variable use.

Example

Check if the alarm is armed:

• Action: Plugin -> TaskerHA -> HA Get state
• Entity: alarm_control_panel.home_alarm
• After the action, read %ha_state in Tasker.
  For example, run different actions based on %ha_state ~ armed_away or disarmed.

Response in tasker

The following variables are available from within tasker after the action

Variable	Function
%ha_state	Contains the current state of the choosen entity
%ha_attrs	Contains in JSON any attributes on the entity. For example, for lights you will get the color, brightness etc.
%ha_raw	Raw JSON of the full API response from homeassistant.
%err	Error code, is 0 if no error occured. Check below for a complete list of error codes. If an error occurs it will also error the task itself unless you have "continue after error" turned on on the action
%errmsg	Error message. Usually contains a friendly error message, with some java exception next to it.

Error codes

Error code	Description
1	Can't connect to Home Assistant. This means the app could not ping HA. The error will contain more details depending on the reason. But usually this means it can't reach the host
2	Invalid input. This means entity ID cannot be empty
3	Get entity state call failed. This means that it can connect correctly with Homeassistant but the entity state call itself failed. %errmsg will contain more details
9999	Unknown error occured. %errmsg will contain more details (java error)

Direct message to HA action

1. Create a new task in tasker
2. Add action -> plugin -> taskerHa -> HA send message back

You can use tasker variables for the type and message.

Example

Activate an automation in Homeassistant

In Tasker:

• action -> plugin -> taskerHa -> HA send message back
• Set type to "this_automation"
• Set message to "some_message"

In Homeassistant:

• Automations -> new automation -> add trigger -> Manual event -> Edit as yaml and paste:

trigger: event
event_type: taskerha_message_back
event_data:
  type: this_automation # Optional, acts as a filter
  message: some_message # Optional, acts as a filter

Response in tasker

The following variables are available from within tasker after the action

Variable	Function
%ha_type	Contains the type sent in the event
%ha_message	Contains the message sent in the event
%rawJson	Contains the raw JSON response from the event
%err	Error code, is 0 if no error occured. Check below for a complete list of error codes. If an error occurs it will also error the task itself unless you have "continue after error" turned on on the action
%errmsg	Error message. Usually contains a friendly error message, with some java exception next to it.

Error codes

Error code	Description
1	Can't connect to Home Assistant. This means the app could not ping HA. The error will contain more details depending on the reason. But usually this means it can't reach the host
9999	Unknown error occured. %errmsg will contain more details (java error)

Direct message from ha profile

1. Create a new profile in Tasker: plugin -> taskerHa -> HA Direct Message
2. You can optionally enter text in type and message
   • These can be used for filtering, if you enter these in tasker, they have to be filled in homeassistant.
   • If you leave it empty it is ignored and you will receive the value.

You can use tasker variables for both fields, make sure to use the "%" for any variable use.

The websocket option in the main app has to be turned on for this. Oterwise it will never fire.

Example

Send a message to tasker in an automation with a specific type

In Tasker:

• Profile: Plugin -> TaskerHA -> HA Direct message
• type: some_type (can be left empty to not filter on type)
• message: (leave empty to not filter on message)

In Homeassistant:

• Automations -> new automation -> add action -> Manual event
• Go in to edit yaml mode (top right 3 dots)

event: taskerha_message
event_data:
  type: some_type
  message: "some message"  # optional

Response in tasker

The following variables are available from within tasker after the action

Variable	Function
%ha_type	Contains the type sent in the event
%ha_message	Contains the message sent in the event
%err	Error code, is 0 if no error occured. Check below for a complete list of error codes. If an error occurs it will also error the task itself unless you have "continue after error" turned on on the action
%errmsg	Error message. Usually contains a friendly error message, with some java exception next to it.

Error codes

Error code	Description
9999	Unknown error occured. %errmsg will contain more details (java error)

Trigger state change profile

1. Create a new profile in Tasker: plugin -> taskerHa -> HA On trigger state
2. In the configuration, search and pick one or more entities using the entity picker (supports domain filtering and fuzzy search).
3. Optionally configure From, To, and For fields to filter events — these work the same as the equivalent fields in a Home Assistant automation trigger.
4. Optionally set a Target attribute to watch a specific attribute of the entity instead of its main state (e.g. color_mode, brightness). When set, HA will only fire the trigger when that attribute changes, and %ha_from / %ha_to will contain the old and new attribute value instead of the entity state.

You can use tasker variables for the entity ID, from/to states and for duration — make sure to use "%" for any variable.

The websocket option in the main app has to be turned on for this. Otherwise it will never fire.

Multiple entities

You can add multiple entities to a single profile. All entities are monitored over a single shared websocket subscription. When any of them fires, %ha_entity tells you which one triggered the profile.

Config per entity

By default ("All entities" mode) the From, To, For, and Target attribute settings apply to every entity in the list equally.

Toggle Config per entity to configure each entity independently — each gets its own From, To, For, and Target attribute settings.

Attribute variable mapping

The Attribute variable mapping section lets you pin specific attribute values to the fixed Tasker variables %ha_attr_1 through %ha_attr_10. This is useful when you want to reliably read an attribute in your task without having to parse %ha_attrs JSON every time.

• Tap Load attributes to fetch the current attribute list for all configured entities from Home Assistant.
• Attributes present on two or more entities appear under a Shared section; attributes unique to a single entity are listed under that entity.
• Assign a slot number (1–10) to any attribute. After the profile fires, the corresponding %ha_attr_N variable will contain that attribute's value from the new state.

Examples

Run a Tasker task when the door opens:

• Profile: Plugin -> TaskerHA -> HA On trigger state
• Entity: binary_sensor.front_door
• From: off, To: on

React to a light's color mode changing:

• Profile: Plugin -> TaskerHA -> HA On trigger state
• Entity: light.living_room
• Target attribute: color_mode
• %ha_from will be the previous color mode (e.g. color_temp), %ha_to will be the new one (e.g. xy).

Map brightness to a variable for easy use downstream:

• Attribute variable mapping: brightness → slot 1
• After the profile fires, %ha_attr_1 contains the current brightness value.

Response in tasker

The following variables are available in Tasker when the profile fires.

Variable	Function
%ha_entity	The entity_id of the entity that triggered the profile.
%ha_from	The previous state of the entity (e.g. off). If a Target attribute is set, contains the previous value of that attribute instead.
%ha_to	The new state of the entity (e.g. on). If a Target attribute is set, contains the new value of that attribute instead.
%ha_for	How long the entity was in the previous state before changing (format: hours:minutes:seconds). Empty if not applicable.
%ha_entities	Comma-separated list of all entity IDs configured in the profile.
%ha_attrs	JSON object of all attributes on the entity for the new state (e.g. brightness, color for lights).
%ha_attr_1–%ha_attr_10	Values of attributes mapped via the Attribute variable mapping section. Only populated for slots you have configured.
%ha_raw	Raw JSON of the full entity state-change event from Home Assistant.
%err	Error code. 0 means no error. If an error occurs the task itself will also error unless "Continue after error" is enabled on the action.
%errmsg	Friendly error message, usually with a Java exception for details.

Error codes

Error code	Description
9999	Unknown error occured. %errmsg will contain more details (java error)

Support