linux-on-android-without-root/spike/README.md

# Phase 0 — Machbarkeits-Spike

Vier Annahmen tragen das gesamte Projekt. Scheitert eine, sieht alles Weitere anders
aus — und das will man **vor** dem Bau der Infrastruktur wissen, nicht danach.

Der Code hier ist bewusst Wegwerf-Code. Was zählt, sind die Protokolle: sie werden
später zur Grundlage der Setup-Skripte in `rootfs/`.

| | Beweis | Wenn er scheitert |
|---|---|---|
| **S1** | Plasma Mobile läuft in proot (genestetes KWin) | XFCE-Profil wird Hauptweg; Kamera-Portal, Bildschirmtastatur und Telefonie-Oberfläche ändern sich mit |
| **S2** | Mikrofon-Eingang erreicht die Linux-Seite | Keine Videocalls, keine Sprachaufnahme, keine Spracheingabe |
| **S3** | Virtuelle PipeWire-Kamera ohne Kernel-Modul | Kamera nur in einer eigenständigen App, keine Browser-Videocalls |
| **S4** | Intent-Handoff Linux → Android-App | Keine Navigation aus dem Linux-Adressbuch |

Dazu der **Übernacht-Test**: überlebt der Stack eine Nacht mit gesperrtem Bildschirm?
Scheitert er, ist das ein früher Warnschuss fürs Gesamtkonzept, kein Detail.

## Voraussetzungen

- Android-Telefon, Adreno 6xx/7xx bevorzugt (Turnip-Pfad)
- Termux samt Zusatz-Apps — siehe unten
- Einmalig `provision/provision.sh` vom PC, plus die dort genannten Handgriffe von Hand
- Etwa 6 GB freier Speicher (Debian-Rootfs, Plasma Mobile, Firefox)
- Geduld beim ersten Lauf: rund 1 GB Pakete

### Termux installieren

```bash
./provision/install-termux.sh
```

Lädt alle vier Apps von GitHub und installiert sie über die bestehende
adb-Verbindung — per WLAN genauso wie per Kabel. `provision.sh` bietet das von
selbst an, wenn Termux fehlt.

#### Warum das ein eigenes Skript verdient

Termux und seine Plugins teilen sich eine Android-UID (`sharedUserId=com.termux`).
Android verlangt, dass Apps mit gemeinsamer UID **mit demselben Schlüssel signiert**
sind — und F-Droid und GitHub signieren verschieden. Mischt man die Quellen, scheitert
die Installation mit `INSTALL_FAILED_SHARED_USER_INCOMPATIBLE`. Das ist der mit Abstand
häufigste Stolperstein beim Einrichten.

Das Skript wählt durchgängig **GitHub**, aus zwei Gründen:

- Termux:X11 gibt es dort in einer **sharedUid-Variante**. Die läuft in Termux'
  Prozessgruppe und erbt dessen Akku-Ausnahmen. Die normale Variante ist eine
  eigenständige Hintergrund-App, die Android drosselt — bei ROMs wie ColorOS der
  Unterschied zwischen „läuft über Nacht" und „war morgens weg".
- Eine Quelle, ein Schlüssel, keine Mischmasch-Fehler.

**Nicht aus dem Play Store** — die Fassung dort wird seit Jahren nicht mehr gepflegt.

Von Hand geht es natürlich auch, dann aber konsequent alles aus **einer** Quelle:

