Home Assistant platforms

Home Assistant supports many platforms for nearly all types of smart home devices and appliances. energy2mqtt will be extended step-by-step to support the most of those platforms for LoRaWAN.

Common settings

Some basic settings needs to be set for all platforms and devices which you want to export to Home Assistant:

name: Should be the name of the json key in the data received by the LNS
friendly_name: You should set that to an English name which will be used by the UI
platform: Sets the platform to transfer to Home Assistant. Should be one of sensor, binary_sensor, fan, climate or valve.

For all further options see the page Definition files.

The sensor platform

The sensor integration is the base for most use cases if no special platform exists in Home Assistant. A sensor can be the register of a energy meter, the status of a speaker or the volume of a siren. The following parts of the sensor platform can be set:

state_class: Defines how a sensor is handled. It defaults to measurement.
device_class: Defines the way that this entity will be handled by home assistant.
unit_of_measurement: Depends on the device_class, see the documentation about the allowed units for different device_classes.
suggested_display_precision: In most cases the UI rounds the values to the next integer value which results in 4V for a battery which has a capacity of 3.6V. You can set the way the UI shows the values using this option.

  - name: temperature
    friendly_name: Temperature
    unit_of_measurement: °C
    device_class: temperature

  - name: energy_active_import_t1
    map_key: positive_energy_t1
    friendly_name: Positive Energy Tariff 1
    unit_of_measurement: kWh
    device_class: energy
    state_class: total_increasing

The binary_sensor platform

Binary sensors should be used if the value is read only and is only on or off, e.g. “is the light on” or “the window is open”. If your device has multiple states but you want to use it as binary than specify a value template to transform that to ON and OFF.

An example that can be found in the code of energy2mqtt is the Milesight WT303 which allows the user to set muliple schedules to run without a smart home system to control the AC based on the time. In our smart home we do not care if “Plan 1” or “Plan 9” is running, we only care if a plan is active which overrides our settings. That could be done with a value template like this, whic will return OFF if no_plan is transmitted by the device and ON in any other case:

  - name: plan_id
    map_key: plan
    friendly_name: Planed Mode
    platform: binary_sensor
    device_class: running
    value_template: "{% if ## == \"no_plan\" %}OFF{% else %}ON{% endif %}"

Beside using a template you can also specify payload_on and payload_off and let Home Assistant to it’s magic. If a value_template is set the payload_* variables are ignored.

Details

energy2mqtt translates on to ON and off to OFF so if your sensor sends “on” make sure to write ON in the configuration file.

If you specify ## in a template it will be overriden by the corresponding key which may be handy if you use map key.

The button / device_automation platform

If a device has buttons you may use those to trigger Home Assistant automations if you define them in the definition YAML file. Define platform as device_automation and make sure to set e2m_persist to False to make sure that events are not repeated after a startup or if your sensor does only send status information without the button data in the next time.

The button platform requires a element named triggers to be set. That element is a list of sub elements which must contain subtype and payload.

energy2mqtt matches the payload and sends the corresponding subtype. For a list of possible subtypes see the Home Assistant documentation. This will allow you to setup up to three buttons. Remember you can use map_key to change the name.

  - name: button_key_in_json
    map_key: button_1
    friendly_name: First Button
    platform: device_automation
    e2m_persist: False
    triggers:
      - subtype: button_short_press
        payload: short
      - subtype: button_long_press
        payload: long
      - subtype: button_double_press
        payload: double

The valve platform

A valve can be used for Gas or Water and may help to shut down pipes no longer needed or help prevent damage if a leak is detected. If your valve is read-only (you cannot set it), please use a binary_sensor and not a valve as this will render better on the UI.

state_template: A value template which has priority over state_open and state_close
state_open: Value in the json document if the valve is open
state_closed: Value in the json document if the valve is closed
payload_open: The Downlink to be sent to the device if you press “open” on the UI.
payload_close: The Downlink to be sent to the device if you press “close” on the UI.

See an example here:

  - name: valve
    platform: valve
    friendly_name: valve
    state_open: open/released
    state_close: closed
    payload_open: !Complex { data: "11223344", port: 95, imme: True }
    payload_close: !Basic "close"

The fan platform

