Integración domótica Zendure, gratuita y de código abierto

Conecte sus baterías solares Zendure (SolarFlow) a Gladys Assistant a través de la nube de Zendure.

• Publicado por Terdious
• Dispositivos
• Versión 1.13.0
• Requiere Gladys >=5.1.0
• ★ 0

Ver en GitHubTodas las integraciones

Conecte sus baterías solares Zendure SolarFlow / Hyper a Gladys Assistant. La integración lee la telemetría (nivel de batería, potencias de carga y descarga, salida hacia la casa y producción solar) desde la nube de Zendure y — opcionalmente — directamente desde el broker MQTT local de cada dispositivo, para actualizaciones rápidas y resistentes sin conexión a internet, con respaldo automático en la nube. Los valores son de solo lectura.

Cada batería se lee y se controla a través de su API local (zenSDK) cuando responde en su red — como lo hace Home Assistant — con la nube de Zendure como respaldo automático.

Requisitos previos

• Una cuenta Zendure, con sus baterías ya configuradas y en línea en la aplicación Zendure.
• Gladys Assistant 5.1 o posterior.

Modelos compatibles

SolarFlow 800, SolarFlow 800 Pro, SolarFlow 1600, SolarFlow 2400, SolarFlow 2400 AC, SolarFlow 2400 Pro y Hyper 2000 (experimental — la correspondencia de la telemetría está pendiente de confirmación por un probador de la comunidad).

Hardware no probado: los SolarFlow 800 Plus, SolarFlow 800 Pro 2 y SolarFlow 4000 AC+ se admiten a partir de las características de la integración oficial de Home Assistant (Zendure-HA), sin haber visto aún un aparato real. Si tiene uno, indique cómo se comporta (un informe Diagnóstico de las baterías es ideal) en las issues.

El nombre de modelo que informa la nube de Zendure se reconoce sin tener en cuenta mayúsculas ni espacios (SolarFlow 800 Pro, SolarFlow800Pro), como hace Zendure-HA.

Funcionalidades

Cada batería se crea con diez funcionalidades de solo lectura (más las que dependen del modelo, más abajo), en las categorías de energía de Gladys (gráficos de energía, historial, paneles):

Funcionalidad	Categoría de Gladys	Unidad
Nivel de batería	Almacenamiento en batería	%
Potencia de carga	Almacenamiento en batería	W
Potencia de descarga	Almacenamiento en batería	W
Potencia de salida del hogar	Sensor de salida del hogar	W
Potencia de entrada solar	Sensor de producción de energía	W
Energía cargada	Almacenamiento en batería	kWh
Energía descargada	Almacenamiento en batería	kWh
Energía de salida del hogar	Sensor de salida del hogar	kWh
Energía solar	Sensor de producción de energía	kWh
Energía restante de la batería	Almacenamiento en batería	kWh

Zendure solo informa de potencias: las cuatro funcionalidades de energía (kWh) las calcula la integración, que acumula cada potencia en el tiempo. Son índices acumulados, guardados en el volumen de datos de la integración para que un reinicio no los ponga a cero; un silencio de más de 5 minutos (batería desconectada, broker caído) se descarta en lugar de estimarse. Gladys convierte el índice de energía solar en sus gráficos de producción. La energía restante es el nivel de batería multiplicado por la capacidad de los packs que declara la batería (AB1000, AB2000, AB3000, packs integrados); queda vacía hasta que la batería envía la lista de sus packs.

Desde la versión 1.3.0, el nivel de batería es el de un almacenamiento en batería, no la pila de un dispositivo que hay que cambiar: Gladys ya no cuenta su batería doméstica en sus alertas de batería baja. Una batería creada con una versión anterior conserva sus categorías anteriores hasta que aplique la nueva definición: en la pestaña Descubrir, haga clic en Actualizar en la batería (marcada como Ya añadido). Las funcionalidades se actualizan en el mismo lugar, por lo que se conservan su historial, las escenas y los paneles. Ese mismo Actualizar añade las funcionalidades de energía a una batería creada antes de la versión 1.5.0.

Salida fuera de red, carga desde la red y temperaturas

Según el modelo, una batería recibe también estas funcionalidades:

Funcionalidad	Categoría de Gladys	Unidad	Modelos
Potencia de la salida fuera de red	Sensor de salida del hogar	W	800 Pro, 800 Pro 2, 1600 AC+, 2400 AC, 2400 AC+, 2400 Pro, 4000 AC+
Energía de la salida fuera de red	Sensor de salida del hogar	kWh	los mismos
Potencia de carga desde la red	Sensor de red	W	todos los modelos (carga AC)
Energía cargada desde la red	Sensor de red	kWh	todos los modelos
Temperatura del dispositivo	Sensor de temperatura del aparato	°C	todos los modelos, si se informa
Temperatura del pack más caliente	Sensor de temperatura del aparato	°C	todos los modelos, si se informa
Tiempo de descarga restante	Duración	min	todos los modelos con batería, si se estima
Tiempo de carga restante	Duración	min	todos los modelos con batería, si se estima

