---
name: android-device
description: "App auf echtes Android-Handy (Samsung S24 Ultra) deployen, USB-Debugging, Wireless ADB, Logcat auf physischem Gerät. Trigger-Phrasen: 'echtes Handy', 'physisches Gerät', 'USB Debugging', 'Samsung', 'S24', 'auf dem Handy testen', 'Wireless ADB', 'Device'."
---

# Skill: Android Device (Samsung S24 Ultra)

Deployt die Bollwerk-App auf das physische Samsung Galaxy S24 Ultra.

---

## Gerätedaten

| Eigenschaft     | Wert                             |
| --------------- | -------------------------------- |
| Modell          | Samsung Galaxy S24 Ultra         |
| Display         | 6.8" QHD+ (3120 × 1440), 505 PPI |
| Android-Version | Android 14+ (API 34+)            |
| SoC             | Snapdragon 8 Gen 3               |
| RAM             | 12 GB                            |

---

## Ersteinrichtung (einmalig)

### 1. USB-Debugging aktivieren

Auf dem Samsung S24 Ultra:

1. **Einstellungen → Über das Telefon → Softwareinformationen**
2. **Buildnummer** 7× tippen → Entwickleroptionen werden aktiviert
3. **Einstellungen → Entwickleroptionen**:
   - **USB-Debugging** aktivieren
   - **USB-Debugging-Autorisierungen widerrufen** (falls Probleme)
   - Optional: **Bildschirm beim Laden aktiv lassen** aktivieren

### 2. USB-Verbindung

1. Samsung mit USB-C-Kabel an PC anschließen
2. Auf dem Handy: **USB-Debugging zulassen?** → **Immer von diesem Computer zulassen** → OK
3. Prüfen:

```powershell
C:\Users\JensR\AppData\Local\Android\Sdk\platform-tools\adb.exe devices -l
```

Erwartete Ausgabe:

```
XXXXXXXXXXXXXXXX   device product:dm3q model:SM_S928B device:dm3q transport_id:N
```

### 3. Wireless ADB (bevorzugt – kein Datenkabel nötig)

**Voraussetzung:** PC und Handy im selben WLAN (aktuell: `funkbert`).

1. Auf dem Handy: **Einstellungen → Entwickleroptionen → Drahtloses Debugging** aktivieren
2. **"Gerät koppeln mit Kopplungscode"** antippen → IP:Port und 6-stelligen Code merken
3. Am PC koppeln:

```powershell
$adb = "C:\Users\JensR\AppData\Local\Android\Sdk\platform-tools\adb.exe"
& $adb pair <IP>:<KOPPLUNGS-PORT> <CODE>
# Beispiel: & $adb pair 192.168.68.107:36257 644638
```

4. Verbinden (der Verbindungsport steht unter "IP-Adresse und Port" im Drahtloses-Debugging-Menü – **anderer Port als der Kopplungsport!**):

```powershell
& $adb connect <IP>:<VERBINDUNGS-PORT>
# Beispiel: & $adb connect 192.168.68.107:42539
```

5. Prüfen:

```powershell
& $adb devices -l
# Erwartete Ausgabe: 192.168.68.107:42539  device product:e3qxeea model:SM_S928B device:e3q
```

**Hinweis:** Die Kopplung bleibt bestehen, aber der Verbindungsport ändert sich bei jedem Neustart des Debugging-Modus. Der `adb connect`-Befehl muss dann mit dem neuen Port wiederholt werden.

**Wichtig:** `adb -d` (USB-Flag) funktioniert NICHT mit Wireless ADB. Stattdessen `adb -s <IP>:<PORT>` verwenden.

---

## Operationen via Skript

**Hinweis:** Die Skript-Aktionen `deploy-device` und `install-device` verwenden `adb -d` und funktionieren nur über USB. Bei Wireless ADB die manuellen Kommandos verwenden.

