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

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.

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, same form as above
        "my_second_entity":  # ID of next entity to create/handle events
          events:
            # etc...

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 2023-Aug-28