# Prüfstand-Simulator (Datenempfang testen)

## Was ist das?

Der Prüfstand-Simulator ist ein eigenständiges Testwerkzeug, das einen echten
Prüfstand nachbildet: Er erzeugt fortlaufend Messwerte und schickt sie über
genau die Wege an TestLabIQ, die auch echte Hardware benutzt — **REST-Push**
(`POST /api/v1/measurements`) oder **MQTT** (JSON auf ein Broker-Topic). So
lässt sich der Datenempfang der App prüfen, ohne einen physischen Prüfstand
anzuschließen: Kommen Werte an? Erscheinen sie live auf der Testfall-Seite?
Steht das Zustell-Log richtig?

Er liegt im Monorepo unter `apps/simulator` und hat ein eigenes kleines
Dashboard im Browser, auf dem sich alle Einstellungen des simulierten
Prüfstands vornehmen lassen — allen voran das **Protokoll**, mit dem gesendet
wird.

> Der Simulator ist ein Entwicklungs- und Testwerkzeug. Er ist bewusst **nicht**
> Teil der Produkt-App und braucht keine Anmeldung; er authentifiziert sich —
> wie echte Hardware — allein über den Prüfstand-API-Key.

## So benutzt man es

1. **App starten**, an die gesendet werden soll (z. B. `pnpm --filter @lab-mgmt/web dev`
   auf Port 4000). Für MQTT zusätzlich einen Broker bereitstellen und die App mit
   `MQTT_BROKER_URL` starten (siehe [MQTT-Anbindung](https://www.testlabiq.com/hilfe/mqtt-anbindung)). Für den
   REST-Weg wird **kein** Broker gebraucht.

   > **Broker per Docker (optional):** Das Repo bringt einen Mosquitto-Broker als
   > opt-in-Profil mit. Zum Testen mit MQTT die App zusammen mit dem Broker
   > starten und ihr die Broker-Adresse mitgeben:
   >
   > ```bash
   > MQTT_BROKER_URL=mqtt://mqtt:1883 docker compose --profile prod --profile mqtt up -d
   > ```
   >
   > Lokal ohne Docker läuft ein Broker genauso: `mqtt://localhost:1883`.
2. **Simulator starten:**

   ```bash
   pnpm --filter @lab-mgmt/simulator dev
   ```

   Danach das Dashboard öffnen: <http://localhost:4100> (Port über `SIM_PORT`
   änderbar).
3. **Prüfstand-API-Key holen:** In der App auf der Detailseite des Prüfstands.
   Der Key identifiziert Prüfstand **und** Organisation.
4. **sequenceItemId holen:** Die UUID des laufenden Sequenz-Items steht auf der
   Testdurchführungs-Seite des jeweiligen Testfalls.
5. **Im Dashboard einstellen:**
   - **Protokoll:** *REST-Push* oder *MQTT*.
     - REST: **App-URL** (z. B. `http://localhost:4000`).
     - MQTT: **Broker-URL**, **Topic** (Standard `testlabiq/ingest`), optional
       Benutzer/Passwort.
   - **Prüfstand-API-Key** und **sequenceItemId** eintragen.
   - **Sendeintervall** (ms) und **Messpunkte je Kanal/Sendevorgang** wählen.
     Mehr als ein Punkt verteilt die Zeitstempel über das Intervall — es entsteht
     eine Kurve statt eines Einzelwerts.
   - **Messkanäle** definieren: Name (muss zum Testfall passen, z. B. `U_in`),
     Einheit, Signalform, Wertebereich (Min/Max), Periodendauer und Rauschen.
6. **Senden:**
   - **Einmal senden** schickt einen einzelnen Batch — gut zum schnellen
     Ausprobieren.
   - **Start** beginnt den Dauerlauf im eingestellten Intervall, **Stop**
     beendet ihn.
7. **Kontrollieren:** Rechts zeigt das Dashboard Sendevorgänge, gesendete
   Messpunkte, per REST übernommene Werte, Duplikate und Fehler sowie ein
   Protokoll der letzten Sendungen. In der App erscheinen die Werte live auf der
   Testfall-Seite und im **Zustell-Log** (`GET /api/v1/ingestion/deliveries`).

## Signalformen

| Signal | Verlauf |
|---|---|
| `sine` | Sinus zwischen Min und Max über die Periodendauer |
| `sawtooth` | linearer Anstieg Min → Max, dann Sprung zurück |
| `ramp` | Dreieck Min → Max → Min (z. B. langsam aufheizender Dauerlauf) |
| `square` | Rechteck, halbe Periode Max, halbe Periode Min |
| `random` | gleichverteilter Zufallswert im Band |
| `constant` | Mittelwert aus Min und Max |

Auf jeden Wert wird optional gleichverteiltes **Rauschen** (± Amplitude)
addiert; das Ergebnis bleibt im Band [Min, Max].

## Standardwerte aus der Umgebung

Damit Simulator und App ohne weiteres Zutun zusammenpassen, übernimmt der
Simulator beim Start — falls gesetzt — dieselben Umgebungsvariablen wie die App:
`NEXT_PUBLIC_APP_URL` (REST-Ziel), `MQTT_BROKER_URL`, `MQTT_TOPIC`,
`MQTT_USERNAME`, `MQTT_PASSWORD`. Zusätzlich: `SIM_PORT` (Dashboard-Port,
Standard 4100), `SIM_API_KEY` und `SIM_SEQUENCE_ITEM_ID` als Vorbelegung.

## Typische Probleme

- **REST meldet 401 „Ungültiger API-Key".** Der eingetragene Prüfstand-API-Key
  stimmt nicht (oder wurde rotiert). Neuen Key auf der Prüfstand-Seite holen.
- **REST meldet 404 „Sequenz-Item nicht gefunden…".** Die `sequenceItemId`
  gehört nicht zur Organisation dieses Prüfstands oder existiert nicht.
- **REST-Verbindung fehlgeschlagen.** Läuft die App unter der eingetragenen
  App-URL? Port und Schema (`http://`) prüfen.
- **MQTT: „verbunden = nein" oder Publish-Fehler.** Broker-URL, Port und ggf.
  Zugangsdaten prüfen. MQTT hat **keinen** Antwortkanal — ob die Werte
  angekommen sind, zeigt allein das **Zustell-Log** der App, nicht der
  Simulator (er bestätigt nur das Publizieren).
- **Werte kommen an, erscheinen aber nicht live.** Kanalname und
  `sequenceItemId` müssen zum gerade laufenden Testfall passen.

---

Quelle: https://www.testlabiq.com/hilfe/pruefstand-simulator