Intégration : OpenFamily (organisation familiale open source)

Bonjour,

Je suis Quentin, je développe OpenFamily, un organisateur familial open source et auto-hébergé (liste de courses, tâches, calendrier, planning de la semaine, repas, budget), en français et en sept autres langues : 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

Nous avons déjà des intégrations avec Home Assistant, Nextcloud, Mealie, Grocy et Immich, et je me dis que Gladys et OpenFamily se complètent bien : vous gérez la maison, nous gérons la vie de famille qui s’y déroule. J’ai lu la spec des intégrations externes et le fil sur les listes de tâches et de courses (10601) : c’est précisément ce qu’OpenFamily sait faire.

Ce que j’imagine, côté Gladys, sous la forme d’une intégration externe publiée dans votre store (donc sans travail pour vous) :

- le calendrier de la famille comme calendrier Gladys (type « calendar »), avec les rendez-vous qui déclenchent des scènes ;

- des widgets de tableau de bord : le programme du jour, la liste de courses, les tâches ;

- des actions de scène « ajouter à la liste de courses » et « ajouter une tâche », et un déclencheur sur les rappels de rendez-vous.

Avant de coder, deux questions :

1. Est-ce que cette forme vous paraît la bonne, ou préférez-vous une autre voie ?

2. Y a-t-il des contraintes du store ou du SDK que je devrais connaître pour un premier jet ?

Je suis preneur de retours, et ouvert à une collaboration plus large entre les deux projets.

Salut Quentin, et bienvenue sur le forum ! :waving_hand:

Merci pour la démarche, et d’avoir lu la spec avant de coder :slightly_smiling_face: Je suis d’accord sur la complémentarité : Gladys gère la maison, OpenFamily la vie de famille. Le fil sur les listes de courses et de tâches (10601) montre qu’il y a une vraie demande.

1. La forme : oui, c’est la bonne

Fais une seule intégration externe de type: "calendar". Elle peut déclarer en plus des widgets, des scene_actions et des scene_triggers, car tous les types peuvent ajouter ces capacités à leur rôle principal.

