Integration: OpenFamily (Open-Source-Familienorganisation)

Hallo,

Ich bin Quentin, ich entwickle OpenFamily, einen Open-Source- und selbstgehosteten Familienorganisator (Einkaufsliste, Aufgaben, Kalender, Wochenplan, Mahlzeiten, Budget) auf Französisch und in sieben weiteren Sprachen: 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

Wir haben bereits Integrationen mit Home Assistant, Nextcloud, Mealie, Grocy und Immich, und ich denke, dass Gladys und OpenFamily sich gut ergänzen: Sie verwalten das Haus, wir verwalten das Familienleben, das darin stattfindet. Ich habe die Spezifikationen für externe Integrationen und den Thread zu Aufgaben- und Einkaufslisten (10601) gelesen: Genau das kann OpenFamily.

Was ich mir auf Gladys-Seite in Form einer externen Integration vorstelle, die im Store veröffentlicht wird (also ohne Arbeit für Sie):

- Der Familienkalender als Gladys-Kalender (Typ « calendar »), mit Terminen, die Szenen auslösen;

- Dashboard-Widgets: Tagesplan, Einkaufsliste, Aufgaben;

- Szenenaktionen « zur Einkaufsliste hinzufügen » und « Aufgabe hinzufügen », und ein Auslöser für Terminerinnerungen.

Bevor ich mit dem Codieren beginne, zwei Fragen:

1. Erscheint Ihnen diese Form die richtige, oder bevorzugen Sie einen anderen Weg?

2. Gibt es Store- oder SDK-Beschränkungen, die ich für einen ersten Entwurf kennen sollte?

Ich bin offen für Feedback und bereit für eine engere Zusammenarbeit zwischen den beiden Projekten.

Hallo Quentin, und willkommen im Forum! :waving_hand:

Danke für die Initiative und dafür, dass du die Spezifikation gelesen hast, bevor du mit dem Codieren begonnen hast :slightly_smiling_face: Ich stimme der Komplementarität zu: Gladys verwaltet das Haus, OpenFamily das Familienleben. Der Thread zu den Einkaufs- und Aufgabenlisten (10601) zeigt, dass es eine echte Nachfrage gibt.

1. Die Form: Ja, das ist die richtige

Mache eine einzige externe Integration von type: "calendar". Sie kann zusätzlich zu widgets, scene_actions und scene_triggers deklarieren, da alle Typen diese Fähigkeiten zu ihrer Hauptrolle hinzufügen können.

