Integración domótica SolaX Power, gratuita y de código abierto
Inversores SolaX mediante el dongle Wi-Fi local: producción solar, red, batería, contadores.
Publicado por guim31
- Dispositivos
- Versión 1.0.2
- Requiere Gladys >=5.1.0
- ★ 0
Presentación
Esta integración lee sus inversores SolaX (X1, X3, X-Hybrid, Boost, Mini, Smart, Hybrid G3/G4, Ultra, MIC PRO, Lite LV y el Q.VOLT de Qcells, mismo hardware) en su red local, a través del dongle Wi-Fi o LAN del inversor (Pocket WiFi). Cada inversor se convierte en un dispositivo de Gladys con su producción solar, sus contadores de energía, el intercambio con la red, la batería de los híbridos y el estado del inversor. SolaX Cloud es una opción para los dongles que no responden en local.
Es de solo lectura: la integración nunca envía al inversor otra cosa que una petición de sus datos en tiempo real.
Desarrollada sin el hardware: sus comentarios son bienvenidos. La decodificación sigue las respuestas reales publicadas con la biblioteca
solaxque utiliza Home Assistant, pero nunca se ha ejecutado frente a un inversor real. Cuente lo que observe en el foro de Gladys o en las issues de GitHub.
Esta integración no está afiliada a SolaX Power (not affiliated with SolaX Power).
Requisitos
- Gladys Assistant 5.1.0 o posterior (5.2 para el seguimiento de energía del índice de producción).
- Un inversor SolaX con su dongle Pocket WiFi (V2 o V3) o Pocket LAN, conectado a la misma red que Gladys. Asigne al dongle una dirección IP fija en su router.
- El número de registro del dongle (10 caracteres, impreso en el dongle, también visible en la aplicación SolaX Cloud): los firmwares recientes lo usan como contraseña de la interfaz local.
- Solo para SolaX Cloud: una cuenta en solaxcloud.com y su token de la API (Service → API en el sitio nuevo, Support → Third-party ecology en el antiguo).
Configuración
Abra Integraciones → SolaX Power → Configuración:
| Campo | Qué introducir |
|---|---|
| Direcciones IP de los dongles | Una dirección por inversor, separadas por comas (192.0.2.10, 192.0.2.11). Se puede indicar un puerto (192.0.2.10:8080). |
| Contraseñas de los dongles | El número de registro de cada dongle, en el orden de las direcciones. Un único valor sirve para todos. Vacío en los firmwares antiguos. |
| Modelo de inversor | Automático (recomendado): el modelo se detecta a partir de la respuesta del dongle. Fuércelo solo si las medidas parecen incorrectas. |
| Actualización local | Cada 10, 15, 30 (por defecto) o 60 segundos. |
| Token de la API de SolaX Cloud | Solo para la opción en la nube. |
| Números de registro | El número de registro de cada dongle que se leerá mediante SolaX Cloud, separados por comas. |
| Actualización en la nube | Cada 5 (por defecto), 10, 15 o 30 minutos. |
| Idioma de los textos | Nombres de las funciones (fijados al añadir el dispositivo), estado del inversor, textos de las escenas. Francés por defecto. |
Después haga clic en Probar la conexión: para cada inversor, indica el modelo encontrado o lo que falla. Los inversores encontrados aparecen en la pestaña Descubrir: añádalos a Gladys.
Cuota de SolaX Cloud. SolaX permite 10 llamadas por minuto y 10 000 al día por token, y el dongle envía sus datos cada 5 minutos. Por eso la integración lee cada inversor de la nube cada 5 minutos como mucho, deja 6,5 segundos entre llamadas (nunca más de 10 por minuto, sea cual sea el número de inversores) y alarga el periodo cuando los inversores superarían 9000 llamadas al día. Un inversor configurado a la vez en local y en la nube solo se lee en local.
Lo que muestra cada dispositivo
Un dispositivo por inversor, llamado SolaX <modelo> <final del número de serie>. Las funciones
dependen de lo que indique el modelo; una función mostrada no desaparece nunca.
| Función | Tipo de Gladys | Notas |
|---|---|---|
| Potencia FV | potencia de producción (W) | Suma de los strings. |
| Potencia FV string 1, 2, 3 | potencia de producción (W) | Cuando el inversor tiene varios strings. |
| Producción de hoy | producción diaria (kWh) | El inversor la pone a cero a medianoche. |
| Producción total | índice de producción (kWh) | El contador acumulado del seguimiento de energía. Nunca se publica a la baja. |
| Potencia de salida CA | potencia (W) | Negativa en un híbrido que carga su batería desde la red. |
| Red (importación +, exportación −) | potencia de la red (W) | Requiere el contador SolaX (pinza). Positiva al importar. |
| Índice de importación de la red, de exportación | índices de la red (kWh) | Los contadores del contador SolaX. |
| Nivel de batería | nivel de batería (%) | Híbridos. |
| Potencia de carga, de descarga de la batería | almacenamiento en batería (W) | Una de las dos vale 0 en todo momento. |
| Temperatura de la batería | temperatura del dispositivo (°C) | Cuando se indica. |
| Índice de carga, de descarga de la batería | índices del almacenamiento en batería (kWh) | Cuando se indican. |
| Temperatura del inversor | temperatura del dispositivo (°C) | Cuando se indica. |
| Estado del inversor | texto | Normal, En espera, Fallo, Respaldo (EPS), En reposo... Cuando se indica. |
| En línea | binario | 0 cuando el dongle no responde (de noche en la mayoría de los inversores). |
La insignia del dispositivo muestra local, nube o inaccesible. Los valores solo se envían a Gladys cuando cambian, y al menos cada 6 horas si no cambian.
Widget
Vista solar (panel → añadir un widget → SolaX Power): la potencia FV, la producción de hoy, el intercambio con la red y la batería en mosaicos en directo, la curva de 24 horas de la producción y de la red, y una lista breve: exportación o importación, carga o descarga, estado del inversor, hora de la última medida. Elija el inversor en la configuración del widget (no hace falta si solo hay uno).
Disparador de escena
El estado del inversor ha cambiado: se activa cuando el inversor pasa a otro estado (por
ejemplo de Normal a Fallo, o a Respaldo (EPS) durante un corte de luz). Filtros: el inversor y los
nuevos estados que le interesen. Variables: status (código: normal, fault, eps...),
previous_status, status_label (el estado en el idioma de la configuración). Solo los modelos
que indican un estado pueden activarlo (X3 Hybrid G4, X3 Ultra, X3 MIC PRO G2 y cualquier inversor
leído mediante SolaX Cloud).
Acción de escena
Obtener el balance solar: devuelve la última medida de un inversor sin volver a consultar el
dongle: summary (una frase como «Solar: 3,1 kW ahora, 12,4 kWh hoy. Red: exportación 830 W.
Batería: 86 %.»), online, pv_power, yield_today, grid_power, battery_level.
Ejemplos de escenas
- Balance de la noche: todos los días a las 21:00 → Obtener el balance solar → enviar un
mensaje con
{{summary}}. - Fallo del inversor: El estado del inversor ha cambiado, nuevo estado Fallo o Fallo permanente → enviar una notificación «El inversor está en fallo: {{status_label}}».
- Aprovechar el excedente: cuando Red (importación +, exportación −) baja de −1500 W → encender el enchufe del termo eléctrico; apagarlo cuando vuelva a superar 0 W.
- Corte de luz: El estado del inversor ha cambiado, nuevo estado Respaldo (EPS) → apagar los aparatos no esenciales y avisar a la familia.
Modelos compatibles
Detectados según el type que indica el dongle: X-Hybrid (primera generación), X1/X3 G3 (Hybrid,
Fit, MIC, Air, Boost, Mini), X1-Boost/Mini (tipos 4, 18, 22), X1-Smart, X1-Hybrid G4, X3-Hybrid G3
con firmware 2.034, X3-Hybrid G4 y Q.VOLT HYB-G3-3P, X3-MIC PRO G2, X3-Ultra, X1-Lite LV. El punto
de recarga X3-EVC no es un inversor y se rechaza.
Solución de problemas
- «Sin respuesta»: compruebe la dirección, que Gladys y el dongle están en la misma red y que el dongle tiene alimentación: la mayoría de los inversores apagan el dongle por la noche, el dispositivo muestra entonces Sin conexión hasta la mañana.
- «Rechazado: compruebe la contraseña»: introduzca el número de registro del dongle (no el número de serie del inversor).
- «Modelo no reconocido»: abra una issue con la salida de
node scripts/probe.mjs <dirección> [número de registro](solo lectura; el número de registro se oculta en la salida). - Valores incorrectos: fuerce el modelo en la configuración y notifíquelo.
- Firmware 2.034 y posteriores: algunos dongles rechazan la red local. La integración envía la cabecera que esperan esos firmwares; si sigue fallando, use SolaX Cloud.
- Más detalles en los registros: configure
LOG_LEVEL=debugen la integración.
Límites
- Solo lectura: no se modifica ningún ajuste del inversor (modo de funcionamiento, carga, límite de exportación), a propósito.
- Algunos dongles no responden en local: use SolaX Cloud, actualizado cada 5 minutos como mucho.
- Los valores de la red requieren el contador SolaX; sin él, se quedan en 0.
- La producción por media hora del panel de energía de Gladys la calcula el núcleo a partir del índice de producción; Gladys 5.2.1 aún no la enlaza automáticamente para las integraciones externas.
- El significado de algunos registros procede de la comunidad, no de SolaX: un modelo ausente de las muestras puede leer mal algunos valores.
Parámetros de configuración
Estos son los parámetros que SolaX Power te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Conexión local | section | No | Gladys lee el inversor a través de su dongle Wi-Fi o LAN de SolaX (Pocket WiFi), en la red local. Asigne al dongle una dirección IP fija en su router. Solo lectura: nunca se modifica nada en el inversor. |
| Direcciones IP de los dongles | string | No | Una dirección por inversor, separadas por comas. |
| Contraseñas de los dongles | secret | No | El número de registro impreso en cada dongle (10 caracteres), en el mismo orden que las direcciones. Déjelo vacío en los firmwares antiguos. |
| Modelo de inversor | select | No | Se detecta automáticamente. Fuércelo solo si las medidas parecen incorrectas. |
| Actualización local | select | No | |
| SolaX Cloud (opcional) | section | No | Solo para los dongles que no responden en local. El token de la API está en Service, API de solaxcloud.com. SolaX permite 10 llamadas por minuto y 10 000 al día, y el dongle envía cada 5 minutos: como mucho una medida cada 5 minutos. |
| Token de la API de SolaX Cloud | secret | No | |
| Números de registro | string | No | El número de registro de cada dongle que se leerá mediante SolaX Cloud, separados por comas. |
| Actualización en la nube | select | No | |
| Visualización | section | No | |
| Idioma de los textos | select | No | Nombres de las funciones (fijados al añadir el dispositivo), estado del inversor y textos de las escenas. |
Cómo instalar SolaX Power en Gladys
- En Gladys, abre Integraciones: SolaX Power aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/guim31/gladys-solax:1.0.2), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-solax.
SolaX Power requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
SolaX Power es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene guim31, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación