Android Build & Debug Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides comprehensive technical information for building, configuring, and debugging the tauri-plugin-serialplugin on the Android platform. It covers the architectural integration between Rust and Kotlin, environment setup, and troubleshooting procedures for USB serial communication.
The Android implementation leverages the usb-serial-for-android library to interface with hardware via the Android USB Host API. It provides a bridge between the Tauri frontend and the native Android USB stack, supporting various USB-to-Serial adapters including FTDI, CP210x, CH340, and PL2303.
Sources: android/README.md:5-7, debug.md:185-190
Architecture Overview
The plugin follows the standard Tauri mobile plugin architecture. The Rust side manages the plugin lifecycle and command dispatching, while the Kotlin side handles the low-level Android USB hardware interactions.
Component Relationship
The following diagram illustrates the data flow from the Tauri application through the native plugin layers to the hardware.
The architecture ensures that USB resources are properly managed according to the Android Activity lifecycle.
Sources: src/lib.rs:160-175, debug.md:40-55, android/README.md:9-13
Lifecycle Management
The SerialPlugin class registers Application.ActivityLifecycleCallbacks during its load() phase. This allows the plugin to automatically call SerialPortManager.cleanup() when the host Activity is destroyed, ensuring that USB ports are closed and executors are shut down to prevent memory leaks or stale native processes.
Sources: android/README.md:9-13, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:115-140
Building the Plugin
Prerequisites
To build the Android module, the following environment requirements must be met:
- Android Studio: Latest version.
- Android SDK: API level 24 or higher.
- JDK: Version 17 (recommended for Gradle stability).
- Kotlin: Version 1.8+.
- Gradle: Version 7.0+.
- Tauri CLI:
@tauri-apps/cliversion 2.0+.
Sources: android/BUILD_INSTRUCTIONS.md:5-10, android/README.md:31-35
Build Process
The build can be initiated either from the project root using the Tauri CLI or directly within the Android module using Gradle.
| Method | Command | Description |
|---|---|---|
| Tauri CLI | npm run tauri android build | Builds the entire project including the Android APK. |
| Verbose Build | npm run tauri android build --verbose | Provides detailed output for debugging build failures. |
| Gradle Library | ./gradlew assembleRelease | Generates the AAR library in build/outputs/aar/. |
| Clean Build | ./gradlew clean | Clears previous build artifacts. |
| Sources: debug.md:60-70, android/BUILD_INSTRUCTIONS.md:15-25 |
Native Configuration
AndroidManifest.xml
The plugin requires specific intent filters to detect USB devices. During the build process, build.rs automatically updates the AndroidManifest.xml to include the USB_DEVICE_ATTACHED action and links it to the device_filter.xml resource.
// Snippet from build.rs ensuring USB detection
tauri_plugin::mobile::update_android_manifest(
"SERIAL PLUGIN",
"activity",
r#"<intent-filter>
<action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
</intent-filter>
<meta-data
android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
android:resource="@xml/device_filter" />"#
.to_string(),
)
Sources: build.rs:55-68, examples/serialport-test/src-tauri/gen/android/app/src/main/AndroidManifest.xml:24-31
Parameter Handling and Types
The Kotlin layer features a flexible parameter handling system that accepts both String and Number types for configuration enums (DataBits, FlowControl, Parity, StopBits).
// Example of type flexibility in SerialPlugin.kt
val dataBits = when (args.dataBits) {
is String -> DataBits.valueOf(args.dataBits as String)
is Number -> DataBits.fromValue((args.dataBits as Number).toInt())
null -> DataBits.EIGHT
else -> throw IllegalArgumentException("Invalid data bits type")
}
Sources: debug.md:100-115, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:185-195
Debugging and Troubleshooting
Debugging Tools
Developers should use adb (Android Debug Bridge) to monitor plugin behavior and USB events.
- Plugin Logs: Filter by tags used in the Kotlin source.
adb logcat -v time | grep -E "SerialPlugin|SerialPortManager" - USB Device Status: Verify hardware connection.
adb shell lsusb - USB Permissions: Check if the system has granted access to the app.
adb shell dumpsys usb | grep -i "permission"
Sources: debug.md:75-90, android/BUILD_INSTRUCTIONS.md:40-45
Common Issues and Solutions
| Issue | Verification | Solution |
|---|---|---|
| Device not detected | Check if it appears in getAvailablePorts(). | Ensure device_filter.xml includes the device's VID/PID. |
| Permission Denied | Check adb logcat for permission requests. | Verify that the USB prompt was accepted on the device. |
| Type Mismatch | Build error: inferred type is Any but String expected. | Use the updated enums with fromValue methods (resolved in recent fixes). |
| Data Truncation | Monitor BufferedEmitter logs. | Adjust serialDataFlushIntervalMs (valid range 10-2000ms). |
| Sources: debug.md:135-155, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:265-270 |
Testing the Implementation
The Android module includes JVM-based unit tests that do not require an emulator for core logic verification. These tests cover:
- SerialModelsTest: Round-trip conversion for enums and default values.
- SerialByteAccumulatorTest: Thread-safe byte coalescing logic.
- SerialPluginConversionTest: Verification of
Map.toJSObjectandList.toJSArrayhelpers.
Sources: android/README.md:15-30
Summary
The Android implementation of the serial plugin provides a robust bridge to hardware using the usb-serial-for-android library. Key to its reliability is the tight integration with the Android Activity lifecycle and flexible type handling that allows the frontend to pass configuration in various formats. Debugging relies heavily on adb logcat and systematic verification of USB permissions and device filters.
Sources: android/README.md:9-13, debug.md:30-35, CHANGELOG.md:10-15