# Cluster-F

> Projektdokumentation – ESP32-Umweltsensor mit BME280 über MQTT

This document contains the full content of all documentation pages for AI consumption.

---

## Funktionsweise

**URL:** https://docs.example.com/docs/ablauf
**Description:** Programmablauf zur Laufzeit und der Entwicklungs-Workflow

## Ablauf des Programms

Nach dem Start durchläuft der ESP32 die folgenden Schritte:

  

  

  

  

## Entwicklungs-Workflow

Der typische Ablauf beim Bearbeiten des Codes:

```text
Code in Thonny bearbeiten
        ↓
Datei auf ESP32 speichern (main.py)
        ↓
ESP32 startet das Skript automatisch
        ↓
Ausgabe / Fehler in der Thonny-Konsole prüfen
```

| Aspekt       | Wert                                                   |
|--------------|--------------------------------------------------------|
| IDE          | [Thonny](https://thonny.org/)                          |
| Sprache      | MicroPython                                            |
| Übertragung  | Dateien werden per Thonny direkt auf den ESP32 geschrieben |

---

## Fehlerbehebung

**URL:** https://docs.example.com/docs/fehlerbehebung
**Description:** Häufige Fehlermeldungen, ihre Ursachen und Lösungen

Treten Probleme auf, hilft meist ein Blick in die **Thonny-Konsole** weiter. Dort werden die Fehlermeldungen ausgegeben. Die folgenden Fehler kommen am häufigsten vor.

---

## Node-RED-Flows

**URL:** https://docs.example.com/docs/finn-nodered-flows
**Description:** Flows, die die Messwerte vom MQTT-Broker in die Datenbank schreiben

Die **Flows** in Node-RED holen die Messwerte vom MQTT-Broker und schreiben sie in die PostgreSQL-Datenbank. Der Server selbst (die VM) ist in [Tims Bereich](/docs/tim-nodered-server) beschrieben.

## Was der Flow macht

```text
MQTT-In (sensor/#)  ──▶  Payload parsen  ──▶  SQL-Insert  ──▶  PostgreSQL
```

## Noch zu dokumentieren

- Welche MQTT-Topics abonniert werden (`sensor/temperatur`, `…/luftfeuchte`, `…/luftdruck`)
- Wie die Nachricht aufbereitet wird (Payload → Felder)
- SQL-Insert in die Datenbank (Tabelle, Spalten)
- Fehlerbehandlung (z. B. Datenbank nicht erreichbar)
- Export des Flows (JSON) als Backup / Anhang

---

## Python-Auswertung

**URL:** https://docs.example.com/docs/finn-python-auswertung
**Description:** Python-Skript zur Auswertung und Visualisierung der Messdaten (noch offen)

Laut Aufgabe Pflicht: ein **Python-Auswertungsskript**, das die Messdaten aus der Datenbank liest und **visualisiert**. Diese Seite ist noch ein Platzhalter.

## Noch zu dokumentieren

- Verbindung zur PostgreSQL-Datenbank (Bibliothek, z. B. `psycopg2`)
- Welche Daten ausgewertet werden (Zeitraum, Messgrößen)
- Visualisierung (z. B. `matplotlib` – Diagramme über die Zeit)
- Wie das Skript gestartet wird
- Wer übernimmt das? (aktuell offen)

---

## Übersicht

**URL:** https://docs.example.com/docs
**Description:** Messdatenerfassung mit ESP32, virtualisiert auf einem Proxmox-Cluster – Projektübersicht und Aufgabenverteilung

Dieses Projekt erfasst Messdaten mit einem **ESP32**, speichert sie dauerhaft in einer **Datenbank** und wertet sie mit einem **Python-Skript** aus. Der komplette Stack läuft **virtualisiert** auf einem **Proxmox-Cluster** aus drei Hosts.

## Datenfluss

```text
 ESP32  ──MQTT──▶  MQTT-Broker  ──▶  Node-RED  ──▶  Datenbank  ──▶  Python-Auswertung
(Sensor)          (Mosquitto)       (Middleware)    (PostgreSQL)     (Visualisierung)
```

Alles läuft als VMs im Proxmox-Cluster und wird über eine OPNsense-Firewall abgesichert.

## Wer hat was gemacht

| Person      | Bereich                | Inhalt                                                        |
|-------------|------------------------|--------------------------------------------------------------|
| **Tim**     | Server & Infrastruktur | Datenbank-, MQTT- und Node-RED-Server (Debian-VMs) aufgesetzt |
| **Finn**    | Software & Code        | ESP32 programmiert, MQTT angebunden, Node-RED-Flows           |
| **Marcell** | Netzwerk & Sicherheit  | OPNsense-Firewall, Vernetzung & Absicherung der VMs           |

> Der **Proxmox-Cluster** wurde gemeinsam aufgesetzt: jeder hat seinen eigenen PVE-Host installiert und ins Cluster integriert (mit Live-Migration zwischen den Hosts).

## Anforderungen aus der Aufgabe

| Anforderung                                | Status   | Wer      |
|--------------------------------------------|----------|----------|
| Proxmox-Cluster (3 Hosts, Live-Migration)  | läuft    | Team     |
| Debian-VM: Datenbankserver                 | ok       | Tim      |
| Debian-VM: MQTT-Broker                     | ok       | Tim      |
| Debian-VM (GUI): Node-RED als Middleware   | ok       | Tim/Finn |
| Messdatenerfassung mit ESP32 → MQTT        | ok       | Finn     |
| Python-Auswertungsskript                   | offen    | —        |
| Netzwerkplanung & Sicherheit               | ok       | Marcell  |
| KI-Nutzung dokumentiert                    | siehe [KI-Nutzung](/docs/ki-nutzung) | Team |

## Bereiche

---

## Installation

**URL:** https://docs.example.com/docs/installation
**Description:** MicroPython-Libraries installieren und die Dateien auf den ESP32 bringen

Damit der Sensor funktioniert, müssen auf dem ESP32 zwei MicroPython-Libraries installiert sein und das Programm `main.py` aufgespielt werden.

## Voraussetzungen

- **Thonny** ist installiert ([thonny.org](https://thonny.org/))
- Der **ESP32** ist mit der **MicroPython-Firmware** geflasht
- Der ESP32 ist per USB-Kabel mit dem Computer verbunden

## Verwendete Libraries

| Library                    | Zweck                            |
|----------------------------|----------------------------------|
| `micropython-bme280`       | Auslesen der BME280-Sensorwerte  |
| `micropython-umqtt.simple` | MQTT-Client für die Veröffentlichung |

## Installation über Thonny

  

  

## Dateistruktur auf dem ESP32

Nach erfolgreicher Installation liegen folgende Dateien auf dem ESP32:

```text
/
├── main.py              # Hauptprogramm (Sensor lesen + MQTT senden)
└── lib/
    ├── bme280.py        # BME280-Library
    └── umqtt/
        └── simple.py    # MQTT-Client-Library
```

---

## KI-Nutzung

**URL:** https://docs.example.com/docs/ki-nutzung
**Description:** Dokumentation des KI-Einsatzes im Projekt (laut Aufgabe verpflichtend)

Laut Aufgabenstellung muss der Einsatz von KI dokumentiert werden. Hier wird festgehalten, wo im Projekt KI-Werkzeuge genutzt wurden.

## Wo KI genutzt wurde

| Bereich                 | KI-Einsatz                                             | Wer  |
|-------------------------|--------------------------------------------------------|------|
| Dokumentation (Website) | Aufbau & Struktur dieser Doku mit Claude (Claude Code) | Team |
| *…ergänzen*             | *z. B. Code-Hilfe, Konfiguration, Fehlersuche*         | *…*  |

## Noch zu ergänzen

- Welche KI-Tools wurden benutzt (z. B. ChatGPT, Claude)?
- Wofür genau (Code generieren, erklären, debuggen, Konfiguration)?
- Pro Person: wer hat wo KI eingesetzt?

---

## Konfiguration

**URL:** https://docs.example.com/docs/konfiguration
**Description:** MQTT-Broker-Adresse einstellen und die verwendeten Topics im Überblick

Die wichtigsten Einstellungen befinden sich in der Datei `main.py`.

## MQTT-Broker-IP anpassen

Der MQTT-Broker bezieht seine IP-Adresse per **DHCP** und kann sich daher ändern. Bei einer geänderten IP muss in `main.py` die Konstante `BROKER` angepasst werden:

```python
# main.py
BROKER = "192.168.1.***"   # <-- IP des MQTT-Brokers
```

## MQTT-Topics

Der ESP32 veröffentlicht die Messwerte unter folgenden Topics:

| Topic                | Inhalt           | Einheit |
|----------------------|------------------|---------|
| `sensor/temperatur`  | Temperatur       | °C      |
| `sensor/luftfeuchte` | Relative Feuchte | %       |
| `sensor/luftdruck`   | Luftdruck        | hPa     |

---

## Netzwerk & Sicherheit

**URL:** https://docs.example.com/docs/marcell-netzwerk
**Description:** Netzwerkplan und Absicherung der VMs im Proxmox-Cluster

Hier steht, wie die VMs vernetzt und abgesichert sind. Ziel: die Server bzw. VMs sind vor Angriffen von außen geschützt – das ist eine ausdrückliche Sicherheitsanforderung aus der Aufgabe.

## Noch zu dokumentieren

- Netzwerkplan / Topologie (Skizze: Hosts, VMs, OPNsense)
- IP-Bereiche / VLANs der einzelnen VMs
- Welche Dienste von wo erreichbar sind (ESP32 → MQTT, Node-RED → DB usw.)
- Sicherheitsmaßnahmen (Firewall-Regeln, kein direkter Zugriff von außen)
- Sicherheitstechnische Überlegungen (was wurde bedacht, was bewusst zugelassen)

---

## OPNsense

**URL:** https://docs.example.com/docs/marcell-opnsense
**Description:** OPNsense-Firewall zur Absicherung der VMs im Proxmox-Cluster

Eine **OPNsense** dient als Firewall und Router und sichert die VMs des Proxmox-Clusters gegen Angriffe von außen ab. Der Verkehr zwischen den VMs und nach außen läuft über die OPNsense.

## Eckdaten

| Punkt         | Wert                                  |
|---------------|---------------------------------------|
| VM            | OPNsense                              |
| Maschinenname | `opnsense`                            |
| Aufgabe       | Firewall, Routing, Segmentierung      |
| Zugang        | siehe [Passwörter](/docs/passwoerter) |

## Noch zu dokumentieren

- Installation der OPNsense (als VM auf Proxmox)
- Interfaces und Netze (WAN, LAN, ggf. VLANs für die VMs)
- Firewall-Regeln (was darf rein/raus, was intern erlaubt ist)
- Wie die VMs angebunden sind (siehe [Netzwerk & Sicherheit](/docs/marcell-netzwerk))

---

## Maschinen

**URL:** https://docs.example.com/docs/maschinen
**Description:** Übersicht aller Maschinen der Cluster-F Group und der darauf laufenden Dienste

Die Cluster-F Group besteht aus mehreren Maschinen. Jede Maschine ist für **einen Dienst** zuständig – und ist nach genau diesem Dienst benannt.

## Namenskonvention

| Dienst     | Maschinenname | Zweck                         |
|------------|---------------|-------------------------------|
| unmint     | `unmint`      | Generiert diese Dokumentation |
| Node-RED   | `nodered`     | Automatisierung & Flows       |
| PostgreSQL | `posql`       | Datenbank                     |
| OPNsense   | `opnsense`    | Firewall / Router             |
| MQTT       | `mqtt`        | MQTT-Broker (Mosquitto)       |

## Zugangsdaten

Die Passwörter folgen einer festen Regel (`Ichbin` + Name in Großbuchstaben) und sind zentral hinterlegt.

---

## Passwörter

**URL:** https://docs.example.com/docs/passwoerter
**Description:** Zentrale Ablage aller Zugangsdaten der Cluster-F-Maschinen – inklusive Namens- und Passwort-Regel

Hier liegen die Zugangsdaten **aller Maschinen** der Cluster-F Group an einem Ort. Damit man sich nichts merken muss, folgt alles einer festen Regel – sie steht ganz oben.

## Die Regel

Damit ergibt sich das Passwort jeder Maschine automatisch:

```text
Passwort = "Ichbin" + MASCHINENNAME (in CAPSLOCK)

unmint    →  IchbinUNMINT
nodered   →  IchbinNODERED
```

## Maschinen & Passwörter

| Maschine   | Läuft darauf / Dienst              | Passwort         |
|------------|------------------------------------|------------------|
| `unmint`   | unmint – diese Dokumentation       | `IchbinUNMINT`   |
| `nodered`  | Node-RED – Automatisierung & Flows | `IchbinNODERED`  |
| `posql`    | PostgreSQL – Datenbank             | `IchbinPOSQL`    |
| `opnsense` | OPNsense – Firewall / Router       | `IchbinOPNSENSE` |
| `mqtt`     | MQTT-Broker (Mosquitto)            | `IchbinMQTT`     |

## Dienst-Zugänge

Eigene Benutzer **innerhalb der Dienste** (nicht zu verwechseln mit dem Login der Maschinen):

| Dienst     | Benutzer | Wofür                                            | Passwort           |
|------------|----------|--------------------------------------------------|--------------------|
| PostgreSQL | `psql_F` | Zugriff auf die Datenbank `messungen` (Node-RED) | `IchbinPSQL`       |
| MQTT       | `mqtt_f` | Anmeldung am Mosquitto-Broker (ESP32 + Node-RED) | *(noch eintragen)* |

## Neue Maschine aufnehmen

---

## Datenbank-Server

**URL:** https://docs.example.com/docs/tim-datenbank
**Description:** Debian-VM mit PostgreSQL 18, in der die Messdaten gespeichert werden

Die Datenbank läuft auf einer eigenen Debian-VM (ohne GUI). Hier werden die Messwerte gespeichert, die Node-RED aus dem MQTT-Broker holt. Als Datenbank wird **PostgreSQL 18** genutzt.

## Eckdaten

| Punkt         | Wert                                  |
|---------------|---------------------------------------|
| VM            | Debian (ohne GUI)                     |
| Maschinenname | `posql`                               |
| Interne IP    | `192.168.1.10`                        |
| Datenbank     | PostgreSQL 18                         |
| DB-Name       | `messungen`                           |
| Tabelle       | `messungen`                           |
| DB-Benutzer   | `psql_F`                              |
| Zugang        | siehe [Passwörter](/docs/passwoerter) |

## Installation

PostgreSQL 18 ist als normale Standard-Installation auf der Debian-VM eingerichtet. Die VM hängt im internen Netz unter der festen IP `192.168.1.10`.

## Zugriff / Benutzer

Statt mit dem Standard-Superuser `postgres` zu arbeiten, wurde ein **eigener Benutzer `psql_F`** angelegt, der **nur auf die Datenbank `messungen`** zugreifen darf. So kommt Node-RED nur an genau diese eine Datenbank und nicht an den Rest des Systems.

```sql
-- eigener Benutzer nur für die Messdaten-DB (Passwort siehe Passwörter-Seite)
CREATE USER psql_F WITH PASSWORD '...';
GRANT CONNECT ON DATABASE messungen TO psql_F;
GRANT SELECT, INSERT ON messungen TO psql_F;
```

Das Passwort von `psql_F` steht bei den [Passwörtern](/docs/passwoerter).

## Datenbank & Tabelle

Es gibt die Datenbank **`messungen`** und darin die Tabelle **`messungen`**:

```sql
CREATE TABLE messungen (
    id           BIGSERIAL PRIMARY KEY,
    timestamp    TIMESTAMPTZ NOT NULL DEFAULT now(),
    temperatur   REAL,
    air_pressure REAL,
    humidity     REAL
);
```

### Spalten

| Spalte         | Typ              | Bedeutung                                  |
|----------------|------------------|--------------------------------------------|
| `id`           | `BIGSERIAL` (PK) | Fortlaufende ID, wird automatisch vergeben |
| `timestamp`    | `TIMESTAMPTZ`    | Zeitpunkt der Messung, Standard `now()`    |
| `temperatur`   | `REAL`           | Temperatur in °C                           |
| `air_pressure` | `REAL`           | Luftdruck in hPa                           |
| `humidity`     | `REAL`           | Luftfeuchte in %                           |

Jede Messung bekommt automatisch eine `id` und einen `timestamp`. Die drei Messwerte (`temperatur`, `air_pressure`, `humidity`) kommen vom BME280 über den ESP32 und werden von Node-RED in die Tabelle geschrieben.

Der Tabellenname `messungen` ist aus dem CREATE-Statement übernommen. Falls die Tabelle bei dir anders heißt, hier noch anpassen.

---

## MQTT-Broker-Server

**URL:** https://docs.example.com/docs/tim-mqtt-server
**Description:** Debian-VM mit Mosquitto als MQTT-Broker, mit eigener Benutzer-Authentifizierung

Der MQTT-Broker läuft auf einer eigenen Debian-VM (ohne GUI). Er nimmt die Messwerte vom ESP32 entgegen und stellt sie für Node-RED bereit. Als Broker wird **Mosquitto** genutzt.

## Eckdaten

| Punkt         | Wert                                  |
|---------------|---------------------------------------|
| VM            | Debian (ohne GUI)                     |
| Maschinenname | `mqtt`                                |
| Interne IP    | `192.168.1.…` *(noch eintragen)*      |
| Broker        | Mosquitto                             |
| Port          | `1883`                                |
| Auth          | Benutzer + Passwort (Passwort-Datei)  |
| MQTT-Benutzer | `mqtt_f`                              |
| Zugang        | siehe [Passwörter](/docs/passwoerter) |

## Installation

Mosquitto ist als normale Standard-Installation auf der Debian-VM eingerichtet.

## Authentifizierung (Besonderheit)

Standardmäßig würde Mosquitto jeden ohne Login annehmen. Damit nur unsere Geräte zugreifen, ist in der Config eine **Passwort-Datei** eingetragen und der anonyme Zugriff abgeschaltet. Darüber wurde ein eigener Benutzer **`mqtt_f`** für unsere Gruppe angelegt. Mit dem meldet sich der ESP32 (publish) und Node-RED (subscribe) am Broker an.

In der Mosquitto-Config:

```text
# /etc/mosquitto/mosquitto.conf (bzw. eine Datei in conf.d)
allow_anonymous false
password_file /etc/mosquitto/passwd
```

Benutzer anlegen (das `-c` legt die Passwort-Datei neu an):

```bash
sudo mosquitto_passwd -c /etc/mosquitto/passwd mqtt_f
```

Das Passwort von `mqtt_f` steht bei den [Passwörtern](/docs/passwoerter).

## Topics

Die genutzten Topics (vom ESP32 befüllt) stehen in Finns [Konfiguration](/docs/konfiguration): `sensor/temperatur`, `sensor/luftfeuchte`, `sensor/luftdruck`.

---

## Node-RED-Server

**URL:** https://docs.example.com/docs/tim-nodered-server
**Description:** Debian-VM mit GUI, auf der Node-RED über das offizielle Install-Skript läuft

Debian-VM (**mit GUI**), auf der **Node-RED** läuft. Node-RED ist die Middleware, die die Daten vom MQTT-Broker in die Datenbank schreibt. Die Flows selbst sind in [Finns Bereich](/docs/finn-nodered-flows) beschrieben.

## Eckdaten

| Punkt          | Wert                                  |
|----------------|---------------------------------------|
| VM             | Debian (mit GUI)                      |
| Maschinenname  | `nodered`                             |
| Interne IP     | `192.168.1.…` *(noch eintragen)*      |
| Dienst         | Node-RED                              |
| Web-Oberfläche | Port `1880`                           |
| Netzwerk       | hinter der OPNsense, per NAT auf Port `1880` |
| Zugang         | siehe [Passwörter](/docs/passwoerter) |

## Installation

Node-RED ist mit dem **offiziellen Install-Skript** eingerichtet, ohne Sonderkonfiguration. Das Skript installiert Node.js und Node-RED und richtet Node-RED als Dienst ein:

```bash
bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)
```

Danach als Dienst aktivieren (Autostart):

```bash
sudo systemctl enable --now nodered.service
```

Die Weboberfläche läuft auf dem Standard-Port `1880`. Der Server steht **hinter der OPNsense** und ist von außen per **NAT (Port-Weiterleitung)** auf dem Standard-Port erreichbar. Die Firewall- und Weiterleitungs-Details stehen in [Marcells Netzwerk-Teil](/docs/marcell-netzwerk).

## Was läuft darauf

Auf dem Server läuft nur Node-RED. Die eigentlichen Flows (MQTT abonnieren, Werte in die Datenbank schreiben) sind in [Finns Node-RED-Flows](/docs/finn-nodered-flows) dokumentiert.

---

## Links

- [GitHub](https://github.com/gsmgh/cluter-f-unmint)
- [Discord](https://discord.gg/your-invite)