• Salida fuera de red: la potencia del enchufe fuera de red (de respaldo) de la batería (gridOffPower). Un valor negativo significa que el enchufe aporta potencia (un panel solar conectado ahí, como señala Zendure-HA): se muestra 0 y no se cuenta.
• Carga desde la red: la potencia que la batería toma de la red para cargarse (gridInputPower), en todos los modelos capaces de cargar en AC.
• Las dos funcionalidades de energía se calculan como las demás (potencia acumulada en el tiempo, guardada en el volumen de datos de la integración, silencios de más de 5 minutos descartados).
• Temperaturas: la temperatura del dispositivo (hyperTmp) y la temperatura más alta de los packs (maxTemp), que Zendure informa en décimas de kelvin y que se convierten a °C. Una batería que no las informa las deja vacías; un valor imposible (por debajo de −40 °C o por encima de 120 °C) se ignora.
• Tiempo restante: el tiempo hasta el límite de descarga (remainOutTime) y hasta el objetivo de carga (remainInputTime), tal como lo estima la batería, en minutos. Cuando la batería no tiene estimación (en reposo, o cargando para el tiempo de descarga), Zendure informa 999 h: ese valor no se publica, la funcionalidad conserva su última estimación y su hora de actualización indica su antigüedad (0 se leería «vacía ahora» y dispararía sus escenas, 999 h aplastaría los gráficos). Un SolarFlow 800 o un Hyper 2000 sin ningún pack no publica nada.

Jerarquía de energía — evitar el doble conteo. La potencia de carga desde la red es un sensor de red: si su vivienda ya tiene un contador principal (contador P1, Shelly EM...) en Gladys, la carga de la batería desde la red ya está incluida en lo que mide. En los ajustes de energía de Gladys, coloque la batería bajo el contador principal (como hija), no a su lado, o la energía que toma se contaría dos veces.

Una batería creada con una versión anterior recibe estas funcionalidades con el mismo Actualizar de la pestaña Descubrir: se conservan las funcionalidades existentes, su historial, las escenas y los paneles.

Packs de batería como dispositivos separados (opcional)

Desactivado por defecto. Con Packs de batería como dispositivos separados activado (pestaña Configuración), la pestaña Descubrir también lista un dispositivo por pack de batería, con el nombre de su batería: Batería del desván — pack 1, Batería del desván — pack 2… Cada dispositivo de pack se identifica por el número de serie del propio pack: sus identificadores nunca chocan con los de la batería.

Funcionalidad	Categoría de Gladys	Unidad	Fuente
Nivel del pack	Batería	%	socLevel
Temperatura del pack	Sensor de temperatura del dispositivo	°C	maxTemp (celda más caliente)
Tensión del pack	Sensor de energía	V	totalVol
Corriente del pack	Sensor de energía	A	batcur, con el signo que da el pack
Potencia del pack	Sensor de energía	W	power, cuando el pack la da

• Un pack aparece en cuanto su batería lo ha listado: en sus informes (API local, nube de Zendure, broker local) o en la lista de dispositivos de Zendure. Si falta un pack, vuelva a abrir la pestaña Descubrir unos minutos después.
• Los valores vienen de la fuente que sirve la batería: la lista de packs del informe de la API local o de la nube (valores brutos, convertidos: centésimas de voltio, décimas de amperio, décimas de kelvin), o los topics MQTT locales del propio pack Zendure/sensor/<número de serie del pack>/… (valores ya en V, A, °C). Pasan por el mismo canal pausado que los de la batería.
• La batería sigue siendo el dispositivo que cuenta en las funcionalidades de energía de Gladys. Por eso el nivel del pack es un simple nivel de Batería, no un nivel de batería doméstica (el de la batería ya lo es: contar cada pack otra vez contaría dos veces la misma carga), y por eso la tensión, la corriente y la potencia son simples medidas: deje los dispositivos de pack fuera de la jerarquía de energía de Gladys. Único efecto secundario: si activó la notificación de batería baja de Gladys, un pack por debajo de su umbral en el momento de la comprobación aparece en ella.
• El estado de salud de los packs se queda en el diagnóstico.
• Desactivar la opción no crea nada nuevo ni elimina nada: los dispositivos de pack ya creados se quedan en Gladys con su historial, pero dejan de actualizarse. Elimínelos en Gladys si ya no los quiere (vea Eliminar una batería): la integración los ignora entonces.

Obtener su clave de la nube de Zendure

La integración se autentica ante la nube de Zendure con una clave de autorización (un token base64) que usted genera una sola vez desde la aplicación móvil Zendure:

1. Abra la aplicación Zendure e inicie sesión con su cuenta.
2. Vaya a la sección desarrollador / integración Home Assistant de la aplicación y genere (o copie) su clave de autorización (también llamada "clave HA").
3. Copie esa clave.

La clave es un secreto vinculado a su cuenta Zendure: manténgala privada. Gladys la almacena cifrada y nunca la escribe en los registros.

Configuración

1. Abra la pestaña Configuración de la integración en Gladys.
2. Pegue su clave en Clave de autorización de la nube de Zendure.
3. Ajuste el Intervalo de actualización (segundos) — la frecuencia con la que se refresca la telemetría cuando no llegan actualizaciones en tiempo real. El valor por defecto (30 s) es adecuado.
4. (Opcional) Active Activar el MQTT local (zenSDK) — vea más abajo.
5. (Opcional) Elija el idioma de los Nombres de las funcionalidades (inglés por defecto): se aplica a las baterías que cree a partir de ahora.
6. (Opcional) Active Packs de batería como dispositivos separados para un dispositivo más por pack (desactivado por defecto) — vea Packs de batería como dispositivos separados.
7. (Instalación trifásica) En Instalación eléctrica, ponga Instalación eléctrica en Trifásica y coloque cada batería en Baterías de la fase L1, Baterías de la fase L2 o Baterías de la fase L3, la fase que alimenta. Los widgets Instalación Zendure y Energía de hoy la leen aquí (vea Widgets del panel). Una instalación monofásica la deja como está.
8. Haga clic en Guardar configuración. Sus baterías aparecen en la pestaña Descubrir, listas para añadirse.

