Home Assistant enOcean addon

Easily integrate enOcean protocol using MQTT layer

ℹ️ About the Project • 🛠 Stack Tech • ⚙ ️Setup • 👏🏻 Contributing

ℹ️ About the Project

This is the Home Assistant addon for HA_enoceanmqtt.
HA_enoceanmqtt allows to easily have access to EnOcean devices in Home Assistant through MQTT.

🛠 Stack Tech

⚙ ️Setup

Installation

To install this project, follow these steps:

Installation

1. If you don't have a MQTT broker yet, click on the below button and then Install or in Home Assistant go to Settings → Add-ons → Add-on store and install the Mosquitto broker addon.

2. Click on the below button and then Add or go back to the Add-on store, click ⋮ → Repositories, fill in
   https://github.com/ChristopheHD/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 this device file under the device_file entry.
   • Leave empty the mapping_file entry to use the default mapping file. If you want to use a custom mapping file, indicate the location of your mapping file. This can be useful for people wanting to add support for new devices or customize the existing ones. Refer to this wiki page for more details.
   • Leave empty the eep_file entry to use the default EEP.xml file. If you want to use a custom EEP.xml file, indicate the location of your EEP.xml file. This can be useful for people wanting to add support for new devices not yet supported by the Python EnOcean library. Refer to this wiki page for more details.
   • 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 transceiver 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 Discovery mechanism from the MQTT integration. 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.

👏🏻 Contributing

We welcome contributions from the community! If you would like to contribute to this project, please follow the guidelines below.

Ways to Contribute

• Report bugs or issues by opening a new issue on our GitHub repository.
• Suggest new features or improvements by opening a new issue on our GitHub repository.
• Contribute code by forking the repository, making changes, and submitting a pull request.

Contribution Instructions

1. Fork the repository.
2. Create a new branch for your feature or bug fix: git checkout -b my-feature-branch.
3. Make the necessary changes and commit them: git commit -am 'Add my new feature'.
4. Push your branch to your forked repository: git push origin my-feature-branch.
5. Open a pull request against the main repository, describing the changes you made and why they should be merged.

For more information on how to contribute, please visit Contribution Guidelines.

---

Built with ❤️ with Document My Project