Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -159,3 +159,7 @@ $RECYCLE.BIN/
# Windows shortcuts
*.lnk
open_wearable/devtools_options.yaml

# Private participant recordings and local squat development data.
/temp/
/open_wearable/tool/squats/data/
95 changes: 95 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
# CLAUDE.md

Dieses Repo ist unser Team-Fork der OpenWearables-App für das **Praktikum Wearable Computing** (KIT, TECO, WS 2026/27). Wir sind Projektgruppe 4 und bauen **Earable Fitness Tracking**. Quelle für den Seminarteil: Intro-Folien vom 04.11.2026.

## Unser Projekt: Earable Fitness Tracking

**Ziel:** Ein Echtzeit-System für OpenEarable 2.0, das aus den Sensordaten am Ohr Schritte zählt, Übungen erkennt, Wiederholungen zählt und übungsbezogene Werte schätzt. Die Ergebnisse zeigt eine App dem Nutzer an.

**Aufgaben:**

1. **Schrittzähler:** robust und dauerhaft laufend auf IMU-Basis. Echte Schritte von Kopfbewegungen trennen. Vorverarbeitung, Peak-Detection und adaptive Schwellwerte untersuchen, mit verschiedenen Gehgeschwindigkeiten und Alltagsbewegungen testen.
2. **Übungen und Wiederholungen:** zuerst Kniebeugen und Liegestütze, später erweiterbar. Herausfinden, welche IMU-Features die Übungen gut beschreiben, und Algorithmen mit leichtgewichtigen ML-Klassifikatoren vergleichen.
3. **Sprunghöhe:** Sprünge erkennen und die Höhe aus der vertikalen Kopfbewegung schätzen. Genauigkeit gegen eine passende Referenzmessung prüfen.
4. **App-Integration:** Echtzeit-Feedback und Zusammenfassung von Schritten, Übungen, Wiederholungen und Sprunghöhe.
5. **Evaluation:** unter realistischen Bedingungen, über verschiedene Personen, Tempi und Ausführungsstile. Metriken: Schrittzahl-Fehler, Erkennungsgenauigkeit, Wiederholungsfehler, Sprunghöhen-Fehler.

**Bonus:** Übungen automatisch erkennen, Gehen, Laufen und Treppensteigen unterscheiden, multimodale Erkennung aus IMU und Mikrofon (z. B. Schrittgeräusche).

**Ausgangspunkt:** Die App gibt Zugriff auf alle Sensoren, eigene Apps laufen direkt in ihr, Audio ist über LE Audio verfügbar. Daten werden zum Smartphone gestreamt oder bei großen Mengen und Audio auf microSD geschrieben. Gerät, microSD und bei Bedarf ein Smartphone mit BLE 5.3 stellt der Lehrstuhl.

## Seminar: Rahmen und Bewertung

Gruppen aus 4 Personen: Problem verstehen, Lösung konzipieren, Prototyp bauen, iterieren, mit Nutzern testen, dokumentieren. Insgesamt sollen etwa 10–20 Personen an Datensammlung und/oder Evaluation teilnehmen. Das Ganze gilt als Vorstudie, auf der andere aufbauen können.

| Teil | Gewicht | Erwartung |
| --- | --- | --- |
| Zwischenpräsentation | unbenotet | ca. 10 min Vortrag, 10 min Diskussion |
| Abschlusspräsentation | **50 %** | 20 min inkl. Prototyp-Demo, 5 min Diskussion |
| Code | **25 %** | GitHub-Repo oder Zip, sorgfältig dokumentiert, gutes README, Abhängigkeiten festgehalten (`pubspec.yaml`, für Python `requirements.txt` oder `pyproject.toml`) |
| Paper | **25 %** | TECO-Overleaf-Vorlage, ca. 10–15 Seiten ohne Referenzen und Abbildungen, Abbildungen trotzdem einbauen |

**Aufbau des Papers:** kurze Einleitung, Related Work (ca. 1 Seite), Problem, Dokumentation der Lösung, Diskussion und Fazit. Andere sollen damit weiterarbeiten können.

### Termine

Pflichttermine sind fett. Q/A-Termine sonst freiwillig: mindestens 24 h vorher anmelden und etwas Praktisches zum Zeigen mitbringen (Stand, Fortschritt, Probleme).

| Datum | Termin |
| --- | --- |
| **11.11.2026** | **Q/A-Session (Pflicht), bis dahin zur Prüfung angemeldet sein** |
| 25.11., 09.12.2026 | Q/A |
| **16.12.2026** | **Zwischenpräsentation** |
| 13.01., 27.01., 10.02.2027 | Q/A |
| **17.02.2027** | **Abschlusspräsentation** |
| **31.03.2027, 23:59** | **Finale Abgabe** |

## Dokumentation ist Teil jeder Aufgabe

Präsentationen und Paper entstehen aus dieser Doku, deshalb wird sie **laufend** geschrieben und nicht erst am Ende:

- Jede nennenswerte Änderung, jedes Experiment und jede Entscheidung kommt im selben PR nach `docs/`. Aufbau siehe [docs/README.md](docs/README.md).
- Immer festhalten, **warum** etwas so gemacht wurde und welche Alternativen verworfen wurden.
- Messwerte nur mit Kontext: Personenzahl, Ablauf, Sensorrate, Referenzmessung, Datum.
- Abbildungen und Diagramme, die in Präsentation oder Paper taugen, unter `docs/figures/` ablegen und das Skript dazu mit einchecken.
- Claude denkt von sich aus daran und nennt am Ende einer Aufgabe, was dokumentiert wurde.
- Praktikumsdoku auf Deutsch, Code und Kommentare auf Englisch.

**Das Repo ist öffentlich:** keine Rohdaten von Probanden und keine personenbezogenen Daten einchecken, nur anonymisierte Ergebnisse.

## Repo-Überblick

- `open_wearable/`: die Flutter-App, hier läuft alles ab.
- `lib/apps/`: In-App-Anwendungen. Neue App in `lib/apps/<name>/` anlegen und in `_apps` in `lib/apps/widgets/apps_page.dart` eintragen. `posture_tracker/` ist die Vorlage (`model/`, `view/`, `view_model/`).
- `lib/view_models/`: übergreifender Zustand (Provider), `lib/router.dart`: Routen, `lib/main.dart`: Start.
- `test/`: Tests, `docs/`: App-Doku von Upstream. Bei Architekturänderungen mitpflegen.
- `docs/`: unsere Praktikumsdoku.
- Sensorzugriff läuft über das Paket `open_earable_flutter`. Beispiel: `lib/apps/posture_tracker/model/earable_attitude_tracker.dart`.

## Entwickeln

Befehle aus `open_wearable/` heraus. Vor jedem PR müssen die letzten drei durchlaufen:

```bash
flutter pub get
flutter run
dart format lib test
flutter analyze
flutter test
```

- Ohne Hardware testen: `flutter run --dart-define=APP_STORE_PREVIEW=true`
- Flutter-Version steht in `open_wearable/.flutter_version`.
- **Windows:** Für `flutter pub get` muss der Entwicklermodus an sein (Symlinks für Plugins).
- **Android-Toolchain:** Gradle 9.3.1, AGP 9.1.0, Kotlin 2.4.0. Java 25 braucht mindestens Gradle 9.1, Flutter 3.47 testet bis Gradle 9.3.1. Die CI baut mit Java 21. Hintergrund im [Journal](docs/journal.md).

## Git

- **`origin` ist unser Fork, `gh` zielt bei Forks aber standardmäßig auf Upstream.** PRs daher immer so erstellen:

```bash
gh pr create --repo philgenb/openearable-activity-tracker --base main
```

- Nichts an `OpenEarable/app` schicken, außer das Team will das ausdrücklich.
- Regeln aus [CONTRIBUTING.md](CONTRIBUTING.md): eigener Branch pro Änderung, Conventional Commits, Rebase statt Merge, öffentliche APIs dokumentieren.
31 changes: 31 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Praktikumsdoku: Earable Fitness Tracking

Hier sammeln wir alles, was wir für Zwischenpräsentation, Abschlusspräsentation und Paper brauchen. Die technische Doku der App selbst liegt in [`open_wearable/docs/`](../open_wearable/docs/README.md).

## Aufbau

| Pfad | Inhalt | Wird genutzt für |
| --- | --- | --- |
| [`journal.md`](journal.md) | Was wir gemacht und entschieden haben, neueste Einträge oben | Stand für Q/A und Präsentationen, roter Faden fürs Paper |
| `algorithmen/` | Eine Datei pro Algorithmus (Schritte, Übungen, Sprunghöhe): Ansatz, Parameter, Alternativen | Paper: Dokumentation der Lösung |
| `evaluation/` | Studienprotokolle, Metriken, anonymisierte Ergebnisse | Paper und Präsentation: Ergebnisse, Diskussion |
| `related-work.md` | Gelesene Paper mit Kurznotiz und Zitat | Paper: Related Work |
| `praesentationen/` | Gliederung und Kernaussagen je Termin | Zwischen- und Abschlusspräsentation |
| `figures/` | Abbildungen samt Quelle oder Skript | Präsentationen und Paper |

Erster Algorithmusbericht: [Liegestütz-Zählung](algorithmen/liegestuetze.md).
Kniebeugen mit lokalen Realaufnahmen: [Entwicklung und Messkriterien](algorithmen/kniebeugen.md).
Weitere Pfade legen wir an, sobald es dafür Inhalt gibt.

## Journal-Eintrag

Kurz halten und diese Fragen beantworten:

- **Was** wurde gemacht?
- **Warum** so, und was wurde verworfen?
- **Ergebnis:** Zahlen mit Kontext (Personenzahl, Ablauf, Sensorrate, Referenzmessung).
- **Offen:** Was fehlt noch, was ist ungeprüft?

## Datenschutz

Das Repo ist öffentlich. Rohdaten von Probanden und personenbezogene Daten gehören nicht hierher, nur anonymisierte Ergebnisse.
130 changes: 130 additions & 0 deletions docs/algorithmen/kniebeugen.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# Kniebeugen: Entwicklung mit realen IMU-Aufnahmen

Stand: 17.11.2026. Manuell gewählter Squat-Modus, kein ML-Klassifikator.

## Wiederverwendung und Abgrenzung

Wie bei Liegestützen liefert `ActivityEngine` Kalibrierung, Gyro-gestützte
Schwerkraftrichtung, vertikale Projektion und kausale Tiefpassfilterung. Sensorquelle,
Controller, Satzverwaltung, Export und Übungsbildschirm werden wiederverwendet.
`SquatDetector` ersetzt den bisherigen privaten `_RepetitionDetector`; der
Liegestütz-Detektor und die Schwellen anderer Modi bleiben unverändert.

Der Entwicklungsbereich liegt unter `open_wearable/tool/squats/`: Manifest,
CSV-Replay und lokale, ignorierte Aufnahmen. Rohdaten aus `temp/` bleiben ebenfalls
ignoriert. Öffentlich dokumentiert werden nur aggregierte Ergebnisse.

## Datensatz: Reihenfolge ist Teil der Referenz

Die fünf Ordnernamen geben folgende Abfolgen vor:

| Aufnahme | Abfolge | Referenz-Kniebeugen |
| --- | --- | ---: |
| squat-01 | 10 Kniebeugen | 10 |
| squat-02 | 5 Kniebeugen → Gehen → 5 Kniebeugen | 10 |
| squat-03 | 5 Kniebeugen → Hinsetzen → 5 Kniebeugen | 10 |
| squat-04 | 5 Kniebeugen → 3 Liegestütze → 5 Kniebeugen | 10 |
| squat-05 | 5 Kniebeugen → Treppen/Gehen → 5 Kniebeugen → Hinsetzen → 5 Kniebeugen → 3 Liegestütze | 15 |

Die gesamte Aufnahme läuft im Squat-Modus. Fremdbewegungen sind Negativkontrollen,
nicht herausgefilterte Daten. Die Zählreferenz stammt ausschließlich aus den
Ordnernamen. Übergangszeitpunkte, Versuchspersonenzahl, Ausführungstempo,
Aufnahmedatum und synchronisierte Referenzvideos sind nicht angegeben. Der
17.11.2026 ist das Auswertungsdatum, nicht das behauptete Messdatum.
Beschleunigung: m/s²; Gyroskop: deg/s als explizite Annahme aus dem üblichen
OE2-Export, im Replay nach rad/s umgerechnet. Die Exportdateien enthalten keine
Einheitenmetadaten. Sensorrate ungefähr 99,9 Hz; die lange Aufnahme enthält zwei
Lücken über 120 ms.

## Entscheidung: Wann zählt eine Wiederholung?

1. Im Squat-Modus reicht ein stabiler 0,7-s-Start: Betrag nahe 1 g (±0,55 m/s²),
Gyro unter 0,35 rad/s und Betragsspanne höchstens 0,45 m/s². Andere Modi behalten
ihre 1,5-s-Kalibrierung. Damit werden kleine Kopfbewegungen toleriert, nicht
beliebig bewegte Daten nachträglich als kalibriert ausgegeben.
2. Der Detektor speichert die anfängliche Schwerkraftrichtung als Haltungsreferenz.
Starke Rotation (>1,2 rad/s) oder eine Abweichung von ungefähr 46° verwerfen
die aktuelle Bewegung; die ursprüngliche Haltungsreferenz bleibt bestehen.
3. Gefilterte vertikale Beschleunigung wird kurzfristig integriert. Gedämpfte
Geschwindigkeit (1,5 s) und Position (4 s) begrenzen Offsetdrift. Im ruhigen,
inaktiven Zustand wird der Restoffset nachgeführt.
4. Absenken beginnt unter −0,06 m/s und −0,048 m Positionsproxy. Der Mindesthub
ist 0,12 m; die Rückkehrphase beginnt über +0,04 m/s.
5. Die Position muss mindestens 70 % der Absenkung zurückkehren. Gezählt wird
nahe dem oberen Geschwindigkeitsumkehrpunkt, frühestens nach 0,8 s und vor
einem 6-s-Zeitlimit. Nach einem Halt verhindert eine separate ungedämpfte
Referenz, dass Positionsdämpfung allein eine Teilrückkehr vervollständigt.
6. Übersteuerung und starke Bewegungen verwerfen nur den laufenden Zyklus.
Pausen, Datenlücken, ungültige Daten und Moduswechsel setzen den Detektor
vollständig zurück. Bestätigte Zählungen bleiben im Controller erhalten.

Mindesthub und Positionswerte sind **Bewegungsproxies**, keine gemessene
anatomische Tiefe oder Bewertung der Kniebeugentechnik. Die IMU am Ohr kann
Knie-/Hüftbewegung nicht direkt beobachten. Hinsetzen und Aufstehen ohne längeren
Halt können ähnlich aussehen; reine vertikale Kopfbewegungen ebenfalls.

Verworfen: rohe Y-Achse als universelle Vertikale (sensor-/haltungsabhängig),
Übernahme der empfindlichen Liegestütz-Schwellen (kleine Fremdbewegungen),
unbegrenzte doppelte Integration (Drift), automatische Übungsklassifikation oder
ML mit diesen fünf nicht zeitannotierten Aufnahmen (keine belastbare Grundlage).
Keine nachträgliche künstliche Startkalibrierung und keine Sonderbehandlung
anhand des Dateinamens.

## Messkriterien und Grenzen

Entwicklungsvergleich: erwartete und gezählte Wiederholungen, signierter und
absoluter Zählfehler pro Aufnahme sowie Kalibrierungsabdeckung und Ereigniszeiten.
Baseline des bisherigen Codes in obiger Reihenfolge: 0, 0, 4, 0, 7.
Drei Aufnahmen bestanden nie die bisherige Startkalibrierung.

**Gleiche Gesamtzahl ist kein Klassifikationsnachweis.** Fehlzählungen in
Negativabschnitten können ausgelassene Kniebeugen kompensieren. Ereignisbezogene
Precision/Recall, falsch positive Zählungen pro Fremdbewegung und Wiederholungsfehler
pro Satz benötigen unabhängig annotierte Zeitintervalle. Dieses Material dient
zur Entwicklung, nicht als unabhängiger Testdatensatz oder nutzerübergreifender
Genauigkeitsnachweis. Keine Parameter anhand von Dateinamen auswählen.

## Ergebnisse vom 17.11.2026

Vollständiges kausales Replay mit deg/s-Annahme, 20-ms-Gyrozuordnung und ohne
künstliche Startdaten; Ergebnisse unter
[`results.json`](../../open_wearable/tool/squats/results.json).

| Aufnahme | Soll | Bisher | Jetzt | Fehler jetzt | Erste Kalibrierung (s) | Kalibrierte Samples (%) |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| squat-01 | 10 | 0 | 10 | 0 | 0,72 | 96,84 |
| squat-02 | 10 | 0 | 9 | −1 | 0,73 | 97,68 |
| squat-03 | 10 | 4 | 9 | −1 | 0,71 | 97,68 |
| squat-04 | 10 | 0 | 7 | −3 | 1,80 | 95,05 |
| squat-05 | 15 | 7 | 8 | −7 | 43,70 | 71,24 |

Summe: 43 Zählungen bei 55 laut Ordnernamen vorgegebenen Kniebeugen; vorher 11.
Mittlerer absoluter Gesamtzählfehler je Aufnahme: 2,4 statt 8,8. Das ist **keine
Recall- oder Genauigkeitsangabe**. Beim langen Ablauf fehlt die Kalibrierung bis
43,70 s; dort kann der kausale Detektor vorherige Bewegungen nicht zählen.
Auch spätere Bestätigungen können ohne Zeitannotation nicht sicher den
Kniebeugen statt Fremdbewegungen zugeordnet werden. Der Mischdatensatz zeigt
weiterhin erhebliche Zählfehler; robuste Fremdbewegungsabgrenzung ist nicht belegt.

102 gezielte Tests bestanden: 21 neue synthetische Kniebeugenfälle,
49 bestehende Liegestützfälle, 14 Engine-Fälle und 18 CSV-/Zuordnungsfälle.
Synthetische Fälle umfassen vollständige Zyklen, verschiedene Tempi/Raten,
andere Sensororientierung, kleine Kopfbewegungen, Teilrückkehr, Halten,
Rotation, Übersteuerung, Datenlücke, Pause und Moduswechsel. Keine BLE-/Hardware-
oder Videoverifikation durchgeführt.
Die sechs geänderten/neuen Dart-Dateien wurden formatiert und gezielt mit
`dart analyze` geprüft: keine Befunde. Keine vollständige App-Testsuite oder
plattformweite Buildprüfung ausgeführt.


## Reproduktion

Aus `open_wearable/`:

```sh
dart run tool/squats/replay.dart
flutter test test/apps/activity_tracker/squat_detector_test.dart test/apps/activity_tracker/activity_engine_test.dart test/apps/activity_tracker/push_up_detector_test.dart test/tool/squat_recordings_test.dart
```

Die lokalen Dateien und genaue Replay-Aufrufvarianten beschreibt
[`tool/squats/README.md`](../../open_wearable/tool/squats/README.md).
Loading