Skip to content

Home Assistant Plugs

Jump to bottom
Charles Powell edited this page Sep 1, 2020 · 4 revisions

Home Assistant (HASS) Source and Plugs

To provide dynamic power values to Sense based on a value from a HASS entity, SenseLink needs to be configured with:

  1. Details to communicate with the HASS Websockets API, and
  2. The HASS entity and attribute to utilize to extract and/or calculate the power value for each plug

Note that if you happen to have multiple HASS instances running, you can define more than one HASS block!

HASS API configuration

For a HASS source, you need to provide the url for your HASS server Websockets API, and a "Long lived access token" as the auth_token. These values need to be defined as key-values in the configuration YAML under the HASS source element, as seen in the example configuration:

sources:
  - hass:
      # Assumes your HASS API port is the default 8123
      url: "ws://{Your HASS API URL or IP here}:8123/api/websocket"
      auth_token: "your_token_here"
      plugs:
      - FirstPlugHere: ...
      - SecondPlugHere: ...

And of course, the device running SenseLink needs to be able to access the HASS Websockets URL & port, so be sure to configure any firewalls appropriately.

HASS Plug Configuration

SenseLink supports two methods of determining power usage via the HASS API:

  • Directly, if an entity already provides power data
  • Scaled to another varying attribute (e.g. brightness)
  • Binary on/off (e.g. 15W if on, 0W if off, no in-between)

For each plug utilizing a HASS entity attribute, the following configuration needs to be supplied in addition to the basic requirements plug requirements. Some keys can be ommitted, and the noted default value will be used.

