166 lines
4.8 KiB
Markdown
166 lines
4.8 KiB
Markdown
# Virtueller Gesundheitsassistent
|
|
|
|
Java desktop application that receives binary health predictions via MQTT, stores them in SQLite, computes rolling risk ratios, and visualizes the result in a dashboard with an avatar streaming view.
|
|
|
|
## Documentation
|
|
|
|
- [Docs Index](docs/INDEX.md)
|
|
- [Architecture](docs/ARCHITECTURE.md)
|
|
- [Setup and Run](docs/SETUP_AND_RUN.md)
|
|
- [Configuration](docs/CONFIGURATION.md)
|
|
- [Source Map](docs/SOURCE_MAP.md)
|
|
- [Testing](docs/TESTING.md)
|
|
- [Known Issues](docs/KNOWN_ISSUES.md)
|
|
|
|
## Features
|
|
|
|
- Swing desktop UI with two tabs:
|
|
- `Avatar Streaming` (embedded JCEF browser, default `http://localhost`)
|
|
- `Dashboard` (time series chart + problem level bar)
|
|
- MQTT client subscriber (`tcp://localhost:1883`) for prediction events
|
|
- SQLite persistence (`data/health.db`)
|
|
- Rolling ratio evaluation and automatic risk level classification:
|
|
- `NONE` for `< 0.5`
|
|
- `WARNING` for `>= 0.5`
|
|
- `HIGH` for `>= 0.8`
|
|
- `DISASTER` for `>= 0.9`
|
|
- Writes animation state JSON for Unreal integration
|
|
- Optional external process startup:
|
|
- Python MQTT simulator
|
|
- Unreal/Pixel Streaming scripts
|
|
- Custom async logger with file output + rotation
|
|
|
|
## Tech Stack
|
|
|
|
- Java 17
|
|
- Maven
|
|
- Swing + FlatLaf
|
|
- JFreeChart
|
|
- Eclipse Paho MQTT
|
|
- SQLite JDBC
|
|
- JCEF (`jcefmaven`)
|
|
- JUnit 5 + Mockito (tests)
|
|
|
|
## Runtime Flow
|
|
|
|
1. App initializes look and feel and services.
|
|
2. MQTT subscriber listens on topic from config (`mqtt.topic`).
|
|
3. Incoming JSON payloads are validated in `BinaryEventService`.
|
|
4. `prediction` (`0`/`1`) is stored in SQLite.
|
|
5. `EvaluationService` computes ratio over last 20 values.
|
|
6. `AppState` updates notify UI controllers.
|
|
7. Dashboard chart and status bar refresh.
|
|
8. Animation state file is written for Unreal consumption.
|
|
|
|
## Payload Format
|
|
|
|
Incoming MQTT payload must be JSON like:
|
|
|
|
```json
|
|
{
|
|
"valid": true,
|
|
"_id": 123,
|
|
"prediction": 0
|
|
}
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
- JDK 17
|
|
- Maven 3.9+
|
|
- Local MQTT broker on `localhost:1883` (or adjust code/config)
|
|
- Windows environment if using bundled process scripts/paths
|
|
- Optional: Python (if MQTT simulator should be auto-started)
|
|
- Optional: Unreal + Pixel Streaming setup (path-based integration)
|
|
|
|
## Configuration
|
|
|
|
Main config: `src/main/resources/config/application.properties`
|
|
|
|
- `app.mode`: current mode flag (`test`)
|
|
- `streaming.url`: initial URL for embedded stream browser
|
|
- `python.path`: Python executable for simulator startup
|
|
- `mqtt.broker.url`: MQTT broker URL
|
|
- `mqtt.client.id`: MQTT client id
|
|
- `mqtt.topic`: subscribed topic (default `PREDICTION`)
|
|
- `mqtt_sim.enabled`: start simulator process on app startup
|
|
- `mqtt_sim.script`: simulator script path
|
|
- `animation.output.path`: path for generated animation JSON file
|
|
- `unreal.enabled`: start Unreal-related processes
|
|
- `unreal.executable`: PowerShell script path for Unreal start
|
|
- `unreal.signalling_server.script`: signalling server batch path
|
|
- `unreal.pid.file`: PID file used for Unreal shutdown cleanup
|
|
- `unreal.signalling.pid.file`: PID file used for signalling shutdown cleanup
|
|
|
|
Logger config: `src/main/resources/config/logger.properties`
|
|
|
|
- `logger.level`
|
|
- `logger.file.enabled`
|
|
- `logger.file`
|
|
- `logger.max.size.mb`
|
|
|
|
## Run
|
|
|
|
### 1) Start MQTT Broker
|
|
|
|
Start a broker on `localhost:1883` (for example Mosquitto).
|
|
|
|
### 2) Start the App
|
|
|
|
```powershell
|
|
mvn clean compile
|
|
mvn org.codehaus.mojo:exec-maven-plugin:3.5.0:java -Dexec.mainClass=vassistent.App
|
|
```
|
|
|
|
Or run `vassistent.App` directly from IntelliJ.
|
|
|
|
### 3) Send Test Data
|
|
|
|
Option A: enable simulator in `application.properties`:
|
|
|
|
- set `mqtt_sim.enabled=true`
|
|
- verify `python.path` and `mqtt_sim.script`
|
|
|
|
Option B: publish messages manually to topic `PREDICTION`.
|
|
|
|
## Tests
|
|
|
|
Run:
|
|
|
|
```powershell
|
|
mvn test
|
|
```
|
|
|
|
Current state in this repository on Java 17:
|
|
|
|
- unit and integration tests are available for state, event processing, evaluation, persistence, and statistics
|
|
- test stack uses JUnit 5 + Mockito JUnit Jupiter
|
|
- full suite runs successfully with `mvn test`
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
src/main/java/vassistent
|
|
App.java
|
|
bootstrap/ # wiring, context, shutdown sequencing
|
|
controller/ # Swing controllers
|
|
model/ # state + data types
|
|
service/ # MQTT, DB, stats, evaluation, processes
|
|
ui/ # App window, dashboard, streaming, widgets
|
|
util/ # config + logger
|
|
|
|
src/main/resources
|
|
config/application.properties
|
|
config/logger.properties
|
|
scripts/mqtt_simulator.py
|
|
scripts/start_avatar.ps1
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
- Animation output path is now config-driven (`animation.output.path`).
|
|
- MQTT broker URL/client id are config-driven (`mqtt.broker.url`, `mqtt.client.id`).
|
|
- Unreal PID cleanup paths are config-driven (`unreal.pid.file`, `unreal.signalling.pid.file`).
|
|
- On app shutdown, `data/health.db` is deleted by `App.deleteDatabase()`.
|
|
- The signalling server process startup in `ProcessManagerService` is prepared but currently not launched (`pb.start()` commented).
|