Werte auswerten (Grafana, VIS, Skripte)

Wie werte ich Werte über mehrere Jahre aus, ohne jedes Jahr alles anzupassen?

Kurz: Nimm in VIS, Grafana und Skripten die States unter sourceanalytix.0.<Gerät>.currentYear. Ihre IDs ändern sich nie, auch nicht zum Jahreswechsel: SourceAnalytix setzt sie beim Periodenwechsel selbst zurück. Für Vergleiche über mehrere Jahre zeichnest du die Vorperioden-States mit einem History-Adapter auf oder liest das Jahresarchiv unter sourceanalytix.0.<Gerät>.<Jahr>.

Welcher Ordner wofür

Ordner	Inhalt	Ändert sich zum Jahreswechsel?
currentYear.<Kategorie>.01_currentDay bis 05_currentYear	laufender Tag, Woche, Monat, Quartal, Jahr	nein, nur der Wert beginnt neu
currentYear.<Kategorie>.01_previousDay bis 05_previousYear	abgeschlossene Vorperiode, z. B. gestern oder Vorjahr	nein
currentYear.<Kategorie>.weeks, months, quarters	jede Woche, jeder Monat, jedes Quartal des laufenden Jahres	nein, alle Werte werden am 1. Januar auf 0 gesetzt
<Jahr>.<Kategorie>.weeks, months, quarters	Archiv eines Kalenderjahres	ja, jedes Jahr kommt ein neuer Ordner dazu

<Kategorie> ist consumed oder delivered für den Verbrauch, costs oder earnings für die Kosten und meterReadings für Zählerstände. Was die Vorperioden-States genau enthalten, steht unter Wo finde ich gestern, letzte Woche, letzten Monat?.

So wertest du über mehrere Jahre aus

1. Öffne unter „Instanzen“ die Einstellungen der SourceAnalytix-Instanz und dort den Tab „Haupteinstellungen“.
2. Prüfe unter „Laufendes Jahr“, ob „Vorheriger Zeitraum“ an ist, und für einzelne Wochen, Monate oder Quartale des laufenden Jahres „Wochen“, „Monate“ oder „Quartale“. Bei einer neuen Instanz sind sie alle an.
3. Soll jedes Jahr als eigener Ordner erhalten bleiben, schalte unter „Jahresstatistik“ „Wochen“, „Monate“ oder „Quartale“ ein. Von Haus aus ist nur „Monate“ an.
4. Speichere. Die Instanz startet neu und legt die States an.
5. Zeichne für Langzeit-Diagramme zum Beispiel 03_previousMonth und 05_previousYear mit einem History-Adapter auf. Jeder Wert wird einmal pro Periode geschrieben, mit dem Zeitstempel 23:59:59 Uhr am letzten Tag der Periode. So entsteht über die Jahre eine lückenlose Reihe, ohne dass du etwas anpasst.

WARNING

Schaltest du eine dieser Optionen aus, löscht SourceAnalytix die passenden States im Ordner currentYear und im Ordner des laufenden Jahres. Ordner früherer Jahre bleiben erhalten.

Vergangene Jahre erreichst du im Archiv über die Jahreszahl im Pfad, etwa sourceanalytix.0.<Gerät>.2025.consumed.months.03_March. Die Jahressumme steht in <Jahr>.consumedCumulative (bei Kosten costsCumulative), der Zählerstand in <Jahr>.readingCumulative. Wie du das Jahr im Skript dynamisch einsetzt, steht unter Wie lese ich SourceAnalytix-Werte im Skript?.

