feuerwehr-getraenkeautomat-status/docs/CONFIG.md

Configuration Reference

Die Anwendung wird über data/config.json konfiguriert.

Gesamtstruktur

{
  "app": {},
  "api": {},
  "admin": {},
  "alerts": {
    "webhooks": [],
    "emails": []
  },
  "machines": []
}

Bereich app

Beispiel:

{
  "name": "Getränkeautomat Monitor",
  "timezone": "Europe/Berlin",
  "dashboard_refresh_seconds": 15,
  "default_from_email": "monitor@example.local",
  "base_path": ""
}

Felder:

• name
  • Anzeigename der Anwendung im Dashboard
• timezone
  • Standardzeitzone für die Anwendung
• dashboard_refresh_seconds
  • Polling-Intervall für das Dashboard
• default_from_email
  • Absenderadresse für mail()
• base_path
  • optionaler URL-Pfad für Deployments unterhalb der Domain
  • leer lassen für Betrieb direkt unter /
  • Beispiel für domain.de/auswertung/: "/auswertung"
  • führende und abschließende Slashes werden beim Speichern normalisiert

Beispiel für einen Betrieb unter https://domain.de/auswertung/:

{
  "name": "Getränkeautomat Monitor",
  "timezone": "Europe/Berlin",
  "dashboard_refresh_seconds": 15,
  "default_from_email": "monitor@example.local",
  "base_path": "/auswertung"
}

Bereich api

Beispiel:

{
  "bearer_token": "demo-esp32-token"
}

Felder:

• bearer_token
  • statisches Token für die Sensor-API
  • wird von Clients im Authorization-Header gesendet

Bereich admin

Beispiel:

{
  "username": "admin",
  "password_hash": "$2y$10$..."
}

Felder:

• username
  • Admin-Benutzername
• password_hash
  • bcrypt-Hash des Passworts
  • wird vom Adminpanel automatisch erzeugt, wenn ein neues Passwort gespeichert wird

Bereich alerts.webhooks

Beispiel:

[
  {
    "id": "lager-webhook",
    "name": "Lager Webhook",
    "url": "https://example.com/hooks/lager",
    "enabled": true,
    "headers": {
      "X-App-Token": "replace-me"
    }
  }
]

Felder:

• id
  • technische Kennung
  • wird von Slots referenziert
• name
  • Anzeigename im Adminpanel
• url
  • Zieladresse für den POST-Webhook
• enabled
  • aktiviert oder deaktiviert den Versand
• headers
  • optionales JSON-Objekt für zusätzliche HTTP-Header

Bereich alerts.emails

Beispiel:

[
  {
    "id": "lager-team",
    "name": "Lager Team",
    "address": "lager@example.com",
    "enabled": true
  }
]

Felder:

• id
  • technische Kennung
  • wird von Slots referenziert
• name
  • Anzeigename im Adminpanel
• address
  • Zieladresse für Alarmmails
• enabled
  • aktiviert oder deaktiviert den Versand

Bereich machines

Hier werden alle Automaten definiert.

Beispiel:

[
  {
    "id": "automat-lobby",
    "name": "Lobby Automat",
    "location": "Erdgeschoss",
    "slots": []
  }
]

Felder:

• id
  • eindeutige Kennung des Automaten
• name
  • Anzeigename im Dashboard
• location
  • optionaler Standorttext
• slots
  • Liste der Fächer dieses Automaten

Bereich machines[].slots

Jedes Fach repräsentiert einen Sensor und eine zugeordnete Produktposition.

Beispiel:

{
  "sensor_id": "fach-a1",
  "label": "A1",
  "product_name": "Cola 0,5l",
  "full_distance_mm": 80,
  "empty_distance_mm": 360,
  "distance_per_unit": 40,
  "alert_below_units": 2
}

Felder:

• sensor_id
  • eindeutige Kennung des Sensors innerhalb des Automaten
• label
  • Kurzlabel für Anzeige und Alarmtexte
• product_name
  • Klartextbezeichnung des Produkts
• full_distance_mm
  • Sensorwert, der als "voll" gilt
• empty_distance_mm
  • Sensorwert, der als "leer" gilt
• distance_per_unit
  • Differenz im Messwert pro Flasche oder Einheit
• alert_below_units
  • kritische Schwelle

Hinweis: Webhook- und Email-Alarme werden global über die alerts.webhooks und alerts.emails Konfiguration gesteuert. Alle aktivierten Webhooks und Emails erhalten Alarmbenachrichtigungen.

Kalibrierung eines Fachs

Für eine brauchbare Bestandsschätzung sollten pro Fach mindestens diese Werte sauber kalibriert werden:

1. Sensorwert bei vollem Fach messen und als full_distance_mm eintragen.
2. Sensorwert bei leerem Fach messen und als empty_distance_mm eintragen.
3. Mehrere Messungen zwischen zwei benachbarten Füllständen machen.
4. Die durchschnittliche Differenz pro Flasche als distance_per_unit eintragen.
5. Einen passenden Schwellwert für alert_below_units festlegen.

Webhook-Typen

Die Konfiguration unterstützt verschiedene Webhook-Typen:

Generic

Standard-Webhook, der ein JSON-Payload mit allen relevanten Informationen sendet.

{
  "label": "lager-webhook",
  "name": "Lager Webhook",
  "type": "generic",
  "url": "https://example.com/hooks/lager",
  "enabled": true,
  "headers": {
    "X-App-Token": "your-token"
  }
}

Telegram

Spezieller Webhook für Telegram-Benachrichtigungen. Sendet formatierte Nachrichten mit Markdown.

{
  "label": "telegram-alerts",
  "name": "Telegram Alerts",
  "type": "telegram",
  "url": "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/sendMessage",
  "enabled": true,
  "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
  "chat_id": "-100123456789"
}

Referenzen zwischen Bereichen

Alarmziele werden global über alerts.webhooks und alerts.emails konfiguriert. Alle aktivierten Webhooks und Emails erhalten Benachrichtigungen bei Alarmen.

Das macht die Konfiguration wartbarer, weil Alarmziele zentral geändert werden können.

Tipps für produktive Nutzung

• Labels nur aus stabilen ASCII-Zeichen vergeben
• machine_id und sensor_id niemals nachträglich leichtfertig ändern
• für jeden neuen Sensor zuerst Kalibrierwerte eintragen
• Testalarme mit einem absichtlich kritischen Messwert prüfen
• Beispiel-Tokens und Default-Zugangsdaten vor dem Live-Betrieb ersetzen