Fahrsimulator_MSY2526_UX/README.md

Virtueller Gesundheitsassistent

A Java 17 desktop application that ingests binary health predictions over MQTT, stores them in SQLite, computes rolling risk levels, and visualizes the result in a dashboard with optional avatar/Unreal integration.

Contents

• Features
• Architecture Overview
• Tech Stack
• Getting Started
• Configuration
• Testing
• Project Structure
• Documentation
• Known Limitations

Features

• Swing desktop UI with:
  • Avatar Streaming tab (embedded JCEF browser)
  • Dashboard tab (risk time-series chart + level bar)
• MQTT subscription to prediction events (PREDICTION by default)
• SQLite persistence (data/health.db)
• Threshold-based risk classification from the latest 20 values:
  • NONE for ratio < 0.5
  • WARNING for ratio >= 0.5
  • HIGH for ratio >= 0.8
  • DISASTER for ratio >= 0.9
• Animation state JSON export (animation.output.path)
• Optional startup/shutdown management for:
  • Python MQTT simulator
  • Unreal/Pixel Streaming startup script
• Asynchronous logger with optional file output and rotation

Architecture Overview

Runtime flow:

1. The app initializes UI and services.
2. MQTT messages are received on a configured topic.
3. Incoming JSON payloads are validated.
4. Accepted predictions are persisted in SQLite.
5. Risk ratio and level are re-evaluated.
6. App state notifies UI controllers.
7. Dashboard widgets and chart update.
8. Animation JSON is written for external consumers.

Tech Stack

• Java 17
• Maven
• Swing + FlatLaf + JFreeChart
• Eclipse Paho MQTT client
• SQLite JDBC
• JCEF (jcefmaven)
• JUnit 5 + Mockito

Getting Started

Prerequisites

• JDK 17
• Maven 3.9+
• MQTT broker running at localhost:1883 (or adjust config)
• Windows for bundled PowerShell/BAT integration scripts
• Optional: Python for simulator support
• Optional: Unreal/Pixel Streaming environment

1) Configure a minimal local run

In src/main/resources/config/application.properties, disable optional external integrations if they are not available on your machine:

mqtt_sim.enabled=false
unreal.enabled=false

2) Build and run

mvn clean compile
mvn org.codehaus.mojo:exec-maven-plugin:3.5.0:java -Dexec.mainClass=vassistent.App

You can also run vassistent.App directly from an IDE.

3) Send test data

Publish to topic PREDICTION with payload format:

{
  "valid": true,
  "_id": 1,
  "prediction": 0
}

Validation rules:

• valid must be true
• _id must exist
• prediction must be 0 or 1

Configuration

Main config: src/main/resources/config/application.properties
Logger config: src/main/resources/config/logger.properties

High-impact keys:

• mqtt.broker.url, mqtt.client.id, mqtt.topic
• streaming.url
• animation.output.path
• mqtt_sim.enabled, python.path, mqtt_sim.script
• unreal.enabled, unreal.executable, unreal.signalling_server.script

A full key-by-key reference is available in docs/CONFIGURATION.md.

Testing

Run tests with:

mvn test

The suite includes unit and integration tests for state changes, payload validation, threshold evaluation, persistence behavior, process management, MQTT behavior, and animation output.

Project Structure

src/main/java/vassistent
  App.java
  bootstrap/      # startup wiring + shutdown sequencing
  controller/     # UI orchestration
  model/          # app state + value objects
  service/        # MQTT, DB, stats, evaluation, processes
  ui/             # Swing views/components
  util/           # config loading/validation + logging

src/main/resources
  config/application.properties
  config/logger.properties
  scripts/mqtt_simulator.py
  scripts/start_avatar.ps1

Documentation

• Documentation Index
• Project Review
• Architecture
• Setup and Run
• Configuration
• Testing
• Source Map
• Known Issues

Known Limitations

• The runtime database (data/health.db) is currently deleted on application shutdown.
• Default Unreal-related paths in application.properties are machine-specific and require adaptation on other systems.
• Enabling optional external integrations without valid local paths causes startup validation to fail.