Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

feat(ui): make USB passthrough an opt-in like Downloads sharing

ExTv0a068d081d80
diff --git a/README.md b/README.md
index 3b09d2b..2f4f99e 100644
--- a/README.md
+++ b/README.md
@@ -104,7 +104,7 @@ Everything below is editable from **Settings**:
- **CPU cores:** 1 · 2 · 4 · 6 · 8
- **Persistent storage:** 2 GB to 64 GB (chosen at first setup; reset to change)
- **Downloads folder sharing:** toggle on/off; mounted inside the VM at `/mnt/downloads` (virtio-9p on QEMU, AVF `SharedPath` where the backend supports it)
-- **USB passthrough:** toggle on/off; hot-plugs attached USB devices into the running VM (QEMU backend only — adds a USB controller at boot, so restart to apply)
+- **USB passthrough:** opt-in toggle in Settings and at first-run setup (alongside Downloads sharing); hot-plugs attached USB devices into the running VM (QEMU backend only — adds a USB controller at boot, so set it while the VM is stopped)
- **SSH** (Dropbear on host port `9922`): toggle on/off; reachable from the LAN as `ssh root@<phone-ip> -p 9922` once the VM is Ready
- **Port forwards:** add/remove host ↔ guest TCP/UDP rules live, no VM restart
- **Advanced QEMU args:** full `-cpu` / `-accel` / RNG / device line, editable
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsScreen.kt b/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsScreen.kt
index bd198cd..da40eb2 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsScreen.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsScreen.kt
@@ -93,6 +93,7 @@ fun SettingsScreen(
val portForwardRules by viewModel.portForwardRules.collectAsStateWithLifecycle()
val vmState by viewModel.vmState.collectAsStateWithLifecycle()
val exportError by viewModel.exportError.collectAsStateWithLifecycle()
+ val usbPassthrough by viewModel.usbPassthroughEnabled.collectAsStateWithLifecycle()
var advancedExpanded by remember { mutableStateOf(false) }
var showAddDialog by remember { mutableStateOf(false) }
@@ -106,6 +107,7 @@ fun SettingsScreen(
// Memoize: both values are constant for the process lifetime / until a backend
// swap, so there's no point re-running reflection on every recomposition.
val isDownloadsShareAvailable = remember { viewModel.isDownloadsShareAvailable() }
+ val isUsbPassthroughAvailable = remember { viewModel.isUsbPassthroughAvailable() }
val activeBackendId = remember { viewModel.activeBackendId() }
// Re-sync the persisted storageAccessEnabled flag against the real OS grant on
@@ -244,6 +246,13 @@ fun SettingsScreen(
activeBackendId = activeBackendId,
onToggle = { viewModel.setStorageAccessEnabled(it) },
)
+ UsbPassthroughRow(
+ enabled = usbPassthrough,
+ vmNotRunning = vmNotRunning,
+ available = isUsbPassthroughAvailable,
+ activeBackendId = activeBackendId,
+ onToggle = { viewModel.setUsbPassthroughEnabled(it) },
+ )
Spacer(Modifier.height(PodroidTokens.Spacing.MD))
PodroidDestructiveButton(
text = "Reset VM (deletes all data)",
@@ -294,31 +303,6 @@ fun SettingsScreen(
onKernelReset = viewModel::resetKernelExtraCmdline,
enabled = vmNotRunning,
)
-
- PodroidSectionLabel("USB passthrough")
- val usbPassthrough by viewModel.usbPassthroughEnabled.collectAsStateWithLifecycle()
- PodroidListRow(
- label = "USB device passthrough",
- rightSlot = {
- PodroidSwitch(
- checked = usbPassthrough,
- onCheckedChange = { viewModel.setUsbPassthroughEnabled(it) },
- enabled = vmNotRunning,
- )
- },
- )
- Text(
- text = "Hot-plugs external USB devices into the running VM. Each device " +
- "asks for permission when attached. Adds a USB controller at boot — " +
- "restart the VM to apply. Requires a libusb-enabled QEMU build.",
- style = MaterialTheme.typography.bodySmall,
- color = MaterialTheme.colorScheme.onSurfaceVariant,
- modifier = Modifier.padding(
- start = PodroidTokens.Spacing.MD,
- end = PodroidTokens.Spacing.MD,
- bottom = PodroidTokens.Spacing.SM,
- ),
- )
}
// ── ABOUT ─────────────────────────────────────────────
@@ -624,6 +608,50 @@ private fun DownloadsSharingRow(
}
}
+/**
+ * Mirrors [DownloadsSharingRow] for USB device passthrough. Permission is asked
+ * per-device at attach time (no upfront system grant), so this is just an opt-in
+ * switch. Adds a USB controller to the QEMU launch line, so it's only editable
+ * while the VM is stopped. Disabled on AVF: that backend has no QMP channel and
+ * cannot pass a device through.
+ */
+@Composable
+private fun UsbPassthroughRow(
+ enabled: Boolean,
+ vmNotRunning: Boolean,
+ available: Boolean,
+ activeBackendId: String,
+ onToggle: (Boolean) -> Unit,
+) {
+ PodroidListRow(
+ label = "USB passthrough",
+ rightSlot = {
+ PodroidSwitch(
+ checked = enabled && available,
+ onCheckedChange = onToggle,
+ enabled = vmNotRunning && available,
+ )
+ },
+ )
+ Text(
+ text = if (available) {
+ "Hot-plugs external USB devices (Wi-Fi, storage, serial, etc.) into the " +
+ "VM. Each device asks for permission when attached. Adds a USB " +
+ "controller at boot, so restart the VM to apply."
+ } else {
+ "Not available on the $activeBackendId backend: USB passthrough rides " +
+ "QEMU's QMP control socket, which the AVF backend doesn't provide."
+ },
+ style = MaterialTheme.typography.bodySmall,
+ color = MaterialTheme.colorScheme.onSurfaceVariant,
+ modifier = Modifier.padding(
+ start = PodroidTokens.Spacing.MD,
+ end = PodroidTokens.Spacing.MD,
+ bottom = PodroidTokens.Spacing.SM,
+ ),
+ )
+}
+
@Composable
private fun AdvancedFieldsBlock(
qemuExtraArgs: String,
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsViewModel.kt b/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsViewModel.kt
index d22b2b4..535b4d0 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsViewModel.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/settings/SettingsViewModel.kt
@@ -237,6 +237,13 @@ class SettingsViewModel @Inject constructor(
else -> true
}
+ /**
+ * USB passthrough rides the QEMU QMP control socket (add-fd + device_add
+ * usb-host); the AVF backend has no QMP channel, so it can never pass a
+ * device through. QEMU-only.
+ */
+ fun isUsbPassthroughAvailable(): Boolean = engine.backendId == "qemu"
+
private val _exportError = MutableStateFlow<String?>(null)
/** One-shot export failure message; clear after showing with [clearExportError]. */
val exportError: StateFlow<String?> = _exportError.asStateFlow()
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupScreen.kt b/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupScreen.kt
index 321c176..f6ffb8f 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupScreen.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupScreen.kt
@@ -82,8 +82,10 @@ fun SetupScreen(
var selectedGb by rememberSaveable { mutableIntStateOf(DEFAULT_STORAGE_GB) }
var sshEnabled by rememberSaveable { mutableStateOf(true) }
var storageAccessEnabled by rememberSaveable { mutableStateOf(false) }
+ var usbPassthroughEnabled by rememberSaveable { mutableStateOf(false) }
+ val usbPassthroughAvailable = remember { viewModel.usbPassthroughAvailable() }
val setupComplete by viewModel.setupComplete.collectAsStateWithLifecycle()
- val pagerState = rememberPagerState(pageCount = { 3 })
+ val pagerState = rememberPagerState(pageCount = { 4 })
val scope = rememberCoroutineScope()
// Request the notification permission BEFORE navigating away; using
@@ -131,7 +133,7 @@ fun SetupScreen(
) {
// Step progress bar
LinearProgressIndicator(
- progress = { (pagerState.currentPage + 1) / 3f },
+ progress = { (pagerState.currentPage + 1) / 4f },
modifier = Modifier.fillMaxWidth(),
trackColor = MaterialTheme.colorScheme.surfaceVariant,
)
@@ -184,11 +186,20 @@ fun SetupScreen(
}
},
onBack = { scope.launch { pagerState.animateScrollToPage(1) } },
+ onNext = { scope.launch { pagerState.animateScrollToPage(3) } },
+ )
+ 3 -> UsbPassthroughPage(
+ windowSizeClass = windowSizeClass,
+ usbPassthroughEnabled = usbPassthroughEnabled,
+ available = usbPassthroughAvailable,
+ onUsbPassthroughToggle = { usbPassthroughEnabled = it },
+ onBack = { scope.launch { pagerState.animateScrollToPage(2) } },
onGetStarted = {
viewModel.completeSetup(
storageSizeGb = selectedGb,
sshEnabled = sshEnabled,
storageAccessEnabled = storageAccessEnabled,
+ usbPassthroughEnabled = usbPassthroughEnabled && usbPassthroughAvailable,
)
},
)
@@ -203,7 +214,7 @@ fun SetupScreen(
horizontalArrangement = Arrangement.Center,
verticalAlignment = Alignment.CenterVertically,
) {
- repeat(3) { index ->
+ repeat(4) { index ->
val isSelected = pagerState.currentPage == index
val dotWidth by animateDpAsState(
targetValue = if (isSelected) 24.dp else 8.dp,
@@ -387,17 +398,17 @@ private fun StorageAccessPage(
onStorageAccessToggle: (Boolean) -> Unit,
onOpenStorageAccessSettings: () -> Unit,
onBack: () -> Unit,
- onGetStarted: () -> Unit,
+ onNext: () -> Unit,
) {
val canManageAllFiles = Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
val hasStoragePermission = !canManageAllFiles || Environment.isExternalStorageManager()
SetupPageLayout(
windowSizeClass = windowSizeClass,
- stepLabel = "Step 3 of 3",
+ stepLabel = "Step 3 of 4",
title = "Downloads Sharing",
description = "Optional. Mount your Android Downloads folder into the VM over virtio-9p.",
- bottomBar = { SetupNavBar(onBack = onBack, onNext = onGetStarted, nextLabel = "Get Started") },
+ bottomBar = { SetupNavBar(onBack = onBack, onNext = onNext, nextLabel = "Continue") },
) {
PodroidSectionLabel("Sharing")
PodroidListRow(
@@ -425,6 +436,53 @@ private fun StorageAccessPage(
}
}
+// ── Page 4: USB passthrough ───────────────────────────────────────────────────
+
+@Composable
+private fun UsbPassthroughPage(
+ windowSizeClass: WindowSizeClass,
+ usbPassthroughEnabled: Boolean,
+ available: Boolean,
+ onUsbPassthroughToggle: (Boolean) -> Unit,
+ onBack: () -> Unit,
+ onGetStarted: () -> Unit,
+) {
+ SetupPageLayout(
+ windowSizeClass = windowSizeClass,
+ stepLabel = "Step 4 of 4",
+ title = "USB Passthrough",
+ description = "Optional. Hot-plug external USB devices (Wi-Fi, storage, serial, etc.) " +
+ "into the VM at runtime.",
+ bottomBar = { SetupNavBar(onBack = onBack, onNext = onGetStarted, nextLabel = "Get Started") },
+ ) {
+ PodroidSectionLabel("Devices")
+ PodroidListRow(
+ label = "Enable USB passthrough",
+ rightSlot = {
+ PodroidSwitch(
+ checked = usbPassthroughEnabled && available,
+ onCheckedChange = onUsbPassthroughToggle,
+ enabled = available,
+ )
+ },
+ )
+ Spacer(Modifier.height(PodroidTokens.Spacing.SM))
+ Text(
+ text = if (available) {
+ "Each device asks for permission when you plug it in. Adds a USB " +
+ "controller to the VM, which costs a little emulation overhead, " +
+ "so leave it off if you don't need it. You can change this later in Settings."
+ } else {
+ "Not available on this backend: USB passthrough needs QEMU's control " +
+ "socket, which the AVF backend doesn't provide. You can change this " +
+ "later in Settings."
+ },
+ style = MaterialTheme.typography.bodyMedium,
+ color = MaterialTheme.colorScheme.onSurfaceVariant,
+ )
+ }
+}
+
// ── Setup bottom bars ─────────────────────────────────────────────────────────
@Composable
diff --git a/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupViewModel.kt b/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupViewModel.kt
index 7371b2f..9037652 100644
--- a/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupViewModel.kt
+++ b/app/src/main/java/com/excp/podroid/ui/screens/setup/SetupViewModel.kt
@@ -5,6 +5,7 @@ import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.excp.podroid.data.repository.SettingsRepository
import com.excp.podroid.data.repository.dataStore
+import com.excp.podroid.engine.VmEngine
import android.content.Context
import dagger.hilt.android.lifecycle.HiltViewModel
import dagger.hilt.android.qualifiers.ApplicationContext
@@ -17,21 +18,37 @@ import javax.inject.Inject
@HiltViewModel
class SetupViewModel @Inject constructor(
@ApplicationContext private val context: Context,
+ private val engine: VmEngine,
) : ViewModel() {
private val _setupComplete = MutableStateFlow(false)
val setupComplete: StateFlow<Boolean> = _setupComplete.asStateFlow()
+ /**
+ * USB passthrough is QEMU-only (it rides the QMP control socket the AVF
+ * backend lacks). Reading backendId here is cheap and side-effect-free.
+ * During first-run the engine pick may still be settling on its QEMU seed,
+ * so on an AVF device this can briefly read available; the choice is inert
+ * on AVF anyway (no QMP, no qemu-xhci) and Settings shows the correct gate.
+ */
+ fun usbPassthroughAvailable(): Boolean = engine.backendId == "qemu"
+
/**
* Persists all setup choices in a single DataStore transaction so a process
* kill mid-write can't leave the app in a half-completed setup state.
*/
- fun completeSetup(storageSizeGb: Int, sshEnabled: Boolean, storageAccessEnabled: Boolean) {
+ fun completeSetup(
+ storageSizeGb: Int,
+ sshEnabled: Boolean,
+ storageAccessEnabled: Boolean,
+ usbPassthroughEnabled: Boolean,
+ ) {
viewModelScope.launch {
context.dataStore.edit { prefs ->
prefs[SettingsRepository.KEY_STORAGE_GB] = storageSizeGb
prefs[SettingsRepository.KEY_SSH_ENABLED] = sshEnabled
prefs[SettingsRepository.KEY_STORAGE_ACCESS_ENABLED] = storageAccessEnabled
+ prefs[SettingsRepository.KEY_USB_PASSTHROUGH_ENABLED] = usbPassthroughEnabled
prefs[SettingsRepository.KEY_SETUP_DONE] = true
}
_setupComplete.value = true