Integración externa - Zendure

Desarrollo
1

:battery: Zendure (integración externa) — presentación + resumen hasta la v1.3.0

¡Hola a todos! :waving_hand:

Me he dado cuenta de que nunca he abierto un tema dedicado a la integración externa Zendure, aunque existe desde este verano (primera versión el 19 de julio de 2026). Me pongo al día: aquí tenéis una presentación completa y el resumen de las versiones hasta la v1.3.0, que acaba de salir. Este tema servirá luego para anunciar las novedades y recoger vuestros comentarios.

:puzzle_piece: ¿Qué es?

Una integración externa de Gladys para las baterías solares Zendure SolarFlow / Hyper. Funciona en su propio contenedor, se instala desde el catálogo de integraciones (sección Energía) y sube la telemetría de vuestras baterías a Gladys, desde el cloud de Zendure y, si lo deseáis, directamente desde el MQTT local de cada dispositivo.

:sparkles: Funcionalidades soportadas

  • Modelos: SolarFlow 800, 800 Pro, 1600 AC+, 2400 AC+, 2400 AC, 2400 Pro y Hyper 2000 (experimental).
  • 5 mediciones por batería (solo lectura), agrupadas en las categorías de energía de Gladys desde la v1.3.0:
    • Nivel de batería, potencia de carga y potencia de descarga → Batería de almacenamiento;
    • potencia hacia la casa → Sensor de salida de la casa;
    • potencia de entrada solar → Sensor de producción de energía.
  • MQTT local (opcional): valores actualizados cada 1 a 3 segundos en lugar de unos 30 segundos por el cloud, y la telemetría continúa durante una caída del cloud de Zendure o de Internet.
  • Retroceso automático al cloud, dispositivo por dispositivo: si una batería se queda muda localmente, la integración cambia automáticamente al cloud, y vuelve al local tan pronto como los mensajes se reanudan.
  • Insignias de transporte en cada dispositivo: Local, Cloud, Cloud + punto naranja (degradado: el dispositivo debería estar en local pero funciona en el retroceso al cloud, la razón se muestra al pasar el cursor) y Inalcanzable.
  • Estado de conexión en la pantalla de configuración (clave faltante, cloud inalcanzable o clave inválida).
  • Publicación de valores ritmada bajo el límite de solicitudes del núcleo de Gladys, que se ralentiza por sí misma si el núcleo está saturado, para mantenerse con una gran flota (yo tengo unas quince SolarFlow).

:rocket: Instalación

  1. En la aplicación móvil Zendure, sección desarrollador/integración Home Assistant: genera (o copia) tu clave de autorización (la «clave HA»).
  2. En Gladys: Integraciones → busca Zendure → Instalar.
  3. Pestaña Configuración: pega la clave, ajusta el intervalo de actualización si es necesario (30 segundos por defecto), activa eventualmente el MQTT local (zenSDK), y luego Guardar la configuración.
  4. Crea tus baterías desde la pestaña Descubrimiento.

El paso a paso completo está en la documentación de la integración (enlace «Documentación» en la pantalla de configuración).

:scroll: Resumen de versiones

  • v1.0.1 (19 de julio): primera versión: descubrimiento de los SolarFlow 800 Pro a través del cloud de Zendure, telemetría de solo lectura, interrogación periódica y tiempo real MQTT.
  • v1.1.0 (21 de julio): MQTT local con retroceso al cloud por dispositivo y retorno automático al local, insignias de transporte, estado de conexión y 6 modelos SolarFlow/Hyper adicionales.
  • v1.2.0 (24 de julio):
    • insignia degradada (punto naranja) cuando una batería funciona en el retroceso al cloud;
    • documentación FR/EN y sección «Para empezar» en la pantalla de configuración;
    • ritmo de publicación adaptativo bajo el límite del núcleo;
    • fiabilidad: los ecos de nuestras propias solicitudes MQTT ya no falsean la telemetría, intervalo vacío o inválido → 30 segundos, retraso de 15 segundos en el cloud, sin valores en caché republicados durante un corte.
  • v1.3.0 (16 de octubre):
    • las mediciones pasan a las categorías de energía de Gladys (Batería de almacenamiento, Sensor de salida de la casa, Sensor de producción de energía): vuestra batería doméstica ya no cuenta en las alertas «batería baja» de Gladys;
    • las potencias del paquete ahora se llaman Potencia de carga y Potencia de descarga: los nombres antiguos («Battery input/output power») se leían al revés en relación con lo que miden;
    • clasificación en la categoría Energía del catálogo;
    • toda la integración en francés, inglés, alemán y español (configuración, mensajes, documentación);
    • actualización técnica (SDK 0.15, herramientas de lanzamiento, notas de versión en GitHub).

:warning: Requisitos previos

  • Gladys ≥ 4.86.0 para la v1.3.0.
  • Una cuenta de Zendure con vuestras baterías ya en línea en la aplicación.
  • Para el MQTT local: activarlo en la aplicación de Zendure (modo desarrollador).

:counterclockwise_arrows_button: ¿Ya tenías tus baterías antes de la v1.3.0?

Después de la actualización (botón Actualizar de la pestaña Supervisión), vuestras baterías conservan sus antiguas categorías hasta que apliquéis la nueva definición: en la pestaña Descubrimiento, haced clic en Actualizar en cada batería (marcada Ya añadida). Las funcionalidades se actualizan sobre la marcha: el historial, las escenas y los paneles de control se conservan.

:light_bulb: A tener en cuenta

  • Un solo consumidor de cloud por cuenta de Zendure: si Home Assistant o una segunda instancia de Gladys usa la conexión cloud de la misma cuenta, ambas compiten y la telemetría se vuelve intermitente. Para un segundo consumidor, usad el MQTT local, que no tiene este límite. La integración lo señala una vez en sus registros cuando detecta esta situación.
  • Una batería en «Cloud (degradado)» aunque el MQTT local esté activado: su firmware puede haber dejado de publicar localmente sin avisar. En la aplicación de Zendure, desactivad y reactivad el control MQTT de esta batería, y volverá a funcionar en menos de un minuto.
  • Integración bloqueada en «degradado» desde la instalación, con timeouts de WebSocket en los registros: verifica que el firewall de la máquina permita el puerto utilizado por las integraciones externas para unirse a Gladys (ver este tema).

:motorway: Lo que sigue

  • El control de las baterías (órdenes de carga/descarga, límites de salida): es el siguiente gran paso.
  • Mediciones adicionales (índice de carga/descarga, energía restante, salida de emergencia) una vez confirmados sus nombres en datos reales.

:test_tube: Comentarios bienvenidos

¡Gracias de antemano por vuestros comentarios! :folded_hands:

2

:new_button: Actualización: v1.3.1 → v1.5.0

¡Gran día en la integración de Zendure! Aquí está lo que ha llegado desde la v1.3.0:

v1.3.1 — seguridad

  • Actualización de la biblioteca MQTT (6 vulnerabilidades corregidas, de las cuales 4 podían hacer que la integración fallara). La reconexión después de un rechazo del broker (sesión retomada por otro cliente de la cuenta, broker que se reinicia) se conserva.

v1.4.0 — nombres de las características

  • Nueva opción Nombres de las características (francés, inglés, alemán, español): las baterías que creas después tienen sus características en tu idioma. Una batería ya creada conserva sus nombres.
  • Un modelo Zendure no reconocido aparece en la pestaña Registros con su nombre exacto (Unsupported Zendure model skipped: productModel "..."). Cópialo en un issue y lo añado.

v1.5.0 — energía, control y widgets (:warning: Gladys ≥ 5.1.0)

:high_voltage: Energía

  • 4 nuevos contadores en kWh: energía cargada, descargada, solar y enviada a la casa. Zendure solo reporta potencias, por lo que la integración las acumula ella misma. Los contadores sobreviven a los reinicios, y un silencio de más de 5 minutos no se cuenta.
  • La energía solar alimenta directamente los gráficos de producción de Gladys.
  • Energía restante en kWh: el nivel de carga multiplicado por la capacidad de los packs declarados (AB1000, AB2000, AB3000, packs integrados).

:control_knobs: Control desde las escenas (categoría Integraciones)

  • Ajustar el límite de salida, Ajustar el límite de carga (carga AC desde la red), Ajustar el modo AC (carga / descarga), Ajustar los niveles de carga (objetivo 70-100 %, mínimo 0-50 %).
  • Protecciones protegen la batería:
    • los límites se limitan a la potencia nominal del modelo;
    • los límites de potencia se envían en «modo inteligente», se guardan en memoria y no se escriben en la flash;
    • un mismo ajuste no cambia más de una vez cada 3 s (potencia) o 30 s (modo, niveles);
    • un valor ya aplicado no se envía de nuevo.
  • Nuevo disparador Conectividad de una batería: una batería ya no reporta nada, o reporta de nuevo (modo MQTT local).

:bar_chart: Dos widgets de panel de control

  • Batería Zendure: nivel y potencias en tiempo real, fuente (local / nube / fallback / inalcanzable), energía almacenada, límites, modo y niveles de carga actuales. Dos botones abren un formulario prellenado para modificarlos.
  • Grupo de baterías: varias baterías acumuladas bajo un nombre de tu elección. Muestran el nivel medio (ponderado por la capacidad), las potencias totales, la energía almacenada y una línea por batería. En trifásico, coloca un grupo por fase («Fase L1», «L2», «L3») y uno último sin selección para todo el sitio.

:counterclockwise_arrows_button: Para disfrutarlo

  1. Supervisión → Actualizar.
  2. Pestaña Descubrimiento: haz clic en Actualizar en cada batería (marcada «Ya añadida») para añadir las características de energía. El historial, las escenas y los paneles de control se conservan.
  3. Añade los widgets desde la edición del panel de control.

:motorway: Lo siguiente

Gladys aún no tiene un tipo «ajuste» para una batería, por lo que el control por escenas y widgets por ahora. Una PR de núcleo está en curso para añadirlo: límites de potencia de carga y descarga, nivel de carga objetivo, reserva de descarga y modo (feat(battery-storage): add power limit, state-of-charge limit and mode commands by Terdious · Pull Request #3210 · GladysAssistant/Gladys · GitHub). Una vez integrado, estos ajustes serán directamente modificables desde la tarjeta de cada batería.

:test_tube: Comentarios bienvenidos

  • El control en tus modelos: límites, modo AC, niveles de carga. En particular la escala del SOC según los firmwares: infórmame de cualquier comportamiento extraño.
  • Los contadores de energía: ¿son coherentes con la aplicación Zendure en un día?
  • Los widgets de grupo para los que tienen varias baterías.

Registro completo de cambios: gladys-zendure/CHANGELOG.md at master · Terdious/gladys-zendure · GitHub

3

Un pequeño resumen sobre la continuación anunciada: todo está listo en el núcleo, SDK e integración, solo faltan los merges. @pierre-gilles, cuando tengas un momento para revisarlos :smiley:

La PR ha evolucionado mucho con las revisiones. Ahora agrega consignas estándar para las baterías de almacenamiento, válidas para todas las marcas (baterías plug-in, inversores híbridos…):

  • límites de potencia de carga y descarga;
  • límite de carga desde la red: limita la carga AC sin restringir la solar;
  • nivel de carga objetivo y reserva de descarga;
  • modo: automático, carga, descarga, espera, horas valle, emergencia.

Y una nueva categoría « Salida de la casa » con su límite de potencia de salida: la potencia máxima que el dispositivo envía a la casa, solar y batería incluidos. Es el ajuste que más se toca en una SolarFlow, y también sirve para los microinversores (Hoymiles, APsystems, Enphase…). Las mediciones siguen en « Sensor de salida de la casa », como la consigna de un termostato está separada de la medición de temperatura.

En cuanto a la integración, la rama está lista y probada: límite de salida, límite de carga AC, niveles de carga y modo AC (carga/descarga) se vuelven ajustables directamente desde la tarjeta de cada batería. Pasan por los mismos límites de seguridad que las escenas: techo de potencia del modelo, modo inteligente, tasa limitada, valor ya aplicado no devuelto. La tarjeta luego muestra el valor realmente aplicado por la batería. Permanecerá en espera hasta que Gladys conozca estos nuevos tipos. La validaré en mis propias baterías antes del lanzamiento.

¡Gracias de antemano! Tan pronto como estas PR se publiquen, haré la actualización del lado de la integración.