iobroker.esphome 0.6.2 → 0.6.3

package/README.md

@@ -23,8 +23,72 @@ Native integration of ESPHome managed device (Including Dashboard) by its native
 
 ![Logo](admin/img/dashboard.png)
 
+**Quick Links:**
+- 📋 [FAQ - Common Questions](#frequently-asked-questions-faq)
+- ⚙️ [Prerequisites & Setup](#prerequisites)
+- 🎛️ [Dashboard Integration](#esphome-dashboard-integration-optional)
+- 📱 [Device Management](#device-management)
+- 🔧 [Configuration Examples](#example-config)
+
 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)!
 
+## Frequently Asked Questions (FAQ)
+
+### What's the difference between the ioBroker ESPHome Adapter and ESPHome Dashboard?
+
+**ioBroker ESPHome Adapter:**
+- Integrates your ESPHome devices into ioBroker for home automation control
+- Communicates directly with ESP devices via ESPHome's native API
+- Creates ioBroker states/objects for device control and monitoring
+- Handles real-time device status updates (no polling required)
+- Manages device configuration within ioBroker
+
+**ESPHome Dashboard:**
+- A web interface for creating, editing, and managing ESPHome device configurations
+- Used for writing YAML configs, compiling firmware, and flashing devices
+- Can be integrated into ioBroker's admin interface as an optional feature
+- Can be run either integrated with this adapter or as an external installation (Docker, standalone)
+
+**In Summary:** The adapter controls your devices within ioBroker, while the dashboard manages device configurations and firmware.
+
+### How do I configure the Dashboard IP selector?
+
+The Dashboard IP setting in the adapter configuration serves different purposes:
+
+**For Integrated Dashboard Tab in ioBroker Admin:**
+1. Enter the IP address and port where your ESPHome Dashboard is running
+2. **Built-in Dashboard:** Use `127.0.0.1:6052` (default for integrated dashboard)
+3. **External Dashboard:** Use the IP:port of your external ESPHome installation (e.g., Docker container)
+4. **HTTPS Setup:** For HTTPS environments, see the detailed HTTPS configuration section below
+
+**Dashboard IP Examples:**
+- Built-in: `127.0.0.1:6052`
+- External Docker: `192.168.1.100:6052`
+- External Host: `esphome.local:6052`
+- HTTPS Proxy: `https://192.168.1.50:8082/proxy.0/esphome/`
+
+![ESPHome Dashboard IP Configuration](admin/img/ESPhomeDashboardIP.png)
+
+**Note:** You can use this adapter to control ESPHome devices without configuring the Dashboard IP. The Dashboard IP is only needed if you want to integrate the ESPHome Dashboard interface into ioBroker's admin panel.
+
+### Do I need the ESPHome Dashboard to use this adapter?
+
+**No, the Dashboard is optional.** You can use this adapter in several ways:
+
+1. **Adapter Only:** Control pre-configured ESPHome devices without any dashboard integration
+2. **Adapter + External Dashboard:** Use your existing ESPHome installation (Docker, standalone) and optionally integrate it into ioBroker's interface
+3. **Adapter + Built-in Dashboard:** Enable the integrated ESPHome Dashboard feature for a complete solution
+
+The adapter works independently and only requires devices with ESPHome API enabled in their configuration.
+
+### How do I add devices to the adapter?
+
+1. **Ensure ESPHome API is enabled** in your device's YAML configuration (see Prerequisites section)
+2. **Open the adapter's device tab** in ioBroker Admin (adapter must be running)
+3. **Add devices manually:** Enter device IP address and authentication credentials
+4. **Automatic discovery:** Currently disabled (see issue #175)
+
+The adapter will establish a connection and create all necessary ioBroker objects for device control.
 
 <!--
 ## [Documentation](https://DrozmotiX.github.io/languages/en/Adapter/ESPHome/)
@@ -39,11 +103,29 @@ All our adapter documentation can be found at [The DrozmotiX Docu Page](https://
     * 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
+## ESPHome Dashboard Integration (Optional)
+
+This adapter can optionally integrate the ESPHome Dashboard into ioBroker's admin interface. You have several options:
+
+**Option 1: Built-in Dashboard (Recommended for beginners)**
+- Enable "Native Integration of ESPHome Dashboard" in adapter settings
+- Uses integrated Python environment (no external setup required)
+- Dashboard runs on port 6052 by default
+- Set Dashboard IP to `127.0.0.1:6052` for admin integration
+
+**Option 2: External Dashboard**
+- Use existing ESPHome installation (Docker, standalone, etc.)
+- Enter the external dashboard's IP:port in adapter settings
+- Example: `192.168.1.100:6052` for Docker container
 
-![Logo](admin/img/ESPhomeDashboardIP.png)
+**Option 3: No Dashboard Integration**
+- Skip dashboard configuration entirely
+- Use external ESPHome tools for device configuration
+- Adapter still controls devices normally
+
+![Dashboard IP Configuration](admin/img/ESPhomeDashboardIP.png)
+
+> **💡 See FAQ above** for detailed explanations about Dashboard IP configuration and adapter vs. dashboard differences.
 
 ### Using HTTPS
 
@@ -89,6 +171,8 @@ api:
   password: 'MyPassword'
 ```
 
+## Device Management
+
 ### Add / Modify / Remove ESPHome devices to ioBroker
 > [!IMPORTANT]
 > This adapter integrates communication with ESPHome capable devices and 
@@ -97,6 +181,8 @@ api:
 > either by using the integrated Dashboard or an external alternative 
 > (like Docker) before they can be integrated to ioBroker
 
+> **💡 See FAQ above** for step-by-step guidance on adding devices to the adapter.
+
 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
 
@@ -198,6 +284,14 @@ If you like my work, please consider a personal donation
     ### __WORK IN PROGRESS__
     * (DutchmanNL) 
 -->
+### 0.6.3 (2025-09-16)
+* (@DutchmanNL) Fixed an admin error related to `jsonConfig` validation. #287
+* (@DutchmanNL) Various general fixes and dependency updates to improve stability.
+* (@DutchmanNL) Improved responsive design for better usability across devices. #284
+* (@DutchmanNL) Introduced GitHub Actions to automatically verify the ESPHome Dashboard. #290
+* (@DutchmanNL) Added a comprehensive FAQ section to the README to help users with common questions. #286
+* (@DutchmanNL) Updated the `esphome-native-api` library to V1.3.3, which may resolve connection issues. #201
+
 ### 0.6.2 (2025-08-08)
 * (@SimonFischer04) add support for text device type #141, displays #103
 * (@SimonFischer04) fix cover device type #156
@@ -217,9 +311,6 @@ If you like my work, please consider a personal donation
 ### 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
 

package/admin/i18n/en/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "Maximum connection retry before considering device as offline",
     "newDevicesHeader": "Newly discovered devices, please provide credentials!",
     "reConInterval": "Setting between ioBroker try's to reconnect this device"
-}
+}

package/admin/i18n/es/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "Reintento máximo de conexión antes de considerar el dispositivo como fuera de línea",
     "newDevicesHeader": "Dispositivos recién descubiertos, proporcione credenciales.",
     "reConInterval": "Configuración entre intentos de ioBroker para volver a conectar este dispositivo"
-}
+}

package/admin/i18n/fr/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "Nombre maximal de tentatives de connexion avant de considérer l'appareil comme hors ligne",
     "newDevicesHeader": "Appareils récemment découverts, veuillez fournir vos informations d'identification !",
     "reConInterval": "Paramètres entre ioBroker essayant de reconnecter cet appareil"
-}
+}

package/admin/i18n/it/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "Numero massimo di tentativi di connessione prima di considerare il dispositivo offline",
     "newDevicesHeader": "Dispositivi appena scoperti, fornisci le credenziali!",
     "reConInterval": "Impostazione tra i tentativi di ioBroker di riconnettere questo dispositivo"
-}
+}

package/admin/i18n/nl/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "Maximale verbindingspoging voordat het apparaat als offline wordt beschouwd",
     "newDevicesHeader": "Nieuw ontdekte apparaten, geef uw inloggegevens op!",
     "reConInterval": "Instelling tussen ioBroker-pogingen om dit apparaat opnieuw te verbinden"
-}
+}

package/admin/i18n/pl/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "Maksymalna liczba ponownych prób połączenia przed uznaniem urządzenia za offline",
     "newDevicesHeader": "Nowo odkryte urządzenia. Podaj dane uwierzytelniające!",
     "reConInterval": "Ustawienie między próbą ponownego podłączenia tego urządzenia przez ioBroker"
-}
+}

package/admin/i18n/pt/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "Tentativa máxima de conexão antes de considerar o dispositivo como off-line",
     "newDevicesHeader": "Dispositivos recém-descobertos, forneça credenciais!",
     "reConInterval": "Configuração entre tentativas do ioBroker para reconectar este dispositivo"
-}
+}

package/admin/i18n/ru/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "Максимальное количество повторных попыток подключения, прежде чем устройство будет считаться отключенным",
     "newDevicesHeader": "Недавно обнаруженные устройства, предоставьте учетные данные!",
     "reConInterval": "Настройка между попытками ioBroker повторно подключить это устройство"
-}
+}

package/admin/i18n/uk/translations.json

@@ -0,0 +1,42 @@
+{
+    "ESPHomeCommunityLink": "Для отримання додаткової інформації про ESPHome, приклади конфігурації та посилання на спільноти відвідайте:",
+    "chkEnableESPHome": "Увімкнути ESPHome Dashboard",
+    "existDevicesHeader": "Усі пристрої, якими керує цей адаптер, та їхній стан підключення",
+    "hlpDiscoveryListeningAddress": "Виявляти пристрої тільки на цьому інтерфейсі",
+    "hlpESPHomeDashboardVersion": "Виберіть версію ESPHome Dashboard для використання",
+    "hlpInputApiPassword": "Пароль API (застарілий, використовуйте ключ шифрування!)",
+    "hlpInputDeviceIP": "Виберіть існуючий пристрій або введіть IP нового пристрою",
+    "hlpInputEncryptionKey": "Вкажіть ключ шифрування для конкретного пристрою (рекомендується)",
+    "introLine-1": "ioBroker ESPHome дозволяє керувати пристроями ESPHome, ви повинні створити та завантажити ці бінарні файли самостійно!",
+    "introLine-2": "ESPHome Dashboard потрібен для створення цих бінарних файлів. Як тільки прошивка пристрою завантажена та працює, ESPHome Dashboard більше не потрібен для зв'язку з ioBroker",
+    "lblApiPass": "Пароль API (застарілий)",
+    "lblAutoDiscovery": "Виявлення пристроїв увімкнено",
+    "lblConnectDetails-Line-1": "Нативний API ESPHome використовується для прямого зв'язку з клієнтами за допомогою високо оптимізованого мережевого протоколу. Нативний API має багато переваг над використанням MQTT для зв'язку з програмним забезпеченням домашньої автоматизації.",
+    "lblConnectDetails-Line-2": "Після додавання рядка api: до конфігурації ESPHome ви можете перейти на цю сторінку та дочекатися появи пристрою ESPHome в розділі виявлених пристроїв (може зайняти до 5 хвилин) або додати пристрій вручну, вибравши \"додати пристрій\" з огляду пристроїв та ввівши \"<NODE_NAME>.local\" або IP-адресу пристрою в поле \"Хост\".",
+    "lblConnectDetails-Line-3": "Нативний API ESPHome базується на спеціальному TCP протоколі, що використовує protocol buffers. Ви можете знайти визначення структури даних протоколу тут:",
+    "lblConnectIobroker": "ioBroker взаємодіє безпосередньо через нативний API замість MQTT, щоб забезпечити найкращий досвід та підтримку ключів шифрування (рекомендується) замість паролів API/MQTT",
+    "lblDashboardLink": "Щоб показати ESPHome dashboard у вкладці адміністратора ioBroker, потрібно вказати IP-адресу, на якій працює установка. Https наразі не підтримується",
+    "lblDefaultCredentials": "Налаштування ключів API / шифрування за замовчуванням для пристроїв (не рекомендується)",
+    "lblDefaultCredentials-Line-1": "Кожен пристрій повинен мати свій унікальний ключ шифрування (рекомендується) або пароль API, виявлення пристроїв (коли увімкнено) виявляє всі пристрої та намагається підключитися з обліковими даними нижче",
+    "lblDefaultCredentials-Line-2": "Якщо ви призначите унікальний ключ шифрування (рекомендується) або пароль API, нові пристрої з'являться на вкладці виявлених пристроїв (або повинні бути додані) і ви повинні вказати унікальні облікові дані вручну",
+    "lblDelDevice": "Видалити пристрій",
+    "lblDevicesTable": "Усі поточні (відомі) пристрої та їхній стан підключення",
+    "lblDiscoveryListeningAddress": "Адреса прослуховування",
+    "lblESPHomeDashboardVersion": "Версія ESPHome Dashboard",
+    "lblESPHomeIP": "IP-адреса, де працює ESPHome Dashboard для інтеграції в адміністратор ioBroker",
+    "lblESPHomePort": "Порт ESPHome Dashboard",
+    "lblEnableESPHome": "Ви можете запустити ESPHome Dashboard окремо або активувати опцію нижче для запуску його нативно в ioBroker",
+    "lblEncryptionKey": "Ключ шифрування за замовчуванням",
+    "lblHeaderConnect": "Як підключити пристрій ESPHome до ioBroker",
+    "lblHeaderMainPage": "Інтеграція ESPHome Dashboard",
+    "lblIgnoreList": "IP-адреси, які виключаються з виявлення пристроїв",
+    "lblInputApiPassword": "Пароль API",
+    "lblInputDeviceIP-content": "IP-адреса пристрою",
+    "lblInputEncryptionKey": "Ключ шифрування",
+    "lblLoadDevices": "Оновити огляд пристроїв",
+    "lblTxtNoButtonsIfNotActive": "Таблиця пристроїв та кнопки ДОДАТИ / Видалити доступні тільки якщо адаптер працює",
+    "lbl_addUpdateDevice": "ДОДАТИ / Змінити пристрої",
+    "maxRetry": "Максимальна кількість спроб підключення перед тим, як вважати пристрій офлайн",
+    "newDevicesHeader": "Нещодавно виявлені пристрої, будь ласка, надайте облікові дані!",
+    "reConInterval": "Інтервал між спробами ioBroker повторно підключитися до цього пристрою"
+}

package/admin/i18n/zh-cn/translations.json

@@ -39,4 +39,4 @@
     "maxRetry": "将设备视为离线之前的最大连接重试次数",
     "newDevicesHeader": "新发现的设备，请提供凭据！",
     "reConInterval": "ioBroker 尝试重新连接此设备之间的设置"
-}
+}

package/admin/jsonConfig.json5

@@ -19,49 +19,89 @@
 				"headerHowToConnect-details-1": {
 					"newLine": true,
 					"type": "staticText",
-					"text": "lblConnectDetails-Line-1"
+					"text": "lblConnectDetails-Line-1",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 
 				"headerHowToConnect-details-2": {
 					"newLine": true,
 					"type": "staticText",
-					"text": "lblConnectDetails-Line-2"
+					"text": "lblConnectDetails-Line-2",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 				"headerHowToConnect-details-3": {
 					"newLine": true,
 					"type": "staticText",
-					"text": "lblConnectDetails-Line-3"
+					"text": "lblConnectDetails-Line-3",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 
 				// Mention & link to api.proto project
 				"headerESPHomeDashboard-details-api.proto": {
 					"type": "staticLink",
 					"label": "api.proto",
-					"href" : "https://github.com/esphome/esphome/blob/dev/esphome/components/api/api.proto"
+					"href" : "https://github.com/esphome/esphome/blob/dev/esphome/components/api/api.proto",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 
 				"emptyLine-6": {
 					"newLine": true,
 					"type": "staticText",
-					"text": ""
+					"text": "",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 
 				// Text explaining ioBroker integration
 				"headerHowToConnect-details-4": {
 					"newLine": true,
 					"type": "staticText",
-					"text": "lblConnectIobroker"
+					"text": "lblConnectIobroker",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 
 				"emptyLine-7": {
 					"newLine": true,
 					"type": "staticText",
-					"text": ""
+					"text": "",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 				"emptyLine-8": {
 					"newLine": true,
 					"type": "staticText",
-					"text": ""
+					"text": "",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 
 				// Header default credentials
@@ -75,12 +115,22 @@
 				"headerDefaultCredentials-details-1": {
 					"newLine": true,
 					"type": "staticText",
-					"text": "lblDefaultCredentials-Line-1"
+					"text": "lblDefaultCredentials-Line-1",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 				"headerDefaultCredentials-details-2": {
 					"newLine": true,
 					"type": "staticText",
-					"text": "lblDefaultCredentials-Line-2"
+					"text": "lblDefaultCredentials-Line-2",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 
 				// Credentials which will be stored (encrypted) in adapter config object
@@ -88,12 +138,20 @@
 					"newLine": true,
 					"type": "password",
 					"label": "lblEncryptionKey",
-					"sm": 3
+					"xs": 12,
+					"sm": 3,
+					"md": 3,
+					"lg": 3,
+					"xl": 3
 				},
 				"apiPass": {
 					"type": "password",
 					"label": "lblApiPass",
-					"sm": 2
+					"xs": 12,
+					"sm": 2,
+					"md": 2,
+					"lg": 2,
+					"xl": 2
 				}
 			}
 		},
@@ -108,15 +166,21 @@
 				"autodiscovery": {
 					"newLine": true,
 					"type": "checkbox",
+					"xs": 12,
 					"sm": 3,
 					"md": 3,
+					"lg": 3,
+					"xl": 3,
 					"label": "lblAutoDiscovery"
 				},
 
 				"discoveryListeningAddress" : {
 					"type": "ip",
+					"xs": 12,
 					"sm": 3,
 					"md": 3,
+					"lg": 3,
+					"xl": 3,
 					"default": "0.0.0.0",
 					"label": "lblDiscoveryListeningAddress",
 					"help": "hlpDiscoveryListeningAddress",
@@ -133,7 +197,8 @@
 					"xs": 12,
 					"sm": 12,
 					"md": 12,
-					"lg": 12
+					"lg": 12,
+					"xl": 12
 				},
 
 				// Input fields to ADD / Modify devices
@@ -144,39 +209,40 @@
 					"type": "autocompleteSendTo",
 					"command": "getDeviceIPs",
 					"jsonData": "{ \"service\": \"${data.deviceInputIP}\" }",
-					"xs": 2,
+					"xs": 12,
 					"sm": 2,
 					"md": 2,
 					"lg": 2,
+					"xl": 2,
 					"label": "lblInputDeviceIP-content",
 					"tooltip": "hlpInputDeviceIP",
 					"help": "hlpInputDeviceIP"
 				},
 				"encryptionKey": {
 					"type": "password",
-					"freeSolo": true,
 					"label": "lblInputEncryptionKey",
 					"doNotSave": true,
 					"default": "",
 					"tooltip": "hlpInputEncryptionKey",
 					"help": "hlpInputEncryptionKey",
-					"xs": 4,
+					"xs": 12,
 					"sm": 4,
 					"md": 4,
-					"lg": 4
+					"lg": 4,
+					"xl": 4
 				},
 				"apiPassword": {
 					"type": "password",
-					"freeSolo": true,
 					"label": "lblInputApiPassword",
 					"doNotSave": true,
 					"default": "",
 					"tooltip": "hlpInputApiPassword",
 					"help": "hlpInputApiPassword",
-					"xs": 2,
+					"xs": 12,
 					"sm": 2,
 					"md": 2,
-					"lg": 2
+					"lg": 2,
+					"xl": 2
 				},
 
 				// Button do ADD / Modify devices, sends
@@ -197,7 +263,8 @@
 					"xs": 12,
 					"sm": 12,
 					"md": 12,
-					"lg": 12
+					"lg": 12,
+					"xl": 12
 				},
 
 				"deleteDevice": {
@@ -217,6 +284,7 @@
 					"sm": 12,
 					"md": 12,
 					"lg": 12,
+					"xl": 12,
 					"confirm" : {
 						"text" : "Are you sure to delete this device ? Alle states will be removed",
 						"title" : "Confirm device Deletion",
@@ -247,7 +315,8 @@
 					"xs": 12,
 					"sm": 12,
 					"md": 12,
-					"lg": 12
+					"lg": 12,
+					"xl": 12
 				},
                 "header2": {
                     "type": "header",
@@ -264,6 +333,7 @@
 					"sm": 12,
 					"md": 12,
 					"lg": 12,
+					"xl": 12,
                     "doNotSave": true,
 					"hidden": "!data.newDevicesTable || data.newDevicesTable.length == 0",
 					"showSecondAddAt": 5,
@@ -321,6 +391,7 @@
 					"sm": 12,
 					"md": 12,
 					"lg": 12,
+					"xl": 12,
 					"showSecondAddAt": 5,
 					"items": [
 						{
@@ -393,12 +464,22 @@
 				// Introduction text
 				"introLine-1": {
 					"type": "staticText",
-					"text": "introLine-1"
+					"text": "introLine-1",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 				"introLine-2": {
 					"newLine": true,
 					"type": "staticText",
-					"text": "introLine-2"
+					"text": "introLine-2",
+					"xs": 12,
+					"sm": 12,
+					"md": 12,
+					"lg": 12,
+					"xl": 12
 				},
 
 				"emptyLine-1": {

package/admin/tsconfig.json

@@ -0,0 +1,9 @@
+{
+	"extends": "../tsconfig.json",
+	"include": [
+		"./admin.d.ts",
+		"./**/*.js",
+		// include the adapter-config definition if it exists
+		"../src/lib/adapter-config.d.ts",
+	]
+}