API local (zenSDK, activada por defecto)

Las baterías SolarFlow (800, 800 Plus, 800 Pro, 800 Pro 2, 1600 AC+, 2400 AC, 2400 AC+, 2400 Pro, 4000 AC+ — todos los modelos compatibles salvo el Hyper 2000) ofrecen una pequeña API HTTP en su red doméstica, llamada zenSDK. Es lo que usa la integración oficial de Home Assistant para estos modelos: ni MQTT ni la nube. Con Usar la API local de las baterías activado (por defecto), la integración lee cada batería a través de ella cada 5 segundos, y también envía por ella los comandos de las escenas y los widgets.

• Requisitos previos: la batería y el host de Gladys en la misma red (el contenedor debe poder alcanzar la dirección IP de la batería: sin Wi-Fi de invitados aislado ni VLAN de por medio), y un firmware reciente: actualice la batería desde la aplicación Zendure si su API local no responde. Los pasos propios de un modelo, si los hay, están en la wiki de Zendure-HA (p. ej. su página del SolarFlow 800).
• Dirección: la integración toma la dirección IP de la batería de la nube de Zendure. Cuando la nube no la da, prueba el nombre mDNS de la batería zendure-<modelo>-<número de serie>.local, que rara vez se resuelve dentro de un contenedor Docker: rellene entonces Direcciones de la API local con pares número de serie=dirección IP, separados por comas (p. ej. HOA1NAH4N123456=192.168.1.42). Dar una IP fija a sus baterías en el router ayuda.
• Respaldo automático: una batería que falla tres peticiones seguidas pasa enseguida a su broker MQTT local si lo activó; a la nube de Zendure solo pasa tras 90 segundos sin respuesta (un corte breve del Wi-Fi no ocupa la conexión a la nube), y vuelve en cuanto su API local responde de nuevo. Al arrancar, una batería tiene los mismos 90 segundos para dar su primera respuesta. Una batería que nunca respondió simplemente sigue en la nube, sin insignia de aviso.
• La nube queda en reposo: cuando todas las baterías responden en local, la integración no se conecta en absoluto al broker de la nube de Zendure, y Home Assistant (u otra aplicación) con la misma cuenta Zendure conserva la única conexión a la nube de la cuenta.

MQTT local (recomendado si lo utiliza)

Cuando activa el MQTT local en la aplicación Zendure (modo desarrollador), cada dispositivo publica su telemetría en un broker local de su red. Con Activar el MQTT local (zenSDK) en Gladys, la integración lee desde ese broker:

• Más rápido: los valores locales se actualizan cada 1–3 s en lugar de unos 30 s a través de la nube.
• Resistente: la telemetría sigue llegando durante una caída de la nube de Zendure o de internet.
• Respaldo automático: si un dispositivo deja de publicar en el broker local, la integración pasa sola a la nube y vuelve a lo local en cuanto se reanudan los mensajes locales — sin ninguna acción por su parte.

Insignias de transporte

Cada dispositivo muestra una insignia que indica cómo se le alcanza en este momento:

• Local (verde) — servido por su broker MQTT local (lo normal cuando el MQTT local está activado).
• Nube (azul) — servido por la nube de Zendure (lo normal cuando el MQTT local está desactivado).
• Nube + punto naranja (degradado) — el dispositivo debería estar en local pero está temporalmente en el respaldo en la nube (su broker local dejó de publicar). Pase el ratón por encima de la insignia para ver el motivo. Desaparece por sí solo cuando el dispositivo vuelve a publicar en local.
• Inaccesible (rojo) — la nube de Zendure indica que el dispositivo está desconectado, o no publica en ninguna fuente.

Con la API local, Local significa que su API local o su broker local sirve el dispositivo. El motivo del estado degradado indica qué fuente local se ha callado.

Control desde las escenas

Gladys aún no tiene una funcionalidad de consigna para baterías: las baterías se controlan desde las escenas (y desde el widget del panel). En una escena, añada una acción de la categoría Integraciones.

Acción	Efecto
Ajustar el límite de salida	Potencia máxima entregada al hogar (W)
Ajustar el límite de carga	Potencia máxima tomada de la red, carga AC (W)
Ajustar el modo AC	Cargar desde la red o descargar hacia el hogar
Ajustar los niveles de carga	Objetivo de carga (70-100 %) y mínimo de descarga (0-50 %)

La integración protege la batería:

• un límite se limita a la potencia nominal de la batería (p. ej. 800 W de salida en una SolarFlow 800 Pro);
• los límites de potencia se envían en "modo inteligente", guardados en memoria en lugar de escribirse en la flash de la batería (los cambios frecuentes la desgastarían);
• un mismo ajuste no puede cambiar más de una vez cada 3 s (límites de potencia) o 30 s (modo AC, niveles de carga): una escena que lo intenta antes falla indicando el tiempo de espera;
• un valor que la batería ya aplica no se vuelve a enviar (la salida de acción Comando enviado es entonces falsa);
• los niveles de carga se rechazan hasta que la batería informa de los suyos (su escala difiere según el firmware).

El comando pasa por el broker que sirve la batería en ese momento (local o nube); el nuevo valor aparece con el siguiente informe de la batería.

El disparador Accesibilidad de una batería inicia una escena cuando una batería deja de informar en todas las fuentes, o vuelve a hacerlo (API local o MQTT local). Sus variables dan el nombre de la batería, el nuevo estado y la fuente de telemetría.

El disparador Alerta de batería inicia una escena cuando un estado de una batería empieza o termina. Sus filtros, todos opcionales (vacíos: cualquier valor):

• Batería: una batería;
• Alerta: Fallo (indicador de error is_error, o nivel de fallo faultLevel mayor que 0), Calefacción (la calefacción de los packs funciona, heatState), Calibración (la calibración del estado de carga está en curso, socStatus), Temperatura baja (lowTemperature), Flujo inverso (reverseState);
• Cambio: Empieza o Termina.

Sus variables dan el nombre de la batería, la alerta, el cambio (started / ended), el código informado (el nivel de fallo para un fallo) y la fuente de telemetría (local / cloud). Ejemplos:

• recibir un aviso cuando una batería se calienta: disparador Alerta de batería, Alerta Calefacción, Cambio Empieza, y luego una acción Enviar un mensaje que nombra la batería con las variables;
• recibir un aviso de un fallo, y de su fin: una escena con Alerta Fallo y Cambio Empieza, otra con Cambio Termina.

Una alerta solo se dispara con un cambio: el estado de una batería al iniciar la integración (o al volver a crearla) es su estado inicial, no un evento. Un nuevo estado debe mantenerse 30 segundos, en al menos dos informes, antes de que la escena empiece: un código que parpadea durante un informe nunca la dispara. Una batería eliminada en Gladys y los dispositivos de pack no disparan ninguna alerta.

Widgets del panel

En el editor del panel hay cuatro widgets disponibles (Gladys 5.1 o posterior):

• Batería Zendure: una batería, elegida en los ajustes del widget. Sus cuatro potencias siguen la batería en directo; su nivel y las líneas de debajo se actualizan cada dos minutos (varía como mucho un 1 % por minuto): su fuente (local, nube, respaldo, inaccesible), la energía almacenada, los límites de salida y de carga, el modo AC y los niveles de carga que informa. Los botones Límites de potencia y Modo y niveles abren un formulario rellenado con los valores actuales: cambie lo necesario y confirme. Se aplican las mismas protecciones que en las acciones de escena.
• Grupo de baterías: varias baterías sumadas bajo el nombre que elija: nivel medio (ponderado por la capacidad de los packs cuando todas son conocidas), potencias totales, energía almacenada y una línea por batería coloreada según su fuente. Deje la lista de baterías vacía para tomar todas las baterías de la cuenta.
• Instalación Zendure: toda la instalación en una tarjeta. Elija la Instalación eléctrica: Según la configuración de la integración (por defecto, recomendado) usa la instalación y las fases de la sección Instalación eléctrica de la configuración; Monofásica suma las baterías elegidas en el widget (ninguna: todas); Trifásica toma las baterías de las listas Baterías de la fase L1, L2 y L3 del widget. La tarjeta muestra los totales de la instalación (nivel ponderado por la capacidad de los packs, carga, descarga, solar, salida al hogar, energía almacenada), luego en trifásica una línea por fase (⌂ salida al hogar, ↑ carga, ↓ descarga, ☀ solar, en W) y el Equilibrio de fases: la diferencia entre la salida al hogar más alta y la más baja, en naranja por encima de la Alerta de desequilibrio (500 W por defecto). Debajo: energía almacenada sobre la capacidad conocida, tiempo restante a la potencia actual, número de baterías por fuente (local, nube, inaccesible) y líneas de alerta para las baterías inaccesibles, los respaldos en la nube y una batería puesta en dos fases, en ninguna o eliminada. Una batería inaccesible conserva su nivel y su energía almacenada, pero sus últimas potencias quedan fuera de las sumas.
• Energía de hoy: la energía del día desde la medianoche local, con la misma elección de instalación y las mismas listas de fases: cargada, descargada, solar y salida al hogar (kWh), una línea por fase en trifásica con la diferencia entre fases, y un gráfico de la salida al hogar cada 30 minutos (una curva por fase). El día empieza a la medianoche de la Zona horaria del widget (un nombre IANA, Europe/Paris por defecto: Gladys no da su zona horaria a una integración). Las cifras vienen de los contadores de energía de la integración (guardados en /data con una instantánea cada 30 minutos, conservada 8 días): cuentan desde el primer informe del día, que indica la línea Contado desde (por ejemplo tras una primera instalación por la mañana). Con una tarifa eléctrica en la configuración, también muestra la estimación del ahorro (vea Ahorro (estimación) más abajo).

Ejemplo trifásico: 18 baterías en L1, L2 y L3. En la pestaña Configuración, sección Instalación eléctrica, ponga la Instalación eléctrica en Trifásica y marque en Baterías de la fase L1 las seis baterías conectadas a L1 (por ejemplo dos 2400 AC, una 2400 Pro, dos 800 Pro y un 800 sin batería), en Baterías de la fase L2 las seis de L2 y en Baterías de la fase L3 las seis de L3, y guarde. Añada un widget Instalación Zendure y un widget Energía de hoy, y deje su Instalación eléctrica en Según la configuración de la integración: no hay nada más que elegir. La tarjeta de la instalación muestra los totales, una línea por fase como L1 (6) · 60 % — ⌂ 1890 · ↑ 500 · ↓ 1000 · ☀ 1400 W, y Equilibrio de fases — Δ 1490 W · L1 la más alta en naranja por encima del umbral; la tarjeta de energía los kWh del día por fase. Una instalación monofásica conserva en todo los valores por defecto. El widget Grupo de baterías sigue disponible para cualquier otra agrupación.

Por qué las fases están en la configuración: Gladys guarda como máximo 1 KB de ajustes por widget, y cada batería marcada en una lista del widget ocupa unos 50 caracteres (su identificador). Por encima de unas 15 baterías en las listas del widget, el widget ya no puede mostrarse ni el panel guardarse (error 422 settings: must be at most 1024 bytes). La configuración no tiene ese límite, y las fases se definen allí una vez para los dos widgets. Un widget en Según la configuración de la integración con una configuración trifásica sin ninguna batería asignada muestra todas las baterías en monofásica, con una línea de aviso Ninguna fase asignada; las fases rellenadas en una configuración monofásica se ignoran (línea Fases ignoradas). Los widgets configurados antes en Monofásica o Trifásica conservan sus propias listas y siguen funcionando. Un widget que ya supera el límite: quítelo del panel y vuelva a añadirlo (o vacíe sus listas), dejando Según la configuración de la integración.

Curvas, periodos y orden: los widgets Grupo de baterías e Instalación Zendure trazan una curva en directo de las últimas horas, elegida en su ajuste Curva: Potencias (carga, descarga, solar y hogar sumadas), Potencia al hogar, Nivel de carga (ponderado por la capacidad de los packs) o Sin curva, sobre el Periodo de la curva (3, 6, 12 o 24 horas, 6 por defecto). En trifásica, Potencia al hogar (el defecto de la instalación) y Nivel de carga trazan una curva por fase (L1, L2, L3). La integración registra estos valores cada 5 minutos durante las últimas 48 horas (en /data, con los contadores de energía): tras una actualización, las curvas se llenan a partir de ese momento. La curva de Energía de hoy ofrece Al hogar, Cargada, Descargada, Solar (una por fase en trifásica), Todos los flujos o Sin curva. Las líneas de baterías de un grupo siguen su Orden de la lista: Por nombre (por defecto, en orden natural: L1.2 antes de L1.10, igual en cada fase), Según la selección, mayor Nivel de carga o mayor Potencia al hogar primero.

Cada widget con curva lleva un botón Periodo y botones Anterior / Siguiente, como los gráficos de Gladys. En Grupo de baterías e Instalación Zendure, el periodo es de 3, 6, 12 o 24 horas, y Anterior retrocede un periodo, hasta las últimas 48 horas. En Energía de hoy, el periodo es un día o 7 días (una barra por día): Anterior retrocede día a día, o semana a semana, durante los últimos 8 días, y un periodo pasado muestra una línea Mostrado con sus fechas. Las tarjetas y líneas siguen el periodo mostrado; la estimación del ahorro solo aparece para hoy. Gladys guarda 8 elementos por widget, botones incluidos: las tarjetas que no caben se convierten en las primeras líneas. Un widget solo muestra su nombre como título si su Título está relleno. El periodo se conserva por widget hasta el reinicio de la integración. Zendure no guarda un historial más largo: sin vista por mes ni por año. Coloque Instalación Zendure y Energía de hoy en una sección del panel de una o dos columnas.

Cada widget solo muestra lo que la batería tiene: un SolarFlow 800 usado sin pack de batería conserva su solar, su salida al hogar y su límite de salida (sin nivel, sin cifras de carga ni botón Modo y niveles), y un modelo acoplado en AC (1600 AC+, 2400 AC, 2400 AC+) no tiene mosaico solar. Mientras la batería carga o descarga, el widget muestra el tiempo restante hasta su objetivo de carga o su mínimo de descarga, tal como lo informa la batería (o calculado a partir de su capacidad cuando no lo da). Un grupo deja fuera las baterías sin pack de su nivel medio y de su energía almacenada, y un grupo de tales dispositivos solo muestra sus potencias.

Ahorro (estimación)

Con su tarifa eléctrica, la integración estima lo que ahorran sus baterías, cada 30 minutos, por batería, y el widget Energía de hoy lo suma para sus baterías (la instalación, o cada fase). Es una estimación sin contador de red, marcada como tal en el widget: lea los límites más abajo.

Configurar la tarifa

En la pestaña Configuración, sección Ahorro (estimación, sin contador):

• Tarifa eléctrica: Ninguna (por defecto: sin estimación), Base (un solo precio) o Punta / valle.
• Precio base, o Precio punta y Precio valle: el precio de un kWh comprado a la red, impuestos incluidos (por ejemplo 0,15). Un precio que falta desactiva la estimación.
• Horas valle: franjas HH:MM-HH:MM separadas por comas, por ejemplo 22:00-06:00 o 01:30-07:30,12:30-14:30. Una franja puede pasar la medianoche; 24:00 se acepta como fin. Unas horas no válidas desactivan la estimación: los registros y el diagnóstico dicen por qué (una vez), y el widget muestra Tarifa no válida.
• Vendo mi excedente solar y Precio de reventa: activado, la energía solar almacenada en las baterías se valora al precio de reventa (lo que habría aportado en la red); desactivado, la energía solar almacenada es gratuita.
• Zona horaria de la tarifa (nombre IANA, Europe/Paris por defecto): las horas valle, y los días, meses y años del ahorro, la siguen, cambios de hora incluidos. Es un ajuste de la integración y no del widget porque las franjas se valoran en segundo plano, al cerrarse, aunque no haya ningún widget abierto; la Zona horaria del widget sigue fijando la medianoche de sus cifras de energía.

En el widget Energía de hoy, Mostrar el ahorro (estimación) está activado por defecto: solo muestra algo cuando hay una tarifa configurada.

Cómo se calcula

Para cada batería y cada franja de 30 minutos, a partir de sus contadores de energía:

• Precio de la franja: el precio base, o el precio punta / valle a la hora local de la franja (una franja a caballo sobre el borde de un rango se calcula a prorrata).
• Coste de la energía almacenada: una media ponderada por batería. La energía cargada desde la red (el contador Energía cargada desde la red) cuesta el precio de la franja; el resto de la carga, de los paneles solares, cuesta el precio de reventa si vende su excedente, 0 si no. La energía almacenada se vuelve a leer del nivel de carga cuando se conocen los packs.
• Salida al hogar: sin contador de red, la integración no puede saber lo que se inyectó, así que la energía enviada al hogar se supone consumida por la vivienda. Su parte procedente de la batería ahorra precio de la franja − coste de la energía almacenada (una batería cargada en punta y descargada en valle ahorra menos que nada); su parte procedente directamente de los paneles ahorra el precio de la franja; el resto (la red que atraviesa una batería AC) no ahorra nada.
• Ahorro = desplazamiento batería + solar directo (+ ingreso por reventa, con el contador de red). La línea Carga de red (pagada) es informativa: ese coste ya está en el coste de la energía almacenada.

El widget muestra Ahorro hoy (estimación), el mes y el año, el día por fase en trifásica, y el detalle del día (desplazamiento batería, solar directo, carga de red pagada, inyección). Los totales del día, mes y año en curso y anteriores se guardan en /data/energy.json con los contadores de energía (un archivo de una versión anterior se carga tal cual; el ahorro empieza en el primer límite de 30 minutos tras la actualización).

Límites

• Sin conocimiento de la inyección: la salida al hogar devuelta a la red (consumo de la vivienda inferior a la salida de la batería) se cuenta como ahorrada al precio de la franja. La línea Inyectado, sin valorar (o Reventa si vende) se queda en 0 hasta que se pueda leer el contador de red.
• Baterías AC (1600 AC+, 2400 AC, 2400 AC+, 4000 AC+): su carga AC se cuenta como carga de red al precio de la franja, incluso cuando en realidad viene del excedente solar de otro inversor: solo el balance de la instalación (el contador de red) podría saberlo.
• Las pérdidas de los packs, las pérdidas de conversión y los informes perdidos hacen que las cifras sean aproximadas; el ahorro empieza cuando se configura la tarifa (nada se recalcula hacia atrás), y un cambio de tarifa se aplica a las franjas que se cierran después.
• La moneda es la de sus precios; el widget escribe €.

Próximamente

Dos opciones aparecerán en la configuración en cuanto Gladys las ofrezca a las integraciones (cambios de Gladys en curso: #3229 y #3230):

• Usar los precios del seguimiento de energía de Gladys, en lugar de escribirlos aquí.
• Contador de red (monofásico, o trifásico L1 / L2 / L3): para saber lo que realmente se consume o inyecta, valorar la reventa y las pérdidas, y distinguir el excedente solar de la carga desde la red en las baterías AC.

Un solo consumidor de la nube por cuenta Zendure

Zendure solo permite un consumidor de la nube por cuenta a la vez. Si otra aplicación usa la conexión a la nube de la misma cuenta (Home Assistant, una segunda instancia de Gladys…), ambas se disputan la conexión y la telemetría se vuelve intermitente. Para cualquier segundo consumidor, prefiera el MQTT local — el broker local no tiene ese límite. La integración avisa una vez en sus registros cuando detecta este fenómeno de toma de la conexión.

Con la API local activada (por defecto), la integración solo se conecta al broker de la nube de Zendure mientras una batería lo necesita, y se desconecta 5 minutos después de que la última batería que lo necesitaba vuelva a una fuente local: si sus baterías responden en local, Home Assistant y Gladys ya no se disputan la conexión a la nube.

Eliminar una batería

Eliminar una batería en Gladys (su página de dispositivo, Eliminar) detiene todo lo que la integración hace por ella, al instante y sin reinicio: su API local deja de consultarse, sus topics del broker se dan de baja, deja de contar para el respaldo en la nube (el broker de la nube se libera enseguida si ninguna otra batería lo necesita: Home Assistant recupera la sesión en la nube de la cuenta), y sale de los logs del watchdog, de los widgets del panel, de las acciones de escena y del diagnóstico (que la lista una vez como ignorada). Los logs lo dicen en una línea: 1 device(s) ignored (deleted in Gladys): ….

La lista de baterías eliminadas se guarda con la configuración de la integración en Gladys: un reinicio o una actualización no las devuelve. La batería sigue en la pestaña Descubrir: créela de nuevo allí y vuelve a seguirse al instante, con los mismos identificadores.

Actualizar la integración

Instalada desde el catálogo (el caso habitual): Gladys consulta el store con regularidad. Cuando sale una nueva versión, la integración muestra la insignia "Actualización disponible" (también contada junto a Integraciones en el menú), y su pestaña Supervisión indica la versión ofrecida, con un enlace a sus notas de versión. Haga clic en Actualizar: Gladys descarga la nueva imagen y aplica el nuevo manifiesto — los nuevos campos de configuración aparecen solos, no hay nada que volver a pegar. Su configuración y sus dispositivos se conservan.

Gladys puede tardar hasta una hora y media aproximadamente en detectar una nueva versión (actualización del índice del store). "Forzar actualización" lo comprueba de inmediato: lee la última versión publicada y descarga su imagen.

Instalada en modo desarrollador (manifiesto pegado a mano): "Forzar actualización" solo vuelve a descargar la imagen de la etiqueta instalada, y la versión mostrada y los campos de configuración provienen del manifiesto pegado — vuelva a pegar el manifiesto actualizado para obtener los nuevos campos.

Solución de problemas

• Una batería no se descubre. Abra la pestaña Registros: una línea Unsupported Zendure model skipped: productModel "..." indica el nombre de modelo exacto que devuelve la nube de Zendure. Abra una issue en gladys-zendure con ese nombre para que se añada el modelo.
• Un dispositivo no muestra ningún valor (o va más lento que los demás) mientras el resto funciona. Revise su insignia de transporte. Si ha pasado a Nube (degradado) con el MQTT local activado, puede que su firmware haya dejado de publicar en local sin avisar. En la aplicación Zendure, ponga el control MQTT de ese dispositivo en OFF, guarde y vuelva a ponerlo en ON — vuelve a publicar en menos de un minuto. Mientras tanto, la integración pasa por la nube y vuelve a lo local automáticamente.
• Too Many Requests en los registros. La integración espacia sus actualizaciones por debajo del límite de peticiones del núcleo de Gladys y se regula sola si hace falta; las ráfagas ocasionales no tienen consecuencias. Un flujo persistente suele deberse a una segunda instancia de la integración (por ejemplo, un contenedor de producción y otro de pruebas en paralelo) que comparte el mismo presupuesto del núcleo — mantenga solo una.
• Todo está en silencio justo después de la configuración. Compruebe que la clave de la nube es correcta: una clave no válida o caducada muestra el estado "La nube de Zendure no está disponible o la clave de la nube no es válida." en la pantalla de configuración.
• Detalle completo. Defina LOG_LEVEL=debug y lea los registros de la integración en su pestaña Registros (o con docker logs en el host). Cada cambio de fuente de telemetría se registra en una línea telemetry:.
• Una batería sigue en la nube aunque su API local debería funcionar. Al arrancar, los registros listan cada batería que no responde, con la dirección probada y el motivo, p. ej. local http: Garage (dCLTD95V) not answering at 192.168.1.42 (from the cloud): EHOSTUNREACH. ENOTFOUND en un nombre .local significa que el mDNS no se resuelve en el contenedor: indique su dirección en Direcciones de la API local. EHOSTUNREACH, ECONNREFUSED o no answer within 2 s significan que el contenedor no alcanza la batería (otra red, VLAN, cortafuegos) o que su firmware aún no tiene API local. Cada 5 minutos, una línea telemetry(local http): resume qué baterías responden.

Diagnóstico

Dos botones de solo lectura, en la pestaña Configuración de la integración, reconstruyen todo el panorama a petición, sin rebuscar en los registros. Ninguno escribe en una batería ni cambia su transporte.

• Diagnóstico de las baterías: un informe de texto de la instalación — la versión de la integración, la configuración (nunca la clave de la nube), la API de la nube de Zendure, cada broker (conectado o no, reconexiones de los últimos 5 minutos, broker de la nube en reposo porque todas las baterías son locales, avisos de toma de sesión), el sondeo de la API local, y luego un bloque por batería: la fuente que la sirve y por qué, la antigüedad de sus últimos datos en cada fuente, la dirección de su API local (de las opciones, de la nube o mDNS) y su estado, los packs, la entrada solar, los ajustes que informa (límites, modo AC, niveles de carga), el tiempo restante y los contadores de energía, y luego las versiones de firmware (dispositivo, maestro, DSP, packs), la señal Wi-Fi (rssi, con una indicación por debajo de −75 dBm) y los estados de conexión, los códigos de estado en bruto (calefacción, baja temperatura, calibración y límite de SoC, bypass, HEMS, nivel de fallo) y, por pack, su nivel, la temperatura de su celda más caliente, su tensión, su corriente y su estado de salud. Elija una batería en la lista Batería (las baterías creadas en Gladys) para describir solo esa; para una batería no creada en Gladys, escriba su nombre o número de serie en el campo de abajo.
• Probar la API local de una batería: lee una vez, ahora, GET /properties/report en la dirección que usa la integración, y muestra el tiempo de respuesta, el origen de la dirección y todas las propiedades que devuelve la batería — o el error exacto con una pista (ENOTFOUND en un nombre .local: rellene Direcciones de la API local; EHOSTUNREACH, ECONNREFUSED o un tiempo agotado: red o firmware).

Por defecto, los números de serie se acortan (WOB1…0159) y las direcciones locales se sustituyen por <local-ip>: pegue el informe tal cual en una issue de GitHub, entre dos líneas de tres comillas invertidas. Mostrar los números de serie y direcciones locales los muestra completos, solo para sus propias comprobaciones: no publique esa versión. Ningún informe contiene nunca la clave de la nube ni una contraseña. Ambos informes se escriben también, ocultados, en los registros de la integración.

Parámetros de configuración

Estos son los parámetros que Zendure te pide en su pantalla de configuración en Gladys.

Parámetro	Tipo	Obligatorio	Descripción
Primeros pasos	section	No	Pegue abajo su clave de autorización de la nube de Zendure (generada desde la aplicación móvil Zendure). Sus baterías SolarFlow / Hyper aparecen entonces en la pestaña Descubrir. Cada batería se sirve entonces por su API local cuando responde en su red (como hace Home Assistant), con respaldo automático en la nube de Zendure; el MQTT local sigue siendo una opción para firmwares antiguos. El paso a paso completo está en el enlace Documentación de arriba.
Clave de autorización de la nube de Zendure	secret	Sí	La clave de autorización generada desde la aplicación móvil Zendure (token base64 utilizado para acceder a la API de la nube de Zendure).
Intervalo de actualización (s)	number	No	Frecuencia con la que se consulta la telemetría de los dispositivos, en segundos.
Usar la API local de las baterías	boolean	No	Leer y controlar cada batería a través de su API HTTP local zenSDK en su red (la que usa Home Assistant), cada pocos segundos. Una batería que no responde sigue en la nube de Zendure, automáticamente.
Direcciones de la API local (opcional)	string	No	Solo para una batería cuya API local no se encuentra (sin dirección de la nube, nombre mDNS no resuelto): pares número de serie=dirección IP, separados por comas.
Activar el MQTT local (zenSDK)	boolean	No	Leer también la telemetría desde el broker MQTT local del dispositivo cuando esté disponible (firmwares antiguos, Hyper 2000), antes de la nube de Zendure.
Nombres de las funcionalidades	select	No	Idioma de los nombres de funcionalidades de las baterías recién descubiertas. Una batería ya creada conserva sus nombres: cambie el nombre de sus funcionalidades en Gladys si es necesario.
Packs de batería como dispositivos separados	boolean	No	Desactivado por defecto. Activado: la pestaña Descubrir también lista un dispositivo por pack de batería (nivel, temperatura, tensión, corriente, potencia), con el nombre de su batería. Desactivarlo no crea nada nuevo ni elimina nada: los dispositivos de pack ya creados se quedan y dejan de actualizarse.
Instalación eléctrica	section	No	La usan los widgets del panel «Instalación Zendure» y «Energía de hoy» configurados en «Según la configuración de la integración» (su valor por defecto). En una instalación trifásica, ponga cada batería en la fase que alimenta (L1, L2, L3): una sola vez aquí, para todos los widgets. Gladys limita los ajustes de un widget a 1 KB, unas 15 baterías: una instalación grande no puede guardar allí sus fases.
Instalación eléctrica	select	No	Monofásica: los widgets de la instalación suman todas las baterías. Trifásica: por fase, según las tres listas de abajo.
Baterías de la fase L1	multi_select	No	Solo trifásica: cada batería en la fase que alimenta.
Baterías de la fase L2	multi_select	No	Solo trifásica: cada batería en la fase que alimenta.
Baterías de la fase L3	multi_select	No	Solo trifásica: cada batería en la fase que alimenta.
Ahorro (estimación, sin contador)	section	No	Opcional. Con su tarifa eléctrica, la integración estima cada 30 minutos lo que ahorran sus baterías: la energía enviada al hogar se supone consumida por la vivienda (sin contador de red nada indica lo que se inyecta), valorada al precio del momento, menos el coste de la energía almacenada (carga desde la red a su precio, carga solar al precio de reventa o gratuita). El widget «Energía de hoy» la muestra para hoy, este mes y este año. Detalles y límites en el enlace Documentación de arriba.
Tarifa eléctrica	select	No	Ninguna: sin estimación del ahorro. Base: un solo precio. Punta / valle: dos precios y las horas valle.
Precio base (por kWh)	number	No	Tarifa base: el precio de un kWh comprado a la red, impuestos incluidos (€/kWh).
Precio punta (por kWh)	number	No	Tarifa punta / valle: el precio de un kWh fuera de las horas valle, impuestos incluidos (€/kWh).
Precio valle (por kWh)	number	No	Tarifa punta / valle: el precio de un kWh durante las horas valle, impuestos incluidos (€/kWh).
Horas valle	string	No	Franjas HH:MM-HH:MM separadas por comas, en la zona horaria de la tarifa; una franja puede pasar la medianoche. Horas no válidas: sin estimación (ver los registros).
Vendo mi excedente solar	boolean	No	Activado: la energía solar almacenada en las baterías se valora al precio de reventa (lo que habría aportado), y la energía inyectada contará como ingreso en cuanto se pueda leer un contador de red. Desactivado: la energía solar almacenada es gratuita.
Precio de reventa (por kWh)	number	No	El precio pagado por un kWh de excedente solar inyectado a la red (€/kWh). Solo se usa si la opción de arriba está activada.
Zona horaria de la tarifa	string	No	Nombre IANA, p. ej. Europe/Paris (por defecto): las horas valle y los días, meses y años del ahorro la siguen, cambios de hora incluidos.
Próximamente	section	No	Dos opciones aparecerán aquí en cuanto Gladys las ofrezca a las integraciones (cambios de Gladys en curso, enlazados abajo): «Usar los precios del seguimiento de energía de Gladys», en lugar de los precios de arriba; y «Contador de red (monofásico, o trifásico L1 / L2 / L3)», para saber lo que realmente se consume o inyecta, valorar la reventa y las pérdidas, y distinguir excedente solar y carga desde la red en las baterías AC. Hasta entonces, el ahorro es una estimación.

Cómo instalar Zendure en Gladys

1. En Gladys, abre Integraciones: Zendure aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/terdious/gladys-zendure:1.13.0), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/Terdious/gladys-zendure.

Zendure 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

Zendure 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 Terdious, 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

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