Das nächste Modell im Store ist ICS Calendars (GitHub - guim31/gladys-ics-calendar: Remote iCalendar (.ics) calendars for Gladys Assistant: Google Calendar secret address, school, waste collection · GitHub). Es macht genau das: einen Kalender, ein Widget „Nächste Ereignisse“, Auslöser und eine Aktion. Für die Listen schau dir Bring! (https://github.com/LM1LC3N7/gladys-bring) und 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) an. Sie decken bereits Einkäufe und Aufgaben ab und sind eine gute Inspirationsquelle für das Nutzererlebnis.

Einige Präzisierungen zu jedem Punkt:

  • Der Kalender funktioniert im „Push“-Modus: Deine Integration synchronisiert, Gladys speichert.
    • Die gesendeten Kalender füttern die Kalenderansicht und die Szenen, wie die nativen CalDAV-Kalender.
    • Es ist einseitig: Gladys schreibt nie in OpenFamily.
    • Jeder Benutzer aktiviert die Integration für sich selbst im Block „Meine Kalender“. Die Kalender sind standardmäßig privat.
    • Ein Kalender muss geteilt werden, damit ihn das gesamte Haushalt sieht und er Szenen auslösen kann.
    • Achte auf Dopplungen: Wenn du den Familienkalender an jedes Mitglied sendest und jeder ihn teilt, wird er mehrmals angezeigt. Es ist besser, ihn an ein einziges Konto zu senden.
  • Erinnerungen an Termine: Du brauchst keinen eigenen Auslöser.
    • Der native Auslöser „Ein Ereignis im Kalender steht bevor“ funktioniert direkt auf den gesendeten Kalendern. Man kann ihn etwas vor Beginn oder Ende eines Termins einstellen, mit einem Filter auf den Namen.
    • Ich würde einen eigenen Auslöser nur erstellen, wenn die OpenFamily-Erinnerungen eine Information enthalten, die Gladys nicht hat, z.B. eine manuell in OpenFamily eingestellte Erinnerung. So vermeidet man zwei Wege, um dasselbe zu tun.
  • Widgets: Sie sind deklarativ. Deine Integration gibt einen Inhalt mit einem festen Vokabular (Liste, Liste von Zuständen, Kacheln, Schaltflächen…) zurück und Gladys kümmert sich um die Anzeige (Theme, Dark Mode, Mobile). Ein Widget dient dazu, Daten anzuzeigen und sie zu berühren:
    • Hinzufügen eines Artikels oder einer Aufgabe über das Widget ist möglich: Eine Schaltfläche kann ein kleines Formular (max. 4 Felder) öffnen, das deine Integration deklariert.
    • Abhaken eines Artikels: Es gibt noch kein Kontrollkästchen pro Zeile. Du kannst mit einer „Abhaken“-Schaltfläche arbeiten, die eine Auswahlliste (Feld select) öffnet, die die aktuellen Artikel enthält, die zum Zeitpunkt der Anzeige generiert wird. Wenn es im Gebrauch zu einschränkend ist, öffne ein Thema: Die Formulare hinter den Schaltflächen sind gerade aus einem solchen Feedback entstanden.
    • Gladys holt den Inhalt und speichert ihn im Cache für die Dauer, die du festlegst (ttl_seconds). Wenn sich eine Liste auf der OpenFamily-Seite ändert, sende ein widget.refresh, um die Widgets zu aktualisieren.
  • Szenenaktionen: „Zur Einkaufsliste hinzufügen“ und „Aufgabe hinzufügen“ eignen sich perfekt dafür, und die Textfelder akzeptieren Szenenvariablen.
    • Denke auch an eine Aktion „Liste lesen“, die ein Ergebnis (outputs) zurückgibt. Eine Szene kann z.B. die Einkaufsliste per Nachricht senden, wenn du die Arbeit verlässt.
    • Wie Auslöser kommen „Artikel hinzugefügt“, „Aufgabe abgeschlossen“ oder „Aufgabe fällig“ natürlich.

2. Einschränkungen des Stores und des SDK für einen ersten Entwurf

  • Veröffentlichung:

    • ein öffentliches GitHub-Repository mit dem Topic gladys-assistant-i* Integration ;
    • Manifest gladys-assistant-integration.json im Stammverzeichnis ;
    • Pflichtdokumentation auf Französisch und Englisch (docs/fr.md und docs/en.md), mindestens 300 Zeichen pro Dokument, mit den Abschnitten Vorstellung / Voraussetzungen / Konfiguration / Problembehebung ;
    • Optional ein Cover-Bild, 800×534 und maximal 150 KB groß.

    Die Indexierung erfolgt automatisch, alle Stunden, ohne unsere Validierung. Wenn deine Integration nicht angezeigt wird, wird der Grund in rejected.json angegeben. Um vor der Indexierung zu testen, reicht es, über „Von GitHub installieren“ mit der URL des Repositories zu gehen.

  • Docker-Image : Es muss auf einem öffentlichen Register sein und für amd64 und arm64 gebaut werden, da viele Gladys auf Raspberry Pi laufen. Beginne mit dem Template GitHub - GladysAssistant/integration-template-js: Gladys Assistant Integration template for a JS external integration · GitHub : Es enthält bereits den Build-Workflow für beide Architekturen nach GHCR.

  • Container :

    • Benutzer ist nicht root, Dateisystem ist schreibgeschützt ;
    • /data ist der einzige erhaltene Ordner ;
    • CPU und Speicher sind begrenzt.

    Der ausgehende Netzwerkverkehr ist offen: Eine selbstgehostete OpenFamily-Instanz im lokalen Netzwerk ist über ihre URL erreichbar. Nur mDNS und eingehender Broadcast werden nicht weitergeleitet.

  • SDK : Das offizielle SDK ist in Node.js (@gladysassistant/integration-sdk). Wenn du eine andere Sprache bevorzugst, ist die REST/WebSocket-API dokumentiert. Du kannst auch außerhalb von Docker mit einem Dev-Token entwickeln.

  • Geheimnisse : Lege die URL und das OpenFamily-Token in das config_schema, mit dem Typ secret, der nie an den Browser zurückgesendet wird. Wenn jedes Mitglied eigene Anmeldedaten hat, verwende lieber das account_schema. Lege sie nie in den Einstellungen eines Widgets oder in den Feldern einer Szene ab: Die Validierung des Manifests lehnt dies ab.

  • Kalender, technisch :

    • Die external_id müssen mit ext:<selector>:<user>: beginnen ;
    • Du musst die Wiederholungen von wiederkehrenden Ereignissen berechnen (wir empfehlen 12 Monate im Voraus) ;
    • Um Ereignisse zu löschen, sendest du ein vollständiges Zeitfenster (window) zurück ;
    • Grenzen: 500 Ereignisse pro Anfrage, 30 Schreibvorgänge pro Minute, 50 Kalender pro Benutzer und 10.000 Ereignisse pro Kalender.
  • Widgets : Maximal 5 pro Integration und 8 Elemente pro Widget. Die Bilder müssen von deiner Integration bereitgestellt werden (PNG, JPEG oder WebP, maximal 300 KB), nie über eine externe URL, die vom Browser geladen wird.

  • gladys_version : Gib die Mindestversion von Gladys an, die das verwendet, was du nutzt. Eine ältere Version lehnt ein Manifest ab, dessen Felder sie nicht kennt.

Die gesamte Dokumentation findest du hier: Créer une intégration externe | Gladys Assistant (Abschnitte „Kalender: der Typ calendar“, „Dashboard-Widgets“ und „Auslöser und Aktionen von Szenen“).

Danke, Pierre-Gilles, das ist sehr klar und beantwortet alles!
Wir gehen also von einer Kalender-Integration mit Widgets, Aktionen und Auslösern aus, inspiriert von ICS Calendars, Bring! und Todoist.
Unser erster Schritt: ein API-Token in OpenFamily, damit die Integration ordnungsgemäß authentifiziert wird (config_schema vom Typ secret).
Dann das Repository vom Template aus, getestet auf einem lokalen Gladys über „Von GitHub installieren“.
Ich komme hier mit einem ersten Repository zurück, das man ausprobieren kann.

Falls es gut funktioniert, bin ich dabei, die Family-Wall-App zu ersetzen, die nicht Open Source ist

Hallo Pierre-Gilles,

Es ist erledigt: Die OpenFamily-Integration ist online, GitHub - NexaFlowFrance/gladys-openfamily: OpenFamily for Gladys Assistant: the family calendar, shopping list and tasks on the dashboard and in scenes. · GitHub. Sie folgt deinem Brief: Kalender-Typ, drei Widgets (heute, Einkäufe, Aufgaben) mit Formularen zum Hinzufügen und Abhaken, vier Szenenaktionen und drei Auslöser. Auf Seiten von OpenFamily haben wir für die Gelegenheit API-Token hinzugefügt.

Die Vorlage, das SDK und der Store-Validator sind sehr angenehm in der Nutzung, danke für die Arbeit. Getestet auf einer Gladys 5.3.3 in Docker.

Zwei Rückmeldungen nebenbei, falls sie nützlich sind:

  1. Wenn die Zeitzone nicht in den Einstellungen eingestellt ist, erhalten die Integrationscontainer TZ=UTC, während der Kern auf Europe/Paris zurückfällt. Die lokalen Zeiten sind dann verschoben. Ich habe eine Zeitzoneneinstellung auf meiner Seite hinzugefügt.
  2. Mit Gladys im Bridge-Modus unter Docker Desktop (Windows) konnte die Integration nicht gladys:80 erreichen, da das Netzwerk gladys-integrations ohne Kommunikation zwischen Containern erstellt wurde. Nicht unter Linux überprüft.

Alle Rückmeldungen sind willkommen, von dir und der Community.

Danke @QuentinCazier für diese neue Integration!

Ich habe die Gelegenheit genutzt, um den Titel zu ändern :slight_smile:
Und ich werde es bald testen :wink:

Wir freuen uns schon auf die neue Integration :wink:

Okay, ich hatte das GitHub-Repo nicht gesehen :sweat_smile:

Ein bisschen Geduld bitte :smiley:
Ich habe Gladys an die Spitze der Liste gesetzt, wir bevorzugen immer Anwendungen und andere Dinge, die dieselbe Philosophie wie wir teilen :slight_smile:

Edit:
Alles klar :wink: