Station Simulator (Testing Data Reception)

What is it?

The station simulator is a standalone testing tool that mimics a real test station: it continuously generates measurements and sends them to TestLabIQ via exactly the same paths real hardware uses — REST push (POST /api/v1/measurements) or MQTT (JSON on a broker topic). This lets you test the app's data reception without connecting a physical station: Do values arrive? Do they show up live on the test case page? Is the delivery log correct?

It lives in the monorepo under apps/simulator and has its own small dashboard in the browser where you configure everything about the simulated station — most importantly the protocol used to send.

The simulator is a development and testing tool. It's deliberately not part of the product app and needs no login; like real hardware, it authenticates solely via the station API key.

How to use it

Start the app you want to send to (e.g., pnpm --filter @lab-mgmt/web dev on port 4000). For MQTT, also provide a broker and start the app with MQTT_BROKER_URL (see MQTT Integration). The REST path needs no broker.
Broker via Docker (optional): The repo ships an opt-in Mosquitto broker profile. To test with MQTT, start the app together with the broker and give it the broker address:
```
MQTT_BROKER_URL=mqtt://mqtt:1883 docker compose --profile prod --profile mqtt up -d
```
Locally without Docker, a broker works the same way: mqtt://localhost:1883.
Start the simulator:
```
pnpm --filter @lab-mgmt/simulator dev
```
Then open the dashboard: http://localhost:4100 (port changeable via SIM_PORT).
Get the station API key: In the app, on the station's detail page. The key identifies both the station and the organization.
Get the sequenceItemId: The UUID of the running sequence item is on the test execution page of the respective test case.
Configure in the dashboard:
- Protocol: REST push or MQTT.
  - REST: App URL (e.g., http://localhost:4000).
  - MQTT: broker URL, topic (default testlabiq/ingest), optionally username/password.
- Enter the station API key and sequenceItemId.
- Choose the send interval (ms) and measurement points per channel/send. More than one point spreads the timestamps across the interval — producing a curve instead of a single value.
- Define measurement channels: name (must match the test case, e.g., U_in), unit, waveform, value range (min/max), period, and noise.
Sending:
- Send once sends a single batch — good for a quick check.
- Start begins continuous sending at the configured interval, Stop ends it.
Checking: On the right, the dashboard shows send operations, sent measurement points, values accepted via REST, duplicates, and errors, plus a log of recent sends. In the app, values appear live on the test case page and in the delivery log (GET /api/v1/ingestion/deliveries).

Waveforms

Signal	Behavior
`sine`	sine wave between min and max over the period
`sawtooth`	linear rise min → max, then jump back
`ramp`	triangle min → max → min (e.g., a slowly heating soak test)
`square`	square wave, half period max, half period min
`random`	uniformly distributed random value within the band
`constant`	average of min and max

Optional uniformly distributed noise (± amplitude) is added to every value; the result stays within the [min, max] band.

Defaults from the environment

So the simulator and app work together with no extra setup, the simulator picks up — if set — the same environment variables as the app on startup: NEXT_PUBLIC_APP_URL (REST target), MQTT_BROKER_URL, MQTT_TOPIC, MQTT_USERNAME, MQTT_PASSWORD. Additionally: SIM_PORT (dashboard port, default 4100), SIM_API_KEY, and SIM_SEQUENCE_ITEM_ID as presets.

Common issues

REST reports 401 "Invalid API key". The entered station API key is wrong (or was rotated). Get a new key from the station page.
REST reports 404 "Sequence item not found…". The sequenceItemId doesn't belong to this station's organization, or doesn't exist.
REST connection failed. Is the app running at the entered app URL? Check the port and scheme (http://).
MQTT: "connected = no" or publish errors. Check the broker URL, port, and any credentials. MQTT has no response channel — whether values arrived is shown only by the app's delivery log, not by the simulator (it only confirms publishing).
Values arrive but don't show up live. The channel name and sequenceItemId must match the currently running test case.