237 lines
7 KiB
Markdown
237 lines
7 KiB
Markdown
---
|
||
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.
|
||
|
||
### Robustes Python-Deployment (empfohlen)
|
||
|
||
Neues Skript: `.github/skills/android-device/deploy-device.py`
|
||
|
||
```powershell
|
||
# Standard: Build + Device erkennen + Install + Launch
|
||
python ".github/skills/android-device/deploy-device.py" --repo-root "X:\bollwerk"
|
||
|
||
# Explizites Wireless-Geraet
|
||
python ".github/skills/android-device/deploy-device.py" --repo-root "X:\bollwerk" --serial "192.168.68.107:42539"
|
||
|
||
# Ohne Build (wenn APK schon gebaut), nur Install
|
||
python ".github/skills/android-device/deploy-device.py" --repo-root "X:\bollwerk" --skip-build --no-launch
|
||
```
|
||
|
||
Funktionen:
|
||
|
||
- ADB-Autodetect ueber `--adb`, `ANDROID_SDK_ROOT`/`ANDROID_HOME` oder `local.properties`
|
||
- Robuste Device-Erkennung (USB oder Wireless)
|
||
- Install-Retries mit klaren Fehlern
|
||
- Definierte Exitcodes (`0` Erfolg, `1` Fehler)
|
||
|
||
```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.
|