search

DrozmotiX / ioBroker.esphome

Control your ESP8266/ESP32 with simple yet powerful configuration files created and managed by ESPHome
MIT License
30 stars 23 forks source link
esp esp32 esphome iobroker-adapter

readme

ioBroker.esphome

NPM version Downloads Number of Installations (latest) Number of Installations (stable) Dependency Status Translation status Known Vulnerabilities

NPM

Tests: Test and Release

This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and for information how to disable the error reporting see Sentry-Plugin Documentation! Sentry reporting is used starting with js-controller 3.0.

ESPHome adapter for ioBroker

Control your ESP8266/ESP32 with simple yet powerful configuration files created and managed by ESPHome. Native integration of ESPHome managed device (Including Dashboard) by its native API and ensures all data is synchronized (live-event handling, no data polling ! :)

Logo

This adapter uses the esphome-native-api with all credits to @Nafaya to interact with ESPHome API!

Prerequisites

* NodeJS >= 18.x
* API is activated in YAML
* For admin tabs (optional)
    * ESPHome Dashboard IP is provided in instance settings

Using the built-in ESPHome Dashboard

You can either use an external installation of ESPHome (like docker) or activate the ESPHome Dashboard process included in this adapter.
In any case, it is possible to integrate the dashboard into ioBroker Admin interface, for this purpose you must specify the ip where the Dashboard is running

Logo

[!IMPORTANT] is currently not possible to show the ESPHome DashBoard integrated in ioBroker when https is enabled, see #159

How to use this adapter

Activate API in YAML

[!IMPORTANT] ioBroker ESPHome allows to integrate Devices by Encryption Key (recommended) or API-Password (legacy), you must specify your authentication settings accordingly, see ESPHome Documentation Please only configure Encryption Key (preferable) or API-Password (legacy)

Example Encryption Key configuration entry

api:
  encryption:
    key: "DyDfEgDzmA9GlK6ZuLkj3qgFcjXiZUzUf4chnIcjQto="

Example API configuration entry

api:
  password: 'MyPassword'

Add / Modify / Remove ESPHome devices to ioBroker

[!IMPORTANT] This adapter integrates communication with ESPHome capable devices and (if activated) an integrated version of ESPHome Dashboard. You must configure and upload your ESP configuration by yourself, either by using the integrated Dashboard or an external alternative (like Docker) before they can be integrated to ioBroker

The device Tab will show all current known devices; you can either wait for Devices to be autodetect (currently disabled, see #175) or add them manually by providing their IP-Address and credentials

DevicesTab

[!NOTE] Buttons to add/modify/remove devices and load device table are only available if adapter is running! You must refresh the device table manually by pressing "Refresh device Overview", all devices and their connection state will be shown

Please enter IP-Address (if a device is already known, you can select it from the dropdown) and choose the proper actions:

[!WARNING] This action will remove a selected device and all its related states from ioBroker!

[!NOTE] After a device has been added, a message will be indicated if successfully or error, you can refresh the table to show current devices and their connection status

DevicesError DevicesOK

If connection was successfully, the Device will be initiated and all related states created to control their attributes.
When making any changes to your YAML configuration, reboot of the ESP will disconnect and initiate a new connection.
During this process, states not part anymore of YAML configuration will be automatically removed.

DevicesOK

Example config

Example config, for more examples see The DrozmotiX Docu Page or ESPHome Documentation

Show example config esphome: name: sensor_badkamer platform: ESP32 board: esp-wrover-kit wifi: use_address: 192.168.10.122 ssid: "xxxxx" password: "xxxxxx" # Enable ESPHome API api: password: 'MyPassword' # Activate i2c bus i2c: sda: 21 scl: 22 scan: True id: bus_a # Example configuration for bh1750 sensor: - platform: bh1750 name: "Hal_Illuminance" address: 0x23 measurement_time: 69 update_interval: 10s # Example configuration for an GPIO output output: - platform: gpio pin: 12 inverted: true id: gpio_12 # Example configuration linking a switch to the previous defined output switch: - platform: output name: "Generic Output" output: 'gpio_12'

Tasmota / ESPEasy migration

Migrating from previous Sonoff Tasmota or ESPEasy setups is very easy. You just need to have ESPHome create a binary for you and then upload that in the web interface.
See for more details on our Docu Page

NOTE: Generated yaml files are stored at ```/opt/iobroker/iobroker-data/iobroker.esphome.>instance</>device<.yaml

Support me

If you like my work, please consider a personal donation
(this is a personal Donate link for DutchmanNL, no relation to the ioBroker Project !)
Donate

Changelog

WORK IN PROGRESS

0.5.0-beta.8 (2023-11-24)

0.5.0-beta.4 (2023-11-15)

0.5.0-beta.1 (2023-11-12)

0.5.0-beta.0 (2023-11-12) - Rebuild Admin Interface & Connection handler

0.4.1 (2023-11-05)

License

MIT License

Copyright (c) 2023 DutchmanNL rdrozda86@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.