-
Notifications
You must be signed in to change notification settings - Fork 14
Home Assistant Plugs
To provide dynamic power values to Sense based on a value from a HASS entity, SenseLink needs to be configured with:
- Details to communicate with the HASS Websockets API, and
- 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!
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.
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 byattribute_max
(While noted as required, if not provided it will default to0.0
, which is probably useless!) -
attribute_min
: The minimum value of the attribute, corresponding to the lowest power consumption of the entity (Defaults to0.0
) -
min_watts
: The wattage to report to Sense when the specified attribute is at the minimum value, as defined byattribute_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 formin_watts
, or0.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 toNone
, meaning it won't be used unless specified) -
state_keypath
: The JSON keypath for plugstate
in the HASS Websockets data. Keys should be separated by forward slashes. (Defaults to the rootstate
key) -
attribute_keypath
: The JSON keypath for the entityattribute
to use for attribute scaling in the HASS Websockets data. Keys should be separated by forward slashes. (Defaults toNone
, meaning it won't be used unless specified)
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.
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 rootstate
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.
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"
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!
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