| App | GitHub | F-Droid |
|---|---|---|
| Termux | [Releases](https://github.com/termux/termux-app/releases/latest) | [f-droid.org](https://f-droid.org/packages/com.termux/) |
| Termux:API | [Releases](https://github.com/termux/termux-api/releases/latest) | [f-droid.org](https://f-droid.org/packages/com.termux.api/) |
| Termux:Boot | [Releases](https://github.com/termux/termux-boot/releases/latest) | [f-droid.org](https://f-droid.org/packages/com.termux.boot/) |
| Termux:X11 | [Releases](https://github.com/termux/termux-x11/releases) | — |

Bei F-Droid-Termux muss für Termux:X11 die **normale** Variante genommen werden
(`termux-x11-universal-debug.apk`), nicht die sharedUid-Fassung.

**Ein USB-Kabel wird nicht gebraucht.** Ab Android 11 geht die Ersteinrichtung über
WLAN — `provision.sh` fragt beim Start, ob per Kabel oder per Netz verbunden werden
soll, und übernimmt die Kopplung. Es kann die Skripte anschließend auch gleich aufs
Telefon übertragen, sodass dort keine Zugangsdaten für ein privates Repo auf einer
Bildschirmtastatur eingetippt werden müssen.

## Ablauf

```bash
# Einmalig, vom PC. Fragt selbst nach USB oder WLAN, installiert Termux
# und legt ein Startskript nach /sdcard/hpos-init.sh.
./provision/provision.sh

# Auf dem Telefon in Termux: git installieren und das Repo holen
bash /sdcard/hpos-init.sh
cd ~/hpos

bash spike/00-bootstrap-termux.sh

# Beweise in dieser Reihenfolge — S1 zuerst, weil er der wackligste ist
bash spike/01-s1-plasma-mobile.sh
bash spike/02-s2-mikrofon.sh
bash spike/03-s3-pipewire-kamera.sh
bash spike/04-s4-intent-handoff.sh
```

**Aktualisieren später** — kein PC nötig, kein erneutes Übertragen:

```bash
cd ~/hpos && git pull

# Falls das scheitert (Server liefert keine Pakete aus):
rm -rf ~/hpos && bash /sdcard/hpos-init.sh
```

Per adb kommt bewusst nur das Startskript aufs Telefon, nicht das Repo selbst.
Dadurch liegt dort eine echte Arbeitskopie statt einer Kopie.

Der zweite Befehl weicht auf den Archiv-Endpunkt aus, wenn `git clone` am Server
scheitert. Das Ergebnis ist dann ein Abzug ohne `.git` — `git pull` geht damit nicht
mehr, und jede Aktualisierung braucht denselben Befehl erneut. Sobald der Server
wieder Pakete liefert, stellt er auch die Arbeitskopie wieder her.

Jedes Skript fragt am Ende nach deiner Beurteilung und schreibt sie nach
`spike/out/ergebnisse.tsv`. Rohprotokolle liegen daneben in `spike/out/*.log`.

**Übertrage die Ergebnisse anschließend nach [`docs/spike-protokoll.md`](../docs/spike-protokoll.md).**
`spike/out/` ist absichtlich nicht im Repo — die Auswertung gehört dorthin, nicht die Rohdaten.

## Stellschrauben

| Variable | Vorgabe | Wofür |
|---|---|---|
| `HPOS_BREITE` / `HPOS_HOEHE` | `1080` / `2340` | Virtuelle Auflösung. Volle Panel-Auflösung ist für einen Telefon-Desktop zu viel Fläche |
| `HPOS_DAUER` | `6` | Sekunden Aufnahme in S2 |
| `HPOS_ZIEL` | Brandenburger Tor, Berlin | Navigationsziel in S4 |
| `HPOS_BEGLEIT_APP` | leer | Paketname einer Overlay-App, die in S4 vor der Navigation startet |

Beispiel:

```bash
HPOS_BEGLEIT_APP=de.blitzer HPOS_ZIEL="Kölner Dom" bash spike/04-s4-intent-handoff.sh
```

## Wenn etwas schiefgeht

**S1 startet nicht.** Das Skript probiert von selbst zwei Wege und fällt am Ende auf
XFCE zurück. Läuft XFCE, dann tragen X-Server und GPU-Pfad — der Fehlschlag liegt dann
eindeutig bei Plasma. Läuft auch XFCE nicht, liegt es an X-Server oder GPU.

**S2 erzeugt eine Datei ohne Ton.** Der häufigste und tückischste Fehlschlag. Das Skript
misst deshalb den Pegel. Ursache ist meist eine fehlende Mikrofonberechtigung für
Termux:API oder ein Termux-Build ohne `module-sles-source`.

**S3: Firefox sieht die Kamera nicht.** Prüfen, ob `xdg-desktop-portal-kde` läuft — die
GTK- und wlr-Portale können das Kamera-Portal nicht bedienen. In `about:config` muss
`media.webrtc.camera.allow-pipewire` auf `true` stehen; das Skript setzt es vorab.

**S4: kein Empfänger für den Intent.** Ohne installierte Navigations-App gibt es nichts,
was den `geo:`-Intent annehmen könnte. Das ist kein Fehler der Brücke.

## Aufräumen

```bash
pkill -f 'termux-x11|virgl_test_server|kwin_wayland|pipewire|bridge-mini.py'
pulseaudio --kill
```