Skip to content

HassController

HassController is the interface to Home Assistant systems. It uses Home Assistant's WebSocket API to implement the communications layer. This approach significantly reduces the load of communication on both systems, even in periods of high activity when a lot of data is being exchanged. You will need to make sure that the WebSocket API is enabled in your HomeAssistant configuration. See their documentation for that.

Because Home Assistant sometimes makes breaking changes to its API, only specific version of Home Assistant are supported by this interface. Currently, only Home Assistant versions 2022.5.3 through 2024.3.3 are supported. Versions outside this range may not work at all, or exhibit errant behaviors that are not immediately obvious. Bug reports and fixes for versions outside this range are not accepted/handled.

The only required fields for HassController are source and access_token:

reactor:
  # reactor configuration section not shown

controllers:
- id: hass
  enabled: true
  implementation: HassController
  name: Home Assistant
  config:
    source: "ws://192.168.0.10:8123"
    access_token: "place long-lived access token within"

Note that the source field must contain a URI in the form ws://ip-address:port. The access_token value is a "long-lived access token" from Home Assistant. To get a LLAT, log in to the Home Assistant UI and click on your username in the bottom-left corner. Then scoll down your profile until you find the "Long-Lived Access Tokens" section. Create a new token there, and copy/paste it into your Reactor controller configuration, keeping it surrounded in quotes as shown above.

Attention

Make sure that the Home Assistant http and websocket_api components are properly configured and enabled. If you have enabled SSL/TLS in your http component configuration (i.e. you specified ssl_certificate in your http configuration in Hass), you must use wss:// on your source value in reactor.yaml, and, if you are using a self-signed certificate, you will also need to add ignore_cert: true after source.

Mapping Home Assistant Entities to Reactor Entities

HassController tries to do as much of the work of mapping between Home Assistant entities and Reactor entities as possible through configuration files. However, there is some data that is not available through the Home Assistant APIs, so there is a mechanism by which you can either override or enhance HassController's default mapping strategy.

Your overrides and enhancements can be specified in a configuration file you create and manage called local_hass_devices.yaml. This file must be located in your config subdirectory (where reactor.yaml also resides).

Overriding Entity Name, Capabilities, etc.

To override the name of an entity, or to add a capability that an entity may have that does not register automatically, add the entity to an entities section of local_hass_devices.yaml, like this:

entities:
  "hass>switch_power_switch":
    name: "My Override Name"
    services:
      - light
      - button
    capabilities:
      - temperature_sensor
    primary_attribute: temperature_sensor.value

In the example above, the entity with the (Reactor) canonical ID hass>switch_power_switch will get given the name shown instead of the name it has in Home Assistant. The services: section (optional) tells Reactor what if any additional (Home Assistant) services the entity provides. This may be needed because (sadly) Home Assistant does not enumerate supported services for its entities in its API — there's no way for Reactor to know what services apply except for the one service that is used to form its entity ID. The (optional) capabilities: section tells Reactor what additional Reactor capabilities to extend to the entity (if any); in this example, we're saying that this odd entity also has temperature sensor capability. Finally, this example makes the temperature sensor value the default (primary) value for the device.

Services First

If you can, use the services section as your first effort to get full entity capabilities. Some Home Assistant services map to multiple Reactor capabilities, so by naming the services first, Reactor is able to correctly find and apply all of those capabilities. If, after naming the services, you don't have a needed native Reactor capability (i.e. not including the x_ extension capabilities), please report that to me on the SmartHome Community so I can improve the device mapping.

Handling Home Assistant Events

Some Home Assistant devices send events, and these events are not mapped in Home Assistant to a Home Assistant Entity. Since the Home Assistant API does not enumerate these events or the devices that may send them, it is up the user (you) to add event handling for any such events.

For example, let's say you have an Amcrest camera that can do motion detection and sends motion events, but the HA integration does not create a virtual motion sensor entity to reflect the state of that capability, it only sends events. Here's a typical motion-start event for the camera:

{
    "event_type": "amcrest",
    "data": {
        "camera": "Cam2",
        "event": "VideoMotion",
        "payload": {
            "Code": "VideoMotion",
            "action": "Start",
            "index": "0"
        }
    },
    "origin": "LOCAL",
    "time_fired": "2021-11-16T19:25:10.223198+00:00",
    "context": {
        "id": "9ec3cdea4a733798660e23e2f59b3a2e",
        "parent_id": null,
        "user_id": null
    }
}