The following keys are used for HASS plugs, see the descriptions of each type of HASS plug configuration below for which keys are used for which type.

  • entity_id [Required]: This tells SenseLink what HASS entity to observe for data.
  • attribute [Required]: This tells SenseLink what attribute of the specified entity to observe to calculate power usage. For example, brightness for a dimmer switch. Attributes can be found in HASS, on the configuration pane for an entity.
  • attribute_max [Required]: The maximum value of the attribute, corresponding the highest power consumption of the entity.
  • max_watts [Required*]: The wattage to report to Sense when the specified attribute is at the maximum value, as defined by attribute_max (While noted as required, if not provided it will default to 0.0, which is probably useless!)
  • attribute_min: The minimum value of the attribute, corresponding to the lowest power consumption of the entity (Defaults to 0.0)
  • min_watts: The wattage to report to Sense when the specified attribute is at the minimum value, as defined by attribute_min (Defaults to `0.0)
  • off_usage: The wattage to supply when the entity state is described as "off" by HASS. This allows you to potentially specify the difference between an idle power and and off power, such as if the device has a vampire load (Defaults to value supplied for min_watts, or 0.0 if none)
  • off_state_key: The text value to utilize to determine if the HASS API is reporting the entity state as in the off state (Defaults to "off")
  • on_state_key: The text value to utilize to determine if the HASS API is reporting the entity state as in the on state. (Defaults to "on")
  • power_keypath: The JSON keypath for raw power usage in the HASS Websockets data. Keys should be separated by forward slashes. See example below. (Defaults to None, meaning it won't be used unless specified)
  • state_keypath: The JSON keypath for plug state in the HASS Websockets data. Keys should be separated by forward slashes. (Defaults to the root state key)
  • attribute_keypath: The JSON keypath for the entity attribute to use for attribute scaling in the HASS Websockets data. Keys should be separated by forward slashes. (Defaults to None, meaning it won't be used unless specified)

Attribute Scaled Power

SenseLink monitors HASS update events, and scales the reported wattage linearly based on the specified attribute values. For example, if a HASS-connected dimmer switch provides values between 0.0 (off) and 255 (full on) for an attribute called brightness, and is connected to four 60 watt incandecent bulbs plus, you would provide the following plug configuration:

- KitchenLights:
    alias: "Kitchen Lights"
    entity_id: light.kitchen_main_lights
    mac: 50:c7:bf:f6:4b:08
    attribute: brightness
    min_watts: 0
    max_watts: 240
    attribute_min: 0
    attribute_max: 255

At 0.0 brightness (off), SenseLink would report 0 watts. At 153.0 (60%) brightness, SenseLink will report 144 watts.

Attribute scaled power can also be paired with the off_state_value and off_usage keys, to report a different power when "off" vs. at the minimum attribute value:

- KitchenLights:
    # ...
    attribute: brightness
    min_watts: 50  # Minimum brightness isn't totally off
    max_watts: 240
    attribute_min: 0
    attribute_max: 255
    off_usage: 5  # Small vampire drain
    off_state_value: "off"   # or a non-standard off string, like "switch_off"

If you don't know exact consumption values, the best way to determine a device power usage is to monitor the power usage manually on the Sense power graph while adjusting the entity attribute of interest, and capture min/max values.

Direct Power Data Type

WARNING: This method requires a little more work and knowledge of JSON, plus possibly some manual work with the HASS Websockets API on your part!

If you have a device connected to HASS that already provides power data (such as even another energy monitor), you need to define the following keys:

  • entity_id
  • power_keypath: Only if the power usage value isn't reported as the root state value

The HASS Websockets API documentation is somewhat lacking, so it may take some investigation on your own to determine the right keypath for your device. SenseLink requests an initial update from HASS on launch, in order to quickly populate power values, and this initial event update has a slightly different JSON structure from the status-change-driven event updates that follow.

SenseLink tries to manage this difference for you, and your power keypath should start from the root of the entity state definition. In the future, a sub-feature maybe added to SenseLink to let you read your own Websockets event feed - but for now you may need to find a Websockets CLI/desktop client to watch the feed and get an idea for the keypath you need.

Example A

Note: This is essentially a made up example. Will be updated as better examples are found.

HASS provides an event update for a device with the following state (this is the full entity definition in a requested update, or the "new_state" value in a status update):

{"entity_id": "sensor.pump_energy_usage",
 "state": {
   "mode": "recirc",
   "runtime": 1245,
   "power": {
     "voltage": 119.4,
     "watts": 241
     }
   },
 "attributes": {
   "attribution": {"..."},
   "friendly_name": "Pool Pump",
   "icon": "mdi:flash",
   }
}

Assuming you want to report the watts value, your plug configuration details would be something like:

- Pool_Pump:
    alias: "Pool Pump"
    entity_id: light.kitchen_main_lights
    mac: #
    entity_id: sensor.pump_energy_usage
    power_keypath: "state/power/watts"

Example B

As an example using a Sense-detected device in HASS that reports watts directly for it's state, an event update contains the following JSON data (some data omitted for brevity):

{"id": 1,
 "type": "event",
 "event": {
   "event_type": "state_changed",
   "data": {
     "entity_id": "sensor.hvac_usage",
     "old_state": {
       "entity_id": "sensor.hvac_usage",
       "state": "707"
       },
     "attributes": {"..."},
     "new_state": {
       "entity_id": "sensor.hvac_usage",
       "state": "403",
       "attributes": {"..."}
     }
  }
}

Your plug configuration details would be something like:

- HVAC_1:
    alias: "HVAC Upstairs"
    entity_id: sensor.hvac_usage
    mac: #

The data of interest here is the "state" value of 403 watts, inside the "new_state" key ("old_state" is as you might expect, the prior state). Because this entity's state is the power value, you do NOT need to define a key path here!

Binary On/Off

If you want to report a semi-static power usage simply based on device state, you only need to define the on/off state strings (if not "on" & "off"), min_watts (if not 0W), and max_watts values. If the value you want to monitor for device state is not at the root state keypath, you can define that as well with the state_keypath key.

# Binary on/off state-based usage device
- Dehumidifier:
    alias: "Dehumidifier"
    entity_id: switch.dehumidifier
    mac: 53:75:31:f6:4b:04
    # off_usage: 0  # If not 0W, uncomment and adjust
    max_watts: 42  # Wattage used for 'on' state
    # on_state_value: "on"  # Uncomment if on state string is something non-standard
    # off_state_value: "off"  # Uncomment if off state string is something non-standard
    # state_keypath: "state/motor/running"  # Example of state at alternate keypath
Clone this wiki locally