```powershell
# App bauen + auf Gerät installieren + starten (nur USB)
& ".github/skills/android-build/android-dev.ps1" -Action deploy-device

# Nur installieren (nur USB)
& ".github/skills/android-build/android-dev.ps1" -Action install-device

# App starten (nur USB)
& ".github/skills/android-build/android-dev.ps1" -Action launch -Target device

# Logcat vom Gerät (nur USB)
& ".github/skills/android-build/android-dev.ps1" -Action logcat -Target device
```

---

## Manuelle Kommandos (Wireless ADB & USB-Fallback)

Alle Kommandos unterstützen sowohl USB (`-d`) als auch Wireless (`-s <IP>:<PORT>`).
Bei Wireless ADB immer `-s` statt `-d` verwenden.

```powershell
$adb = "C:\Users\JensR\AppData\Local\Android\Sdk\platform-tools\adb.exe"
# Geräte-Selektor:
#   USB:      $sel = "-d"
#   Wireless: $sel = "-s 192.168.68.107:42539"  (Port prüfen!)
```

### App bauen + installieren + starten (Wireless-Workflow)

```powershell
$adb = "C:\Users\JensR\AppData\Local\Android\Sdk\platform-tools\adb.exe"
$dev = "192.168.68.107:42539"  # Port prüfen!

# 1. Build
cd X:\bollwerk
.\gradlew.bat assembleDebug

# 2. Install
& $adb -s $dev install -r "app\build\outputs\apk\debug\app-debug.apk"

# 3. Launch
& $adb -s $dev shell am start -n de.bollwerk.app/.MainActivity
```

### App installieren

```powershell
& $adb -s $dev install -r "app\build\outputs\apk\debug\app-debug.apk"
```

`-r` = Reinstall ohne Datenverlust.

### App starten

```powershell
& $adb -s $dev shell am start -n de.bollwerk.app/.MainActivity
```

### App stoppen

```powershell
& $adb -s $dev shell am force-stop de.bollwerk.app
```

### Logcat (gefiltert auf App)

```powershell
& $adb -s $dev logcat --pid=$(& $adb -s $dev shell pidof de.bollwerk.app) -v time
```

### Screenshot vom Gerät

**Wichtig:** `exec-out screencap -p` liefert über Wireless ADB oft korrupte Bilder (Binärdaten-Problem). Stattdessen den **Pull-Workflow** verwenden:

```powershell
# Screenshot auf Gerät speichern, herunterladen, aufräumen
& $adb -s $dev shell screencap -p /sdcard/screenshot.png
& $adb -s $dev pull /sdcard/screenshot.png tmp\device-screenshot.png
& $adb -s $dev shell rm /sdcard/screenshot.png
```

### App deinstallieren

```powershell
& $adb -s $dev uninstall de.bollwerk.app
```

---

## Bekannte Probleme

### 1. `unauthorized` in `adb devices`

Das Handy fragt nach USB-Debugging-Berechtigung, die noch nicht bestätigt wurde.

**Lösung:**

- Display entsperren
- Dialog **USB-Debugging zulassen?** bestätigen
- Falls kein Dialog: Entwickleroptionen → **USB-Debugging-Autorisierungen widerrufen** → USB neu anschließen

### 2. `no devices/emulators found`

**Checkliste:**

1. USB-Kabel prüfen (manche Kabel sind nur zum Laden)
2. USB-Debugging aktiviert?
3. ADB-Daemon neu starten: `& $adb kill-server; & $adb start-server`
4. Samsung-USB-Treiber installiert?

### 3. `INSTALL_FAILED_UPDATE_INCOMPATIBLE`

Die App ist mit einem anderen Signaturschlüssel installiert.

**Lösung:**

```powershell
& $adb -d uninstall de.bollwerk.app
& $adb -d install "app\build\outputs\apk\debug\app-debug.apk"
```

### 4. Samsung-spezifisch: App wird von Knox blockiert

Samsung Knox kann Debug-Apps blockieren. In **Entwickleroptionen → Apps über USB installieren** aktivieren.