homebridge-homeassistant-things 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -10,6 +10,22 @@ Todos los cambios relevantes de este proyecto se documentan aquí.
 
 ---
 
+## [2.1.2] - 2026-04-02
+
+### Changed / Cambios
+- **EN** README: added troubleshooting section for users upgrading from v1.x — explains how to uninstall, clear cache, restart and reinstall to fix schema caching issues.
+- **ES** README: añadida sección de solución de problemas para usuarios que actualizan desde v1.x — explica cómo desinstalar, limpiar caché, reiniciar y reinstalar para resolver problemas de caché del schema.
+
+---
+
+## [2.1.1] - 2026-04-02
+
+### Changed / Cambios
+- **EN** README updated: Homebridge verification submitted notice and badge added.
+- **ES** README actualizado: añadido aviso e insignia de verificación oficial de Homebridge solicitada.
+
+---
+
 ## [2.1.0] - 2026-04-02
 
 ### Added / Añadido

package/README.md

@@ -4,6 +4,11 @@ Homebridge plugin to control Home Assistant devices as native HomeKit accessorie
 
 [![npm version](https://img.shields.io/npm/v/homebridge-homeassistant-things)](https://www.npmjs.com/package/homebridge-homeassistant-things)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Homebridge Verified](https://img.shields.io/badge/homebridge-verification%20pending-yellow)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+
+> **EN** This plugin has been submitted for **official Homebridge verification**. Once approved, it will appear as a verified plugin in the Homebridge plugin catalogue.
+>
+> **ES** Este plugin ha sido enviado para **verificación oficial de Homebridge**. Una vez aprobado, aparecerá como plugin verificado en el catálogo de plugins de Homebridge.
 
 ---
 
@@ -71,12 +76,13 @@ Desde v2.0.0 el plugin es una **dynamic platform**. Mueve la config del bloque `
 
 ### Supported device types
 
-| `deviceType`  | HomeKit service   | HA entity domain | Sync |
-|---------------|-------------------|------------------|------|
-| `switch`      | Switch            | `switch`, `light`, `input_boolean` | Bidirectional |
-| `thermostat`  | Thermostat        | `climate`        | Bidirectional |
-| `blind`       | Window Covering   | `cover`          | Bidirectional |
+| `deviceType`  | HomeKit service    | HA entity domain | Sync |
+|---------------|--------------------|------------------|------|
+| `switch`      | Switch             | `switch`, `light`, `input_boolean` | Bidirectional |
+| `thermostat`  | Thermostat         | `climate`        | Bidirectional |
+| `blind`       | Window Covering    | `cover`          | Bidirectional |
 | `garageDoor`  | Garage Door Opener | `switch` (pulse relay) | One-way |
+| `sensor`      | Light Sensor       | `sensor` (any numeric) | Read-only |
 
 ### Features
 
@@ -85,6 +91,7 @@ Desde v2.0.0 el plugin es una **dynamic platform**. Mueve la config del bloque `
 - Thermostat: current temperature, target temperature, heating/cooling mode
 - Blind: open/close/stop, position 0–100%, moving state
 - Garage door: pulse relay logic (turn_on → 2s → turn_off)
+- Sensor: read-only numeric values (power, energy, temperature, etc.) — usable in HomeKit automations
 - Config UI X form — no manual JSON editing required
 
 ### Installation
@@ -105,59 +112,82 @@ npm install -g homebridge-homeassistant-things
    - **Poll Interval**: seconds between sync (default `30`)
 3. Click **Save** and restart Homebridge
 
-### Manual config.json examples
+### Manual config.json example
 
-**Switch / Light**
-```json
-{
-  "accessory": "HomeAssistantThing",
-  "name": "Living Room Light",
-  "deviceType": "switch",
-  "haUrl": "http://homeassistant.local:8123",
-  "haToken": "eyJhbGciOiJIUzI1NiIs...",
-  "entityId": "light.living_room",
-  "pollInterval": 30
-}
-```
+Full example with all device types:
 
-**Thermostat**
 ```json
-{
-  "accessory": "HomeAssistantThing",
-  "name": "Living Room Heater",
-  "deviceType": "thermostat",
-  "haUrl": "http://homeassistant.local:8123",
-  "haToken": "eyJhbGciOiJIUzI1NiIs...",
-  "entityId": "climate.living_room",
-  "pollInterval": 30
-}
+"platforms": [
+  {
+    "platform": "HomeAssistantThing",
+    "name": "HA Things",
+    "devices": [
+      {
+        "name": "Living Room Light",
+        "deviceType": "switch",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "light.living_room",
+        "pollInterval": 30
+      },
+      {
+        "name": "Living Room Heater",
+        "deviceType": "thermostat",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "climate.living_room",
+        "pollInterval": 30
+      },
+      {
+        "name": "Living Room Blind",
+        "deviceType": "blind",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "cover.living_room_blind",
+        "pollInterval": 15
+      },
+      {
+        "name": "Garage",
+        "deviceType": "garageDoor",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "switch.garage_relay",
+        "openingTime": 15,
+        "closingTime": 15,
+        "pulseTime": 2000
+      },
+      {
+        "name": "Power Consumption",
+        "deviceType": "sensor",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "sensor.power_consumption_w",
+        "pollInterval": 30
+      },
+      {
+        "name": "Solar Production",
+        "deviceType": "sensor",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "sensor.solar_production_w",
+        "pollInterval": 30
+      }
+    ]
+  }
+]
 ```
 
-**Blind / Shutter**
-```json
-{
-  "accessory": "HomeAssistantThing",
-  "name": "Living Room Blind",
-  "deviceType": "blind",
-  "haUrl": "http://homeassistant.local:8123",
-  "haToken": "eyJhbGciOiJIUzI1NiIs...",
-  "entityId": "cover.living_room_blind",
-  "pollInterval": 15
-}
-```
+### Sensor type — power & energy monitoring
 
-**Garage Door (pulse relay)**
-```json
-{
-  "accessory": "HomeAssistantThing",
-  "name": "Garage",
-  "deviceType": "garageDoor",
-  "haUrl": "http://homeassistant.local:8123",
-  "haToken": "eyJhbGciOiJIUzI1NiIs...",
-  "entityId": "switch.garage_relay",
-  "pollInterval": 30
-}
-```
+The `sensor` device type reads any numeric Home Assistant entity and exposes it as a HomeKit **Light Sensor** (`CurrentAmbientLightLevel`). This is the standard workaround since HomeKit has no native power/energy service.
+
+- The numeric value from HA is passed directly (e.g. `1234` W → shows as `1234` in HomeKit)
+- Works with any `sensor.*` entity: power (W), energy (kWh), temperature, humidity, etc.
+- **Home.app** displays the value with a "lux" unit label — visually incorrect but fully functional for automations
+- **Eve app** displays the same value and supports history graphs
+- Use it in **HomeKit Automations** with numeric thresholds (e.g. "if Solar Production > 2000, turn on dishwasher")
+
+> **Note:** HomeKit's maximum for this characteristic is 100,000. Values above that will be clamped. For most home energy use cases (< 20 kW) this is not an issue.
 
 ### Getting a Home Assistant Long-Lived Access Token
 
@@ -182,6 +212,7 @@ Scheduling is not a HomeKit accessory feature — it must be configured through
 | `thermostat`  | Termostato         | `climate`          | Bidireccional |
 | `blind`       | Persiana           | `cover`            | Bidireccional |
 | `garageDoor`  | Puerta de Garaje   | `switch` (relé pulso) | Unidireccional |
+| `sensor`      | Sensor de Luz      | `sensor` (cualquier numérico) | Solo lectura |
 
 ### Características
 
@@ -190,6 +221,7 @@ Scheduling is not a HomeKit accessory feature — it must be configured through
 - Termostato: temperatura actual, temperatura objetivo, modo calefacción/refrigeración
 - Persiana: abrir/cerrar/parar, posición 0–100%, estado de movimiento
 - Puerta de garaje: lógica de relé de pulso (turn_on → 2s → turn_off)
+- Sensor: valores numéricos de solo lectura (potencia, energía, temperatura, etc.) — utilizables en automatizaciones HomeKit
 - Formulario automático en Config UI X
 
 ### Instalación
@@ -210,59 +242,82 @@ npm install -g homebridge-homeassistant-things
    - **Intervalo Poll**: segundos entre sincronizaciones (por defecto `30`)
 3. Haz clic en **Guardar** y reinicia Homebridge
 
-### Ejemplos de config.json manual
+### Ejemplo de config.json manual
 
-**Interruptor / Luz**
-```json
-{
-  "accessory": "HomeAssistantThing",
-  "name": "Luz Salón",
-  "deviceType": "switch",
-  "haUrl": "http://homeassistant.local:8123",
-  "haToken": "eyJhbGciOiJIUzI1NiIs...",
-  "entityId": "light.salon",
-  "pollInterval": 30
-}
-```
+Ejemplo completo con todos los tipos de dispositivo:
 
-**Termostato / Calefacción**
 ```json
-{
-  "accessory": "HomeAssistantThing",
-  "name": "Calefacción Salón",
-  "deviceType": "thermostat",
-  "haUrl": "http://homeassistant.local:8123",
-  "haToken": "eyJhbGciOiJIUzI1NiIs...",
-  "entityId": "climate.salon",
-  "pollInterval": 30
-}
+"platforms": [
+  {
+    "platform": "HomeAssistantThing",
+    "name": "HA Things",
+    "devices": [
+      {
+        "name": "Luz Salón",
+        "deviceType": "switch",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "light.salon",
+        "pollInterval": 30
+      },
+      {
+        "name": "Calefacción Salón",
+        "deviceType": "thermostat",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "climate.salon",
+        "pollInterval": 30
+      },
+      {
+        "name": "Persiana Salón",
+        "deviceType": "blind",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "cover.persiana_salon",
+        "pollInterval": 15
+      },
+      {
+        "name": "Garaje",
+        "deviceType": "garageDoor",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "switch.rele_garaje",
+        "openingTime": 15,
+        "closingTime": 15,
+        "pulseTime": 2000
+      },
+      {
+        "name": "Consumo eléctrico",
+        "deviceType": "sensor",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "sensor.consumo_watts",
+        "pollInterval": 30
+      },
+      {
+        "name": "Producción solar",
+        "deviceType": "sensor",
+        "haUrl": "http://homeassistant.local:8123",
+        "haToken": "eyJhbGciOiJIUzI1NiIs...",
+        "entityId": "sensor.produccion_solar_watts",
+        "pollInterval": 30
+      }
+    ]
+  }
+]
 ```
 
-**Persiana**
-```json
-{
-  "accessory": "HomeAssistantThing",
-  "name": "Persiana Salón",
-  "deviceType": "blind",
-  "haUrl": "http://homeassistant.local:8123",
-  "haToken": "eyJhbGciOiJIUzI1NiIs...",
-  "entityId": "cover.persiana_salon",
-  "pollInterval": 15
-}
-```
+### Tipo sensor — monitorización de potencia y energía
 
-**Puerta de garaje (relé pulso)**
-```json
-{
-  "accessory": "HomeAssistantThing",
-  "name": "Garaje",
-  "deviceType": "garageDoor",
-  "haUrl": "http://homeassistant.local:8123",
-  "haToken": "eyJhbGciOiJIUzI1NiIs...",
-  "entityId": "switch.rele_garaje",
-  "pollInterval": 30
-}
-```
+El tipo `sensor` lee cualquier entidad numérica de Home Assistant y la expone en HomeKit como **Sensor de Luz** (`CurrentAmbientLightLevel`). Es la solución estándar ya que HomeKit no tiene un servicio nativo de potencia o energía.
+
+- El valor numérico de HA se pasa directamente (p.ej. `1234` W → aparece como `1234` en HomeKit)
+- Compatible con cualquier entidad `sensor.*`: potencia (W), energía (kWh), temperatura, humedad, etc.
+- **App Home** muestra el valor con la etiqueta de unidad "lux" — visualmente incorrecto pero funcional para automatizaciones
+- **App Eve** muestra el mismo valor y soporta gráficos de historial
+- Úsalo en **Automatizaciones HomeKit** con umbrales numéricos (p.ej. "si Producción solar > 2000, encender el lavavajillas")
+
+> **Nota:** El máximo de HomeKit para esta característica es 100.000. Valores superiores se recortarán. Para la mayoría de instalaciones domésticas (< 20 kW) no supone ningún problema.
 
 ### Nota sobre la programación horaria del termostato
 
@@ -270,6 +325,38 @@ La programación horaria no es una función del accesorio HomeKit — debe confi
 
 ---
 
+## Troubleshooting — after upgrading to v2.0.0 or later
+
+From v2.0.0 this plugin changed from `accessory` to `platform`. If Config UI X still generates `"accessory"` instead of `"platform"` after updating, follow these steps:
+
+1. **Uninstall the plugin** from Config UI X → Plugins → `homebridge-homeassistant-things` → Uninstall
+2. **Clear the Homebridge accessory cache**: Config UI X → Settings → scroll down → **Remove All Cached Accessories**
+3. **Restart the Homebridge container/service** completely:
+   - Docker: `docker restart homebridge`
+   - systemd: `sudo systemctl restart homebridge`
+4. **Reinstall the plugin** from Config UI X → search `homebridge-homeassistant-things` → Install
+5. **Add the plugin again** from the Config UI X assistant — it will now generate the correct `"platform"` config
+
+> This is necessary because Config UI X caches the plugin schema. A full restart forces it to reload the schema from the newly installed version.
+
+---
+
+## Solución de problemas — tras actualizar a v2.0.0 o superior
+
+Desde v2.0.0 este plugin cambió de `accessory` a `platform`. Si Config UI X sigue generando `"accessory"` en lugar de `"platform"` tras actualizar, sigue estos pasos:
+
+1. **Desinstala el plugin** desde Config UI X → Plugins → `homebridge-homeassistant-things` → Desinstalar
+2. **Limpia la caché de accesorios**: Config UI X → Ajustes → baja hasta **Eliminar todos los accesorios en caché**
+3. **Reinicia completamente el contenedor/servicio de Homebridge**:
+   - Docker: `docker restart homebridge`
+   - systemd: `sudo systemctl restart homebridge`
+4. **Vuelve a instalar el plugin** desde Config UI X → busca `homebridge-homeassistant-things` → Instalar
+5. **Añade el plugin de nuevo** desde el asistente de Config UI X — ahora generará la config correcta con `"platform"`
+
+> Esto es necesario porque Config UI X cachea el schema del plugin. Un reinicio completo fuerza la recarga del schema desde la versión recién instalada.
+
+---
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for version history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-homeassistant-things",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Homebridge plugin to control Home Assistant devices (switches, thermostats, blinds, garage doors) as native HomeKit accessories",
   "main": "index.js",
   "keywords": [