Android Setup & Manifest
Relevant source files
The following files were used as context for generating this wiki page:
The Android implementation of the Tauri Serial Plugin enables USB serial communication by leveraging the Android USB Host API and the usb-serial-for-android library. This setup requires specific manifest configurations to grant the application permission to act as a USB host and to automatically detect connected hardware via device filters.
The scope of this setup includes defining hardware requirements, managing USB permissions, and configuring the build environment to package the Kotlin-based plugin as an AAR library. Proper manifest configuration is critical for the plugin to receive USB_DEVICE_ATTACHED intents and to manage the lifecycle of serial connections relative to the host Activity.
Sources: android/AndroidManifest.xml, android/BUILD_INSTRUCTIONS.md, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:80-90
Build Environment & Prerequisites
Setting up the Android environment requires specific SDK versions and tooling to ensure compatibility with the Tauri mobile runtime and the underlying serial libraries.
Requirements
The plugin requires Android SDK API 24+ and Kotlin 1.8+. The build process is managed via Gradle 7.0+ and can be executed either through Android Studio or via the command line using the provided Gradle wrapper.
Sources: android/BUILD_INSTRUCTIONS.md:5-10
Build Commands
| Action | Command |
| | |
| Environment Setup | ./gradlew clean |
| Build Release AAR | ./gradlew assembleRelease |
| Build Debug AAR | ./gradlew assembleDebug |
| Plugin Compilation | ./gradlew :tauri-plugin-serialplugin:compileReleaseKotlin |
Sources: android/BUILD_INSTRUCTIONS.md:14-25, debug.md:55-60
Manifest Configuration
The AndroidManifest.xml is the core configuration file that defines the app's interaction with Android's USB subsystem.
Permissions and Features
The plugin explicitly requires the android.hardware.usb.host feature. This ensures the application is only available on devices capable of acting as a USB host. Additionally, permissions for USB interaction and storage (for older Android versions) are defined.
<!-- USB permissions and features -->
<uses-feature android:name="android.hardware.usb.host" android:required="true" />
<uses-permission android:name="android.permission.USB_PERMISSION" />
<!-- Storage for legacy support -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
Sources: android/src/main/AndroidManifest.xml:7-14
Intent Filters and Metadata
To enable automatic detection of USB devices when they are plugged in, the manifest includes a metadata entry pointing to a device_filter.xml. This allows the Android OS to identify the app as a candidate for handling the specific USB device based on Vendor ID (VID) or Product ID (PID).
Sources: android/src/main/AndroidManifest.xml:18-21, build.rs:55-65
USB Device Filtering
The device_filter.xml file specifies which USB devices the plugin is interested in. This prevents the application from being prompted for every generic USB device connected to the Android host.
Filtering Logic
The filter supports matching by vendor-id, product-id, class, subclass, and protocol.
The logic relies on the resource file defined in res/xml/device_filter.xml.
Sources: android/src/main/res/xml/device_filter.xml, android/BUILD_INSTRUCTIONS.md:50-55
Build-time Manifest Automation
The project uses a Rust-based build script (build.rs) to automate the injection of serial-specific manifest entries into the final Android application.
Manifest Update Flow
The tauri_plugin::mobile::update_android_manifest function is used during the build process to insert the necessary <intent-filter> and <meta-data> tags into the generated Android project's MainActivity.
Sources: build.rs:50-65
Plugin Initialization & Lifecycle
The SerialPlugin class manages the transition between the Tauri/Rust environment and the Android Activity lifecycle.
Lifecycle Management
The plugin registers Application.ActivityLifecycleCallbacks to ensure that USB resources are properly cleaned up when the host Activity is destroyed. This prevents memory leaks and stale file descriptors.
private fun registerActivityDestroyCleanup() {
val app = activity.application
val cb = object : Application.ActivityLifecycleCallbacks {
override fun onActivityDestroyed(destroyed: Activity) {
if (destroyed !== activity) return
serialPortManager.cleanup() // Close ports and release threads
}
// ... other overrides
}
app.registerActivityLifecycleCallbacks(cb)
}
Sources: android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:105-130
Hardware Acceleration
The manifest explicitly enables hardware acceleration to ensure smooth performance of the WebView when interacting with the serial plugin's asynchronous data streams.
Sources: android/src/main/AndroidManifest.xml:4
Summary of Android Components
| Component | Path | Purpose |
|---|---|---|
| Main Plugin | SerialPlugin.kt | Bridges Tauri commands to Android USB logic. |
| Port Manager | SerialPortManager.kt | Handles low-level USB enumeration and IO. |
| Device Filter | device_filter.xml | Defines target VID/PID for auto-detection. |
| Build Script | build.rs | Automates manifest modification for the host app. |
Sources: android/BUILD_INSTRUCTIONS.md:45-55, debug.md:120-130