Fans can be pretty useful in the summer or if you want to clear your workspace of smoke from soldering. energy2mqtt allows you to define a switch to turn it on and off, get and set the oscillation and use presets like “high”, “low” or “auto”.

Details

You MUST provide a command file to translate the payload of Home Assistant to a downlink, that was a design decision because we you need to have payload_on and _off to be the same and we need a command file for the oscillation anyway.

Your command file MUST support command with $PAYLOAD set to ON and OFF. If you want to use predefined modes like “low”, “high”, “auto” your command tool must implement preset_mode_command.

state_value_template: A value template which has priority over payload_on and payload_off
payload_on: Value in the json document if the fan is running
payload_off: Value in the json document if the fan is off
oscillation_value_template: A value template which has priority over payload_oscillation_on and payload_oscillation_off
payload_oscillation_on: Value in the json document if the oscillation should be displayed as running
payload_oscillation_off: Value in the json document if the oscillation should be displayed as still
preset_mode_value_template: A value template to convert you parsers output to the allowed modes
preset_modes: A list of modes the fan supports.

See an example here:

  - name: fan_status
    friendly_name: Fan
    platform: fan
    value_template: "{% if value_json.fan_status == \"OFF\" %}OFF{% else %}ON{% endif %}"
    oscillation_value_template: "{% if value_json.fan_status == \"OFF\" %}OFF{% else %}ON{% endif %}"
    preset_mode_key: fan_mode
    modes:
      - auto
      - low
      - medium
      - high

The climate platform

Climate consists of heating and cooling devices. Home Assistant allows you to switch between “heating”, “cooling”, “fan_only” and other modes. Climate is the most complex platform currently implemented in energy2mqtt and requires you to write a command tool as soon as you want to set something.

Details

You MUST provide a command file to translate the payload of Home Assistant to a downlink. The command file receives commands like set_temp, set_mode, etc. as described in Downlink handling.

Temperature Settings

current_temperature_template: A value template to extract the current room temperature from the sensor data
temperature_state_template: A value template to extract the target temperature from the sensor data
temperature_command_topic: The command name (e.g., set_temp) passed to your command file when the user changes the target temperature
min_temp: Minimum temperature that can be set (defaults to 7)
max_temp: Maximum temperature that can be set (defaults to 35)
temp_step: Temperature increment (defaults to 0.5)

Mode Settings

mode_state_template: A value template to extract the current mode from the sensor data
mode_command_topic: The command name passed to your command file when the user changes the mode
modes: A list of supported modes. Common modes include:
- off - Device is off
- heat - Heating mode
- cool - Cooling mode
- heat_cool - Auto mode (heating or cooling)
- fan_only - Fan only, no heating/cooling
- dry - Dehumidification mode
- auto - Automatic mode

Fan Mode Settings (optional)

fan_mode_state_template: A value template to extract the current fan speed
fan_mode_command_topic: The command name for fan speed changes
fan_modes: A list of supported fan speeds, e.g., ["auto", "low", "medium", "high"]

Swing Mode Settings (optional)

swing_mode_state_template: A value template to extract the swing/oscillation mode
swing_mode_command_topic: The command name for swing mode changes
swing_modes: A list of supported swing modes, e.g., ["off", "on", "vertical", "horizontal"]

Complete Example

  - name: climate_control
    platform: climate
    friendly_name: Air Conditioner

    # Current room temperature
    current_temperature_template: "{{ value_json.temperature }}"

    # Target temperature
    temperature_state_template: "{{ value_json.target_temperature }}"
    temperature_command_topic: set_temp
    min_temp: 16
    max_temp: 30
    temp_step: 1

    # Operating modes
    mode_state_template: "{{ value_json.mode }}"
    mode_command_topic: set_mode
    modes:
      - "off"
      - heat
      - cool
      - fan_only
      - dry

    # Fan speed
    fan_mode_state_template: "{{ value_json.fan_speed }}"
    fan_mode_command_topic: set_fan
    fan_modes:
      - auto
      - low
      - medium
      - high

    # Swing/oscillation
    swing_mode_state_template: "{{ value_json.swing }}"
    swing_mode_command_topic: set_swing
    swing_modes:
      - "off"
      - "on"

For the corresponding command file implementation, see the Downlink handling documentation which includes a complete shell script example for climate control.