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,
  "webhook_ids": ["lager-webhook"],
  "email_ids": ["lager-team"]
}

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
• webhook_ids
  • Liste von Webhook-IDs aus alerts.webhooks
• email_ids
  • Liste von Email-IDs aus alerts.emails

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.

Referenzen zwischen Bereichen

Slots referenzieren Alarmziele nicht direkt über URLs oder Email-Adressen, sondern über IDs:

• webhook_ids referenziert alerts.webhooks[].id
• email_ids referenziert alerts.emails[].id

Das macht die Konfiguration wartbarer, weil ein Alarmziel zentral geändert werden kann.

Tipps für produktive Nutzung

• IDs 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