Le modèle le plus proche dans le store est ICS Calendars (GitHub - guim31/gladys-ics-calendar: Remote iCalendar (.ics) calendars for Gladys Assistant: Google Calendar secret address, school, waste collection · GitHub). Il fait exactement ça : un calendrier, un widget « Prochains événements », des déclencheurs et une action. Pour les listes, regarde Bring! (https://github.com/LM1LC3N7/gladys-bring) et 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). Ils couvrent déjà les courses et les tâches, c’est une bonne source d’inspiration pour l’expérience utilisateur.

Quelques précisions sur chaque point :

  • Le calendrier fonctionne en « push » : ton intégration synchronise, Gladys stocke.
    • Les calendriers envoyés alimentent la vue calendrier et les scènes, comme ceux du CalDAV natif.
    • C’est à sens unique : Gladys n’écrit jamais dans OpenFamily.
    • Chaque utilisateur active l’intégration pour lui-même, dans le bloc « Mes calendriers ». Les calendriers sont privés par défaut.
    • Un calendrier doit être partagé pour que tout le foyer le voie et qu’il puisse déclencher des scènes.
    • Attention aux doublons : si tu envoies le calendrier familial à chaque membre et que chacun le partage, il apparaîtra plusieurs fois. Mieux vaut l’envoyer à un seul compte.
  • Rappels de rendez-vous : tu n’as pas besoin de ton propre déclencheur.
    • Le déclencheur natif « Un évènement dans le calendrier arrive » fonctionne directement sur les calendriers envoyés. On peut le régler un peu avant le début ou la fin d’un rendez-vous, avec un filtre sur le nom.
    • Je ne créerais un déclencheur maison que si les rappels OpenFamily contiennent une info que Gladys n’a pas, par exemple un rappel réglé à la main dans OpenFamily. Ça évite deux façons de faire la même chose.
  • Widgets : ils sont déclaratifs. Ton intégration renvoie un contenu avec un vocabulaire fixe (liste, liste d’états, tuiles, boutons…) et Gladys se charge de l’affichage (thème, mode sombre, mobile). Un widget sert à afficher des données et à les toucher :
    • Ajouter un article ou une tâche depuis le widget, c’est possible : un bouton peut ouvrir un petit formulaire (4 champs maximum) que ton intégration déclare.
    • Cocher un article : il n’y a pas encore de case à cocher par ligne. Tu peux contourner avec un bouton « Cocher » qui ouvre une liste de choix (champ select) contenant les articles en cours, générée au moment de l’affichage. Si c’est trop limitant à l’usage, ouvre un sujet : les formulaires derrière les boutons sont justement nés d’un retour de ce genre.
    • Gladys récupère le contenu et le garde en cache pendant la durée que tu fixes (ttl_seconds). Quand une liste change côté OpenFamily, envoie un widget.refresh pour mettre à jour les widgets.
  • Actions de scène : « ajouter à la liste de courses » et « ajouter une tâche » s’y prêtent parfaitement, et les champs texte acceptent les variables de scène.
    • Pense aussi à une action « lire la liste » qui renvoie un résultat (outputs). Une scène pourra par exemple envoyer la liste de courses par message quand tu quittes le travail.
    • Comme déclencheurs, « article ajouté », « tâche terminée » ou « tâche à échéance » viennent naturellement.

2. Contraintes du store et du SDK pour un premier jet

  • Publication :

    • un dépôt GitHub public avec le topic gladys-assistant-integration ;
    • le manifeste gladys-assistant-integration.json à la racine ;
    • une doc obligatoire en français et en anglais (docs/fr.md et docs/en.md), d’au moins 300 caractères chacune, avec les sections Présentation / Prérequis / Configuration / Dépannage ;
    • une image de couverture facultative, en 800×534 et 150 Ko maximum.

    L’indexation est automatique, toutes les heures, sans validation de notre part. Si ton intégration n’apparaît pas, la raison est indiquée dans rejected.json. Pour faire tester avant l’indexation, il suffit de passer par « Installer depuis GitHub » avec l’URL du dépôt.

  • Image Docker : elle doit être sur un registre public et construite pour amd64 et arm64, car beaucoup de Gladys tournent sur Raspberry Pi. Pars du template GitHub - GladysAssistant/integration-template-js: Gladys Assistant Integration template for a JS external integration · GitHub : il contient déjà le workflow de build pour les deux architectures vers GHCR.

  • Conteneur :

    • utilisateur non root, système de fichiers en lecture seule ;
    • /data est le seul dossier conservé ;
    • CPU et mémoire limités.

    Le réseau sortant est ouvert : une instance OpenFamily auto-hébergée sur le réseau local est joignable par son URL. Seuls le mDNS et le broadcast entrants ne passent pas.

  • SDK : le SDK officiel est en Node.js (@gladysassistant/integration-sdk). Si tu préfères un autre langage, l’API REST/WebSocket est documentée. Tu peux aussi développer hors Docker avec un jeton de dev.

  • Secrets : mets l’URL et le jeton OpenFamily dans le config_schema, avec le type secret qui n’est jamais renvoyé au navigateur. Si chaque membre a ses propres identifiants, utilise plutôt l’account_schema. Ne les mets jamais dans les réglages d’un widget ou les champs d’une scène : la validation du manifeste le refuse.

  • Calendrier, côté technique :

    • les external_id doivent commencer par ext:<selector>:<user>: ;
    • c’est à toi de calculer les occurrences des événements récurrents (on conseille 12 mois à l’avance) ;
    • pour supprimer des événements, tu renvoies une période complète (window) ;
    • limites : 500 événements par requête, 30 écritures par minute, 50 calendriers par utilisateur et 10 000 événements par calendrier.
  • Widgets : 5 au maximum par intégration et 8 éléments au maximum par widget. Les images doivent être servies par ton intégration (PNG, JPEG ou WebP, 300 Ko maximum), jamais via une URL externe chargée par le navigateur.

  • gladys_version : indique la version minimale de Gladys qui gère ce que tu utilises. Une version plus ancienne refuse un manifeste dont elle ne connaît pas les champs.

Toute la doc est ici : Créer une intégration externe | Gladys Assistant (sections « Calendriers : le type calendar », « Widgets de tableau de bord » et « Déclencheurs et actions de scène »).

Merci Pierre-Gilles, c’est très clair et ça répond à tout !
On part donc sur une intégration de type calendar avec widgets, actions et déclencheurs, en s’inspirant d’ICS Calendars, Bring! et Todoist.
Première étape de notre côté : un jeton d’API dans OpenFamily, pour que l’intégration s’authentifie proprement (config_schema en type secret).
Ensuite le dépôt à partir du template, testé sur un Gladys local via « Installer depuis GitHub ».
Je reviens ici avec un premier dépôt à essayer.

Si cela fonctionne bien je suis preneur pour remplacer l’appli family wall qui n’est pas open source

Bonjour Pierre-Gilles,

C’est fait : l’intégration OpenFamily est en ligne, GitHub - NexaFlowFrance/gladys-openfamily: OpenFamily for Gladys Assistant: the family calendar, shopping list and tasks on the dashboard and in scenes. · GitHub. Elle suit ton brief : type calendar, trois widgets (aujourd’hui, courses, tâches) avec formulaires pour ajouter et cocher, quatre actions de scène et trois déclencheurs. Côté OpenFamily, on a ajouté des jetons d’API pour l’occasion.

Le template, le SDK et le validateur du store sont très agréables à utiliser, merci pour ce travail. Testée sur une Gladys 5.3.3 en Docker.

Deux retours au passage, si ça peut servir :

  1. Quand le fuseau n’est pas réglé dans les paramètres, les conteneurs d’intégration reçoivent TZ=UTC alors que le cœur retombe sur Europe/Paris. Les heures locales sont alors décalées. J’ai ajouté un réglage de fuseau de mon côté.
  2. Avec Gladys en mode bridge sous Docker Desktop (Windows), l’intégration n’arrivait pas à joindre gladys:80, le réseau gladys-integrations étant créé sans communication entre conteneurs. Pas vérifié sous Linux.

Tous les retours sont bienvenus, de toi comme de la communauté.

Merci @QuentinCazier pour cette nouvelle intégration !

J’en ai profité pour modifier le titre :slight_smile:
Et je vais tester dans pas trop longtemps :wink:

On attend avec impatience la nouvelle intégration :wink:

Bon, je n’avais pas vu le github :sweat_smile:

Ca arrive un peu de patience :smiley:
J’ai mis Gladys en tête de liste, on privilégiera toujours des applications et autre qui partagent la même philosophie que nous :slight_smile:

Edit :
C’est tout bon :wink: