# Folding@home Add-on Dokumentation

## Über dieses Add-on

Dieses Add-on führt den [Folding@home](https://foldingathome.org/) Client (Version 8.x) als
Home Assistant Add-on aus. Folding@home ist ein verteiltes Rechenprojekt, das die Rechenleistung
deines Computers nutzt, um Proteinfaltungssimulationen für medizinische Forschung durchzuführen
(z. B. Alzheimer, Krebs, COVID-19).

---

## Installation

1. Öffne Home Assistant und gehe zu:
   **Einstellungen → Add-ons → Add-on Store**
2. Klicke oben rechts auf **⋮ → Repositories**
3. Füge folgende URL hinzu:
   ```
   https://gitea.bitfire.work/retr0/dont-stop-folding
   ```
4. Schließe den Dialog – das Add-on „Folding@home" erscheint nun im Store
5. Klicke auf das Add-on und dann auf **Installieren**
6. Konfiguriere die gewünschten Optionen (siehe unten)
7. Klicke auf **Starten**

---

## Konfiguration

### Optionen

| Option          | Typ    | Standard  | Beschreibung |
|-----------------|--------|-----------|--------------|
| `user`          | string | _(leer)_  | Dein Folding@home-Benutzername. Wird für die Statistikseite verwendet. |
| `team`          | string | `247478`  | Team-ID. `247478` ist das offizielle Home Assistant Team. |
| `passkey`       | string | _(leer)_  | Dein persönlicher Passkey von foldingathome.org. Aktiviert Bonus-Punkte. |
| `account_token` | string | _(leer)_  | Token für das neue FAH 8 Online-Konto (von foldingathome.org). |
| `machine_name`  | string | _(leer)_  | Anzeigename dieser Maschine im FAH-Online-Konto. |

### Beispielkonfiguration

```yaml
user: "mein_benutzername"
team: "247478"
passkey: "abc123..."
```

Mit FAH 8 Online-Konto:
```yaml
account_token: "eyJ..."
machine_name: "homeassistant"
```

> Die Leistungsstufe lässt sich nach dem Start im Web-Interface unter `http://<ip>:7396` anpassen.

---

## Web-Interface

Nach dem Start ist die Folding@home Web-UI erreichbar unter:

```
http://<homeassistant-ip>:7396
```

Dort kannst du:
- Aktuelle Work Units und Fortschritt einsehen
- Die Leistungsstufe manuell anpassen
- Folding pausieren oder fortsetzen
- Statistiken abrufen

---

## Zwei Kontosysteme

Folding@home bietet zwei Möglichkeiten, Punkte zu sammeln:

### Klassisch (user + passkey)
Das bewährte System – erstelle einen Account auf [foldingathome.org](https://foldingathome.org/),
trage Benutzernamen und optional einen Passkey ein.

### FAH 8 Online-Konto (account_token)
Das neue System seit Version 8. Erstelle ein Konto auf
[foldingathome.org](https://foldingathome.org/), generiere einen Token und trage
ihn unter `account_token` ein. `machine_name` gibt der Maschine einen erkennbaren Namen
in deinem Konto-Dashboard.

> Hinweis: Beide Systeme können nicht gleichzeitig aktiv sein. Wenn `account_token`
> gesetzt ist, wird er bevorzugt. Ohne beides wird anonym gefaltet.

---

## Datenspeicherung

Der FAH Client speichert seine Konfiguration und Work-Unit-Daten im
Home Assistant Konfigurationsverzeichnis unter:

```
/config/  (innerhalb des Containers)
```

Die Daten bleiben bei Neustarts und Updates des Add-ons erhalten.

---

## Unterstützte Architekturen

| Architektur | Unterstützt |
|-------------|-------------|
| `amd64`     | ✓           |
| `aarch64`   | ✓           |
| `armhf`     | ✗ (vom FAH 8 Client nicht unterstützt) |
| `armv7`     | ✗ (vom FAH 8 Client nicht unterstützt) |

---

## Problembehandlung

### Add-on startet nicht
- Prüfe im Log-Tab des Add-ons auf Fehlermeldungen
- Stelle sicher, dass Port `7396` nicht von einem anderen Dienst belegt ist

### Web-Interface nicht erreichbar
- Warte 30–60 Sekunden nach dem Start – der FAH Client benötigt etwas Zeit zum Initialisieren
- Prüfe, ob das Add-on im Status „Läuft" angezeigt wird

### Keine Punkte / kein Fortschritt
- Der FAH Server weist Work Units zu – bei geringer Auslastung der Server kann es zu Wartezeiten kommen
- Prüfe im Web-Interface unter `http://<ip>:7396`, ob aktiv gefaltet wird
- Stelle sicher, dass `user` und `team` korrekt eingetragen sind

### „No appropriate assignment" im Log (Raspberry Pi / ARM)
Meldungen wie `HTTP_SERVICE_UNAVAILABLE: {"error":"No appropriate assignment"}` sind auf ARM-Geräten ohne GPU (z. B. Raspberry Pi) normal. FAH 8 priorisiert GPU- und x86-Clients – für reine ARM-CPUs sind schlicht weniger Arbeitspakete verfügbar.

Der Client wiederholt die Anfrage automatisch mit exponentiell steigendem Abstand. Es ist keine Aktion erforderlich – nach einigen Stunden wird in der Regel eine Work Unit zugeteilt. Das Add-on muss **nicht** neu gestartet werden.

### Anonym falten
Wenn weder `user` noch `account_token` gesetzt sind, werden Beiträge unter dem
anonymen Benutzer gesammelt. Die Leistung ist identisch, nur die Statistiken werden
keinem Konto zugeordnet.