Ab v0.6.2: Das Wochenarchiv liegt im Ordner des Jahres, zu dem die Kalenderwoche gehört. Woche 53 von 2026 steht also auch dann unter 2026, wenn ihre letzten Tage im Januar 2027 liegen (#1256). Mehr dazu unter Warum zeigt Woche 52/53 Werte im neuen Jahr?.

Siehe auch: Welche Datenpunkte nehme ich für Grafana/InfluxDB? · Welche Instanz-Einstellungen gibt es? · Was passiert zum Jahreswechsel?

Welche Datenpunkte nehme ich für Grafana/InfluxDB?

Kurz: Für Tages-, Wochen- und Monatsbalken zeichnest du die Vorperioden-States auf, also 01_previousDay, 02_previousWeek und 03_previousMonth unter sourceanalytix.0.<Gerät>.currentYear.<Kategorie>. Sie bekommen genau einen Wert pro Periode. Für eigene Auswertungen in Grafana reicht der Gesamtstand cumulativeReading. Alle diese States sind Zahlen, speichere sie in InfluxDB auch als Zahl.

Welcher State für welches Diagramm

Du willst …	State unter currentYear.<Kategorie>	Was in der Datenbank landet
Tagesbalken	01_previousDay	ein Wert pro Tag mit Zeitstempel 23:59:59 Uhr dieses Tages
Wochen vergleichen	02_previousWeek	ein Wert pro Woche, Zeitstempel Sonntag 23:59:59 Uhr
Monate vergleichen	03_previousMonth	ein Wert pro Monat, Zeitstempel letzter Tag 23:59:59 Uhr
Verlauf des laufenden Tages	01_currentDay	ein Wert bei jeder Änderung, ab 0:00 Uhr wieder ab 0
alles selbst rechnen	cumulativeReading (direkt unter der Technischen ID)	der Gesamtstand, er fällt bei eingeschalteter Reset-Erkennung nie von selbst

Die Vorperioden-States schreibt SourceAnalytix bei jedem Periodenwechsel neu, auch wenn der Wert gleich bleibt. Ein Tag mit 0 kWh erscheint also als eigener Balken. Die laufenden Werte wie 01_currentDay schreibt es dagegen nur, wenn sich der Wert ändert. Sie eignen sich für eine Live-Anzeige, aber nicht als Tagesbalken.

Für Kosten nimmst du dieselben States im Ordner costs (bei Einspeisung earnings). Damit die Vorperioden-States existieren, muss in den Instanz-Einstellungen unter „Haupteinstellungen“, „Laufendes Jahr“ die Option „Vorheriger Zeitraum“ an sein.

So richtest du es ein

1. Öffne im Admin den Reiter „Objekte“ und dort sourceanalytix.0.<Gerät>.currentYear.consumed. Die Technische ID steht ab v0.7.0 in der Detailansicht der Quelle unter „Für Experten“.
2. Aktiviere bei 01_previousDay (und bei Bedarf 02_previousWeek, 03_previousMonth) die Aufzeichnung deines History-Adapters, zum Beispiel InfluxDB.
3. Wähle als Datentyp „Zahl“, falls dein History-Adapter danach fragt.
4. Zeichne in Grafana die Werte als Balken ohne weitere Summierung. Jeder Punkt ist schon der Verbrauch der ganzen Periode.

Der erste Wert erscheint erst nach dem ersten Periodenwechsel, für 01_previousDay also nach der nächsten Mitternacht.

TIP

Willst du die aktuelle Woche oder den aktuellen Monat neben die Vorperiode stellen, nimm 02_currentWeek und 02_previousWeek bzw. 03_currentMonth und 03_previousMonth als letzten Wert in einem Panel. Die Pfade sind fest, du musst das Dashboard nie anpassen.

Gruppierung, Zeitraum und Farben stellst du in Grafana ein. Das ist keine Funktion von SourceAnalytix.

Siehe auch: Über mehrere Jahre auswerten · Wo finde ich gestern, letzte Woche, letzten Monat? · Was steht in cumulativeReading?

Wie visualisiere ich die Werte in VIS, Flot, HabPanel und der Historie?

Kurz: SourceAnalytix liefert nur States, keine Diagramme. Für Verläufe und Balken zeichnest du die gewünschten States mit einem History-Adapter auf (History, SQL oder InfluxDB) und zeigst sie in Flot, eCharts, Grafana oder einem VIS-Widget an. Für Tabellen und Kacheln ohne Datenbank nimmst du den State statisticsJson, der alle Werte des laufenden Jahres in einem JSON enthält.

Diagramme mit der Historie

1. Wähle die States, die du darstellen willst. Für Tagesbalken ist das sourceanalytix.0.<Gerät>.currentYear.consumed.01_previousDay, für Monatsbalken 03_previousMonth. Welcher State wofür passt, steht unter Welche Datenpunkte nehme ich für Grafana/InfluxDB?.
2. Aktiviere im Reiter „Objekte“ bei diesen States die Aufzeichnung deines History-Adapters.
3. Lege in Flot oder eCharts ein Diagramm mit diesen States an, als Balken.
4. Binde das Diagramm in VIS oder HabPanel ein, zum Beispiel als Flot- oder eCharts-Widget.

Tageswerte mit Datum speichern und exportieren

Die Vorperioden-States tragen als Zeitstempel 23:59:59 Uhr am letzten Tag der Periode, zu der sie gehören, nicht die Uhrzeit des Wechsels. Der History-Adapter legt den Wert von gestern deshalb bei gestern ab. Damit hast du eine Liste der Tageswerte mit Datum. Exportieren kannst du sie mit den Mitteln deines History-Adapters.

Holt SourceAnalytix einen verpassten Wechsel später nach, etwa nach einem Neustart, bekommt der Wert trotzdem den Zeitstempel 23:59:59 Uhr am Tag vor dem Nachholen.

Tabellen und Kacheln ohne Datenbank

Der State sourceanalytix.0.<Gerät>.statisticsJson enthält in einem JSON die laufenden Werte, die Vorperioden und die Wochentage, Wochen, Monate und Quartale des laufenden Jahres. Ein VIS-Widget für JSON-Tabellen oder ein kleines Skript kann daraus eine Tabelle bauen, ohne dass du jeden State einzeln bindest. Der Aufbau ist unter Gibt es ein JSON mit allen Werten? beschrieben.

Einzelne Werte bindest du direkt an die States unter currentYear, zum Beispiel 01_currentDay für „Heute“ und 01_previousDay für „Gestern“. Ist in den Instanz-Einstellungen „Wochentag“ an, stehen die Tage der laufenden Woche unter currentYear.<Kategorie>.currentWeek, von 01_Monday bis 06_Saturday und 07_Sunday.

Siehe auch: Über mehrere Jahre auswerten · Wo finde ich gestern, letzte Woche, letzten Monat? · Welche States gibt es für Wochen, Monate und Wochentage?

Wie lese ich SourceAnalytix-Werte im Skript?

Kurz: Jeder Wert ist ein normaler State unter sourceanalytix.0.<Gerät>, den du im Skript mit getState liest. Die Technische ID ist der Ordnername der Quelle. Du findest sie ab v0.7.0 in der Detailansicht der Quelle unter „Für Experten“. Werte vergangener Jahre liest du aus dem Jahresarchiv, indem du die Jahreszahl in die ID einsetzt.

Die State-ID finden

Die ID setzt sich so zusammen: sourceanalytix.0.<Gerät>.<Ordner>.<State>, zum Beispiel sourceanalytix.0.strom.currentYear.consumed.03_currentMonth. Der Name oder Alias, den du der Quelle gibst, kommt in der ID nicht vor, nur die Technische ID.

• Quellen aus v0.7.0: Der Assistent „Quelle hinzufügen“ bildet die Technische ID aus dem Namen, den du im Schritt „Name“ eingibst. Unter „Für Experten“ kannst du sie dort selbst wählen.
• Ältere Quellen: Die Technische ID ist die ID des Quell-Datenpunkts mit __ statt Punkten, etwa modbus__0__inputRegisters__energy für modbus.0.inputRegisters.energy, sofern du keine eigene Output-ID gesetzt hast.

Alle Technischen IDs einer Instanz samt Quell-Datenpunkt liefert der Befehl getUsedOutputIds. Die Antwort ist ein Objekt mit der Technischen ID als Schlüssel und der ID des Quell-Datenpunkts als Wert. Bei einem Ordner ohne Quelle steht dort null.

sendTo('sourceanalytix.0', 'getUsedOutputIds', {}, result => {
    log(JSON.stringify(result));
});

Diesen Monat und denselben Monat im Vorjahr lesen

Die Monate des laufenden Jahres stehen unter currentYear, die Monate abgeschlossener Jahre nur im Ordner des jeweiligen Jahres. Einen festen Ordner „Vorjahr“ gibt es nicht. Die Monatsnamen sind englisch und nummeriert, von 01_January bis 12_December.

const root = 'sourceanalytix.0.strom';
const months = ['01_January', '02_February', '03_March', '04_April', '05_May', '06_June',
    '07_July', '08_August', '09_September', '10_October', '11_November', '12_December'];
const now = new Date();
const month = months[now.getMonth()];

const thisMonth = getState(`${root}.currentYear.consumed.03_currentMonth`).val;
const lastYearId = `${root}.${now.getFullYear() - 1}.consumed.months.${month}`;
const lastYear = existsState(lastYearId) ? getState(lastYearId).val : null;

log(`Dieser Monat: ${thisMonth}, im Vorjahr: ${lastYear}`);

IMPORTANT

Den Ordner des Vorjahres gibt es nur, wenn im Vorjahr in den Instanz-Einstellungen unter „Jahresstatistik“ die Option „Monate“ an war. Sie ist bei einer neuen Instanz eingeschaltet. Für Wochen und Quartale gibt es die Optionen „Wochen“ und „Quartale“, sie sind von Haus aus aus.

Für den letzten Monat oder das letzte Jahr brauchst du kein Datum: Sie stehen in currentYear.consumed.03_previousMonth und currentYear.consumed.05_previousYear.

Einstellungen einer Quelle lesen

Die Einstellungen stehen im Objekt des Quell-Datenpunkts unter common.custom, mit dem Instanznamen als Schlüssel. Weil der Name einen Punkt enthält, brauchst du die Klammerschreibweise: getObject('<Quell-ID>').common.custom['sourceanalytix.0'].

NOTE

Alle States von SourceAnalytix sind nur lesbar. Schreibe nicht aus einem Skript hinein: SourceAnalytix überschreibt sie mit dem nächsten Wert der Quelle oder beim nächsten Periodenwechsel. Für Korrekturen gibt es die Aktionen in den Instanz-Einstellungen, siehe Falsche Werte korrigieren.

Siehe auch: Über mehrere Jahre auswerten · Was ist die Output-ID? · Befehle per sendTo