Integración: OpenFamily (organización familiar de código abierto)

Hola,

Soy Quentin, desarrollo OpenFamily, un organizador familiar de código abierto y autoalojado (lista de la compra, tareas, calendario, horario semanal, comidas, presupuesto), en francés y en siete idiomas más: GitHub - NexaFlowFrance/OpenFamily: The open-source, self-hosted family organizer. Keep full control of your family's data : run it on your own server. · GitHub

Ya tenemos integraciones con Home Assistant, Nextcloud, Mealie, Grocy e Immich, y creo que Gladys y OpenFamily se complementan bien: ustedes gestionan la casa, nosotros gestionamos la vida familiar que ocurre en ella. He leído la especificación de las integraciones externas y el hilo sobre las listas de tareas y de la compra (10601): es exactamente lo que sabe hacer OpenFamily.

Lo que imagino, en el lado de Gladys, en forma de una integración externa publicada en su tienda (por lo que no hay trabajo para ustedes):

- el calendario familiar como calendario Gladys (tipo « calendario »), con las citas que activan escenas;

- widgets de panel de control: el programa del día, la lista de la compra, las tareas;

- acciones de escena « añadir a la lista de la compra » y « añadir una tarea », y un disparador en los recordatorios de citas.

Antes de codificar, dos preguntas:

1. ¿Les parece esta forma la correcta, o prefieren otra vía?

2. ¿Hay restricciones de la tienda o del SDK que debería conocer para un primer borrador?

Estoy abierto a comentarios y a una colaboración más amplia entre los dos proyectos.

¡Hola Quentin, y bienvenido al foro! :waving_hand:

Gracias por el gesto, y por haber leído la especificación antes de codificar :slightly_smiling_face: Estoy de acuerdo en la complementariedad: Gladys gestiona la casa, OpenFamily la vida familiar. El hilo sobre las listas de compras y tareas (10601) muestra que hay una verdadera demanda.

1. La forma: sí, es la correcta

Haz una sola integración externa de type: "calendar". Puede declarar además de widgets, scene_actions y scene_triggers, ya que todos los tipos pueden añadir estas capacidades a su rol principal.

El modelo más cercano en la tienda es ICS Calendars (GitHub - guim31/gladys-ics-calendar: Remote iCalendar (.ics) calendars for Gladys Assistant: Google Calendar secret address, school, waste collection · GitHub). Hace exactamente eso: un calendario, un widget “Próximos eventos”, desencadenadores y una acción. Para las listas, mira Bring! (GitHub - LM1LC3N7/gladys-bring: Gladys Assistant external integration for Bring! shopping lists: lists on the dashboard, add and check off items, scene action “add an item”, scene trigger “item added”. Unofficial, not affiliated with Bring! Labs. · GitHub) y Todoist (GitHub - LM1LC3N7/gladys-todoist: Gladys Assistant external integration for Todoist: today’s tasks on the dashboard, add and complete tasks from scenes, a “task due” scene trigger. Unofficial, not affiliated with Doist. · GitHub). Ya cubren las compras y las tareas, es una buena fuente de inspiración para la experiencia del usuario.

Algunas precisiones sobre cada punto:

  • El calendario funciona en “push”: tu integración sincroniza, Gladys almacena.
    • Los calendarios enviados alimentan la vista de calendario y las escenas, como los del CalDAV nativo.
    • Es de un solo sentido: Gladys nunca escribe en OpenFamily.
    • Cada usuario activa la integración para sí mismo, en el bloque “Mis calendarios”. Los calendarios son privados por defecto.
    • Un calendario debe ser compartido para que toda la familia lo vea y pueda desencadenar escenas.
    • Cuidado con los duplicados: si envías el calendario familiar a cada miembro y cada uno lo comparte, aparecerá varias veces. Es mejor enviarlo a una sola cuenta.
  • Recordatorios de citas: no necesitas tu propio desencadenador.
    • El desencadenador nativo “Un evento en el calendario está llegando” funciona directamente en los calendarios enviados. Se puede ajustar un poco antes del inicio o final de una cita, con un filtro en el nombre.
    • No crearía un desencadenador casero a menos que los recordatorios de OpenFamily contengan información que Gladys no tenga, por ejemplo, un recordatorio ajustado manualmente en OpenFamily. Así se evitan dos formas de hacer lo mismo.
  • Widgets: son declarativos. Tu integración devuelve un contenido con un vocabulario fijo (lista, lista de estados, baldosas, botones…) y Gladys se encarga de la visualización (tema, modo oscuro, móvil). Un widget sirve para mostrar datos y tocarlos:
    • Añadir un artículo o una tarea desde el widget, es posible: un botón puede abrir un pequeño formulario (4 campos máximo) que tu integración declara.
    • Marcar un artículo: aún no hay una casilla de verificación por línea. Puedes sortearlo con un botón “Marcar” que abre una lista de opciones (campo select) que contiene los artículos en curso, generada en el momento de la visualización. Si es demasiado limitante en el uso, abre un tema: los formularios detrás de los botones nacieron justo de un comentario de este tipo.
    • Gladys recupera el contenido y lo guarda en caché durante la duración que tú fijas (ttl_seconds). Cuando una lista cambia en OpenFamily, envía un widget.refresh para actualizar los widgets.
  • Acciones de escena: “añadir a la lista de compras” y “añadir una tarea” se prestan perfectamente, y los campos de texto aceptan las variables de escena.
    • Piensa también en una acción “leer la lista” que devuelve un resultado (outputs). Una escena, por ejemplo, podría enviar la lista de compras por mensaje cuando salgas del trabajo.
    • Como desencadenadores, “artículo añadido”, “tarea terminada” o “tarea con fecha límite” vienen naturalmente.

2. Limitaciones de la tienda y del SDK para un primer borrador

  • Publicación:

    • un repositorio GitHub público con el tema gladys-assistant-i* el manifiesto gladys-assistant-integration.json` en la raíz;
    • una documentación obligatoria en francés y en inglés (docs/fr.md y docs/en.md), de al menos 300 caracteres cada una, con las secciones Presentación / Requisitos previos / Configuración / Solución de problemas;
    • una imagen de portada opcional, de 800×534 y un máximo de 150 Ko.

    La indexación es automática, cada hora, sin validación por nuestra parte. Si tu integración no aparece, la razón se indica en rejected.json. Para hacer una prueba antes de la indexación, basta con pasar por « Instalar desde GitHub » con la URL del repositorio.

  • Imagen Docker: debe estar en un registro público y construida para amd64 y arm64, ya que muchos Gladys funcionan en Raspberry Pi. Parte del template https://github.com/GladysAssistant/integration-template-js: ya contiene el flujo de trabajo de construcción para las dos arquitecturas hacia GHCR.

  • Contenedor:

    • usuario no root, sistema de archivos de solo lectura;
    • /data es la única carpeta conservada;
    • CPU y memoria limitadas.

    La red saliente está abierta: una instancia OpenFamily autoalojada en la red local es accesible mediante su URL. Solo el mDNS y el broadcast entrantes no pasan.

  • SDK: el SDK oficial está en Node.js (@gladysassistant/integration-sdk). Si prefieres otro lenguaje, la API REST/WebSocket está documentada. También puedes desarrollar fuera de Docker con un token de desarrollo.

  • Secretos: coloca la URL y el token OpenFamily en el config_schema, con el tipo secret que nunca se envía al navegador. Si cada miembro tiene sus propias credenciales, usa mejor el account_schema. Nunca los pongas en la configuración de un widget o en los campos de una escena: la validación del manifiesto lo rechaza.

  • Calendario, lado técnico:

    • los external_id deben comenzar con ext:<selector>:<user>:;
    • es tu responsabilidad calcular las ocurrencias de los eventos recurrentes (se recomienda 12 meses por adelantado);
    • para eliminar eventos, envías un período completo (window);
    • límites: 500 eventos por solicitud, 30 escrituras por minuto, 50 calendarios por usuario y 10,000 eventos por calendario.
  • Widgets: máximo 5 por integración y 8 elementos por widget. Las imágenes deben ser servidas por tu integración (PNG, JPEG o WebP, máximo 300 Ko), nunca a través de una URL externa cargada por el navegador.

  • gladys_version: indica la versión mínima de Gladys que gestiona lo que usas. Una versión más antigua rechaza un manifiesto del que no conoce los campos.

Toda la documentación está aquí: Créer une intégration externe | Gladys Assistant (secciones « Calendarios: el tipo calendar », « Widgets de tablero de control » y « Disparadores y acciones de escena »).

¡Gracias, Pierre-Gilles, es muy claro y responde a todo!
Por lo tanto, nos basamos en una integración de tipo calendario con widgets, acciones y desencadenantes, inspirándonos en ICS Calendars, Bring! y Todoist.
Primera etapa de nuestro lado: un token de API en OpenFamily, para que la integración se autentifique correctamente (config_schema de tipo secreto).
Luego el repositorio a partir de la plantilla, probado en un Gladys local a través de « Instalar desde GitHub ».
Vuelvo aquí con un primer repositorio para probar.

Si funciona bien, me interesa reemplazar la aplicación family wall que no es de código abierto

Hola Pierre-Gilles,

Ya está hecho: la integración OpenFamily está en línea, GitHub - NexaFlowFrance/gladys-openfamily: OpenFamily for Gladys Assistant: the family calendar, shopping list and tasks on the dashboard and in scenes. · GitHub. Sigue tus indicaciones: tipo calendario, tres widgets (hoy, compras, tareas) con formularios para añadir y marcar, cuatro acciones de escena y tres disparadores. Por parte de OpenFamily, hemos añadido tokens de API para la ocasión.

La plantilla, el SDK y el validador de la tienda son muy agradables de usar, gracias por este trabajo. Probado en una Gladys 5.3.3 en Docker.

Dos comentarios de paso, por si sirven:

  1. Cuando la zona horaria no está configurada en los parámetros, los contenedores de integración reciben TZ=UTC mientras que el núcleo vuelve a Europa/París. Las horas locales están entonces desplazadas. He añadido una configuración de zona horaria por mi parte.
  2. Con Gladys en modo bridge bajo Docker Desktop (Windows), la integración no podía conectarse a gladys:80, ya que la red gladys-integrations se creaba sin comunicación entre contenedores. No verificado en Linux.

Todos los comentarios son bienvenidos, tanto de ti como de la comunidad.

¡Gracias @QuentinCazier por esta nueva integración!

Aproveché para modificar el título :slight_smile:
Y voy a probarlo en un ratito :wink:

¡Esperamos con impaciencia la nueva integración :wink:

Bueno, no había visto el github :sweat_smile:

Un poco de paciencia :smiley:
He puesto a Gladys en la lista de prioridades, siempre daremos preferencia a aplicaciones y otras cosas que compartan nuestra misma filosofía :slight_smile:

Edición :
¡Todo listo! :wink: