feuerwehr-getraenkeautomat-status/docs/CONFIG.md

Configuration Reference

Die Anwendung wird ueber data/config.json konfiguriert.

Gesamtstruktur

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

Bereich app

Beispiel:

{
  "name": "Getraenkeautomat Monitor",
  "timezone": "Europe/Berlin",
  "dashboard_refresh_seconds": 15,
  "default_from_email": "monitor@example.local"
}

Felder:

• name
  • Anzeigename der Anwendung im Dashboard
• timezone
  • Standardzeitzone fuer die Anwendung
• dashboard_refresh_seconds
  • Polling-Intervall fuer das Dashboard
• default_from_email
  • Absenderadresse fuer mail()

Bereich api

Beispiel:

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

Felder:

• bearer_token
  • statisches Token fuer 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 fuer den POST-Webhook
• enabled
  • aktiviert oder deaktiviert den Versand
• headers
  • optionales JSON-Objekt fuer zusaetzliche 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 fuer 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 Faecher dieses Automaten

Bereich machines[].slots

Jedes Fach repraesentiert 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 fuer 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

Fuer eine brauchbare Bestandschaetzung 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 Fuellstaenden machen.
4. Die durchschnittliche Differenz pro Flasche als distance_per_unit eintragen.
5. Einen passenden Schwellwert fuer alert_below_units festlegen.

Referenzen zwischen Bereichen

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

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

Das macht die Konfiguration wartbarer, weil ein Alarmziel zentral geaendert werden kann.

Tipps fuer produktive Nutzung

• IDs nur aus stabilen ASCII-Zeichen vergeben
• machine_id und sensor_id niemals nachtraeglich leichtfertig aendern
• fuer jeden neuen Sensor zuerst Kalibrierwerte eintragen
• Testalarme mit einem absichtlich kritischen Messwert pruefen
• Beispiel-Tokens und Default-Zugangsdaten vor dem Live-Betrieb ersetzen