Skip to content

Home Assistant Addon

mak-gitdev edited this page Feb 2, 2023 · 8 revisions

HA_enoceanmqtt can also be installed as a Home Assistant addon.

Install Addon

Migration from the old addon repository

The addon repository has been moved from the HA_enoceanmqtt repository to HA_enoceanmqtt-addon.
This has been done as the addon and HA_enoceanmqtt may evolve at different pace and keeping separate repositories seems easier to me to handle that.
The migration is possible without losing your current setup:

  1. Go to Settings → Add-ons, go to your current addon page and browse to the configuration tab.
  2. Click ⋮ → Edit as YAML, and copy your configuration then paste it in a temporary file of your choice.
  3. If the addon is running, stop it first then uninstall it.
  4. Once the addon is uninstalled, go to the Add-on store, click ⋮ → Repositories and remove the old repository.
  5. Follow the instructions in the installation chapter below to install the new addon repository.
  6. Finally, in the configuration tab, click ⋮ → Edit as YAML and paste your previously saved configuration.

Note: Your device configuration file is not affected by the addon uninstallation.

Installation

  1. If you don't have a MQTT broker yet, in Home Assistant go to Settings → Add-ons → Add-on store and install the Mosquitto broker addon.
  2. Go back to the Add-on store, click ⋮ → Repositories, fill in https://github.com/mak-gitdev/HA_enoceanmqtt-addon and click Add → Close.
  3. Click on the addon and press Install and wait until the addon is installed.

Configuration

  1. Click on Configuration
    • If you already have a previous valid configuration, click ⋮ → Edit as YAML and paste your previously saved configuration. Otherwise, follow the instructions below.
    • Adapt the addon/enoceanmqtt.devices.sample and put it to your Home Assistant /config directory. You can use the Home Assistant File Editor.
      Tip: Your device name can contain / e.g. [lights/livingroom]. This allows you to group your devices by type when exploring MQTT messages.
    • Indicate the location of your device file under the device_file entry.
    • Indicate the location of your mapping file under the mapping_file entry. Useful for people wanting to add support for new devices. Leave empty to use the default mapping file.
    • Indicate your preferred location for the log file under the log_file entry. It shall be in your Home Assistant /config directory.
    • Select the serial interface of your EnOcean dongle in the list of detected serial ports. When using yaml configuration, the format is for example:
      enocean_port: /dev/ttyUSB0
    • If you are not using the Mosquitto broker addon, fill in your MQTT details. Otherwise, leave empty the MQTT broker configuration. The format is for example:
      host: localhost
      port: '1883'
      user: my_user
      pwd: my_password
    • Indicate the mqtt_discovery_prefix under the mqtt_discovery_prefix entry. This is the MQTT prefix used for MQTT device discovery. It defaults to homeassistant and can be configured in the Home Assistant MQTT integration as follow:
      mqtt:
        discovery_prefix: <prefix>
    If you have other HA integrations using MQTT discovery (e.g. zigbee2mqtt, etc.), mqtt_discovery_prefix should be set to homeassistant as it seems to be the one used in general.
    • Indicate the mqtt_prefix under the mqtt_prefix entry. This is the prefix which will be used to interact with your EnOcean devices.
      EnOceanMQTT will interact with EnOcean devices through the device root topic <mqtt_prefix>/<device_name>.
    • Turn on the debug switch if you want a very verbose log file.
    • Other settings can be kept to their default values.
    • Click Save
    • Tip: it is possible to refer to variables in the Home Assistant secrets.yaml file by using e.g. pwd: '!secret mqtt_pwd'
  2. Start the addon by going to Info and click Start
  3. Wait till HA_enoceanmqtt starts and press Log to verify HA_enoceanmqtt started correctly.

Versions

The addon version follow the versions of HA_enoceanmqtt.
The format is: <HA_enoceanmqtt version>-<addon iteration> where HA_enoceanmqtt version format is: <major>.<minor>.<dev iteration>
Example:
0.2-1 = first addon iteration for version 0.2 of HA_enoceanmqtt (stable version)
0.2.2-1 = first addon iteration for version 0.2.2 of HA_enoceanmqtt (dev version, second iteration from stable version 0.2)

Note: x.y.0 and -0 are omitted.