To handle this event, we add the following configuration to our HassController's config section of reactor.yaml:

  config:
    # Additions to config section for Amcrest camera motion:
    event_targets:
     cam2_motion:
        capabilities:
        - motion_sensor
        events:
        - event:
            event_type: amcrest
            data:
              camera: "Cam2"
              event: "VideoMotion"
          response:
            "motion_sensor.state":
              from: "lower(event.data.payload.action)"
              map:
                start: true
                stop: false

This will create a (Reactor) entity with ID cam2_motion, having the single capability motion_sensor, that responds to amcrest HA events. If an amcrest event is received that also matches the given data filters, the attributes enumerated in response will be updated in accordance with their configuration. In this case, that takes the value from the event's data and maps it to a boolean value as required for the attribute.

Each event in the events section (detailed fully below) contains a number of keys and values that are used to filter events. The subkeys of event are compared to the data received. The comparison is literal and case-sensitive; regular expressions are not supported here. In the example above, the event_type field and the data subfields camera and event are compared to the event data. If the match is successful, the response configuration is processed.

Note that the event_type and data values are dependent entirely on the event data for the device and integration in Hass, and they will vary. You can add log_events: true to the config section of your HassController instance to capture events to a file in your logs directory, to help you determine what data Hass is sending with the event and what the filter values and expressions should be.

Large logs!

Turning on event logged will log a lot of data, because Home Assistant processes a lot of events. This setting should be enable only while you are working on an event configuration and turned off immediately after. A restart is required, of course, when the configuration setting is changed.

The response section is an object the keys of which are attribute names in the target entity. Each attribute name must be fully specified as a capability_name.attribute_name pair (e.g. power_switch.state). That value for the key is an object containing instructions for setting the attribute value, which are derived from a combination of from, map and expr keys. The from key may be used to take a value from the event data received. The top level of the event received is represented by the event name in context; for example, using the sample event data received above, one could access the action field in the event data as event.data.payload.action. The event context variable also exists in the expr key, so referring to event.data.payload.action in the value of either from or expr produces the same result; the difference is that from only allows a member reference in the event data (just the path to a field), where expr allows any expression, so you could modify the value before it is assigned to its target attribute. Also note that expr and from are mutually exclusive; you cannot use both, and if both happen to be configured, only expr will be honored. The map key accepts from/to pairs; when the derived value matches the from string, it is changed to the to string. This mapping, if configured, is done last, after any from or expr.

The generalized form of the event_targets section is:

      event_targets:    # this section starts the event-receiving entities
        "my_virtual_entity_id":    # Assign an ID to your entity; each entity must have a unique ID
          name: "My Entity Name"   # This is optional but recommended, so you have a friendly name
          capabilities:  # define an array of capabilities to be modified by the event
            - capability_name    # first capability
            - capability_name    # second, etc., as many as you need, but always at least ONE
          events:  # define an array of events that modify capability attributes on the entity
            - event:  # start of an event; each element of the events array begins this way
                event_type: "type of HomeAssistant event"
                data:  # optional section, if further matching to the event data is required
                  data_field: "data_value"    # data field to be checked/matched to data_value
                  data_field: "data_value"    # as many as you need, but each data_field must be unique
              response:  # begin the (required) response section for handling the event
                "capability.attribute":  # an attribute that the event modifies.
                  expr: "expression"   # expression to get attribute value from event data
                "capability.attribute":
                  # This shows an alternative to using "expr"/expressions for value handling
                  from: "event.data...."  # dot-reference expression to pull value from event message
                  map:                    # optional, map to modify value
                    value_in: new_value   # if value is value_in, it is mapped to new_value
                    value_in: new_value   # repeat this as needed, but each value_in must be unique
                # repeat "capability.attribute" section for all attributes modified by the event
            - event:  # start of next event for this entity, if any; same form as above
        "my_second_entity":  # ID of next entity to create/handle events
          events:
            # etc...

Note that in the expr expression, the variable entity (object) is available with the current data/structure of the target entity. This allows you to access the current value of attributes on the entity while computing the new value, if that's relevant. As stated above, the event variable (object) is also available with the full, raw data of the received event.

Other Special Configuration for HassController

This section is informational only. It is not usually necessary to specify these values or modify their defaults.

  • timeout — this value sets the length of time HassController will wait for a successful connection to Home Assistant before throwing an error. The default is 15000 (milliseconds, 15 seconds).

Updated 2024-Mar-23