iobroker.esphome
Version:
Control your ESP8266/ESP32 with simple yet powerful configuration files created and managed by ESPHome
245 lines (184 loc) • 10.8 kB
Markdown
<img src="./admin/esphome.png" width="10%" height="10%" align="center">
# ioBroker.esphome
[](https://www.npmjs.com/package/iobroker.esphome)
[](https://www.npmjs.com/package/iobroker.esphome)
[](https://david-dm.org/DrozmotiX/iobroker.esphome)
[](https://weblate.iobroker.net/engage/adapters/?utm_source=widget)
[](https://snyk.io/test/github/DrozmotiX/ioBroker.esphome)
[](https://nodei.co/npm/iobroker.esphome/)
**Tests:** 
**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](https://github.com/ioBroker/plugin-sentry#plugin-sentry)! 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 ! :)
This adapter uses the [esphome-native-api](https://github.com/Nafaya/esphome-native-api#readme) with all credits to @Nafaya to interact with [ESPHome API](https://esphome.io/components/api.html?highlight=api)!
<!--
## [Documentation](https://DrozmotiX.github.io/languages/en/Adapter/ESPHome/)
All our adapter documentation can be found at [The DrozmotiX Docu Page](https://DrozmotiX.github.io/languages/en/Adapter/ESPHome/)
-->
## 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
### Using HTTPS
One reason to use HTTPS is to be able to flash directly to devices plugged into you pc, because esphome will not allow this with http (probably browser limitation with WebSerial).
Using the integrated dashboard when the iobroker is using https currently requires some more steps:
1. install - if you don't have it already - web adapter and configure https. see web documentation for further information: [ioBroker.web](https://github.com/ioBroker/ioBroker.web)
2. install [proxy](https://github.com/ioBroker/ioBroker.proxy) adapter
3. configure the path in the proxy adapter settings:
1. context: `esphome/`
2. url: `http://localhost:6052`
4. configure the full dashboard url in the advanced section of the esphome adapter settings - esphome dashboard:
1. like: `https://<iobrokerIP>:<webAdapterPort>/proxy.0/esphome/`
2. where `<iobrokerIP>` is the ip of the host where you iobroker is running (same as above)
3. and `<webAdapterPort>` is the port of the web adapter (default is 8082)
4. it should look something like this:
5. if you run the dashboard on an external host, you can also use the url to an external dashboard instance here
## 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](https://esphome.io/components/api.html?highlight=api)
> 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
> [!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:
- ADD / Modify Devices
- Will send IP address and credentials to the backend and try to establish a connection
- When an encryption Key is provided, API-Password is ignored, please ensure proper YAML configuration!
- Delete Device
- Will send a message to the backend to remove this device
> [!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
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.
### Example config
Example config, for more examples see [The DrozmotiX Docu Page](https://DrozmotiX.github.io) or [ESPHome Documentation](https://esphome.io/index.html)
<details><summary>Show example config
</summary>
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'
</details>
## 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](https://DrozmotiX.github.io/languages/en/Adapter/ESPHome/06.migration.html)
**_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 !)
[](http://paypal.me/DutchmanNL)
## Changelog
<!--
Placeholder for the next version (at the beginning of the line):
### __WORK IN PROGRESS__
* (DutchmanNL)
-->
### 0.6.2 (2025-08-08)
* (@SimonFischer04) add support for text device type #141, displays #103
* (@SimonFischer04) fix cover device type #156
* (@SimonFischer04) workaround: downgrade python for now. fixes #259
### 0.6.1 (2025-05-24)
* (@SimonFischer04) Update esphome
* (@ticaki) Optimize admin configuration interface
* (@DutchmanNL) Optimize backend handling of device discovery
* (@DutchmanNL) Capability to select ESPHome Dashboard version added, resolves #118
### 0.5.0-beta.8 (2023-11-24)
* (DutchmanNL) Capability to automatically detect new devices added
* (DutchmanNL) Ensures a compatible pillow version is used (10.0.1)
* (SimonFischer04) Add pillow python package by default, resolves #188
### 0.5.0-beta.4 (2023-11-15)
* (DutchmanNL) Refactor memory caching of device data, resolves #189
### 0.5.0-beta.1 (2023-11-12)
* (DutchmanNL) Only show error messages once for unreachable devices
## License
MIT License
Copyright (c) 2023-2025 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.