Skip to content

Clarify Android docs for Kotlin build #311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cowboydaniel merged 1 commit into from
Nov 20, 2025
Merged

Clarify Android docs for Kotlin build #311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions android/ANDROID_ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -369,7 +369,7 @@ Full version control and team collaboration from your Android device.
- Android plugin system architecture
- Plugin discovery and loading
- Plugin marketplace UI
- Install plugins from APK or Python packages
- Install plugins from APK-delivered extensions
- 8 plugin types:
- Editor extensions
- Board packages
Expand Down Expand Up @@ -526,7 +526,7 @@ Some phases can run in parallel to reduce total timeline:

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| PySide6 performance issues on Android | Medium | High | Use Kivy as fallback; optimize rendering; profile early |
| Android API/Gradle regression risk | Medium | High | Track AGP releases early; pin known-good toolchains; run CI matrix |
| Arduino CLI ARM64 compatibility | Low | High | Cross-compile early; test on real devices; maintain alternatives |
| USB OTG reliability varies by device | High | Medium | Extensive device testing; clear compatibility list; Bluetooth fallback |
| Battery drain from background services | Medium | Medium | Aggressive power management; foreground services only when needed |
Expand Down
37 changes: 14 additions & 23 deletions android/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

## Overview

**Arduino IDE Modern for Android** brings the complete power of the desktop Arduino development environment to mobile devices. The mobile client is implemented natively in **Kotlin** with the standard Android toolchain so GitHub Actions (and your local Android Studio) can assemble installable APKs without any Python or Qt deployment steps.
**Arduino IDE Modern for Android** brings the complete power of the desktop Arduino development environment to mobile devices. The mobile client is implemented natively in **Kotlin** with the standard Android toolchain so GitHub Actions (and your local Android Studio) can assemble installable APKs without any external Python runtimes or Qt deployment steps.

Whether you're prototyping on the go, teaching Arduino in classrooms without computers, or debugging projects in the field, Arduino IDE Modern for Android provides a professional-grade development experience optimized for touchscreen interfaces.

Expand Down Expand Up @@ -112,7 +112,7 @@ All major desktop features adapted for mobile:
- **Debugging**: GDB/MI support via USB or WiFi debugging
- **Version Control**: Git integration with visual diff viewer
- **Collaboration**: Real-time multi-user editing sessions
- **Plugin System**: Installable extensions via APK or Python packages
- **Plugin System**: Installable extensions distributed as APK-delivered plugins
- **Code Quality**: Real-time analysis and suggestions
- **Examples Library**: 100+ pre-loaded Arduino examples

Expand Down Expand Up @@ -160,7 +160,7 @@ Coming Soon - Currently in Beta Testing

#### Prerequisites

The Android build is now driven by a committed Android Studio/Gradle project under `android/android-studio/`. **Everything is native Kotlin**—no Buildozer, `python-for-android`, or Qt deployment is required. Install the following:
The Android build is driven by a committed Android Studio/Gradle project under `android/android-studio/`. **Everything is native Kotlin**—no Buildozer, `python-for-android`, or Qt deployment is required. Install the following:

- Java 11 or 17 (for the Gradle Android plugin)
- Android SDK (API 34 recommended) and command-line tools
Expand Down Expand Up @@ -437,7 +437,7 @@ A: Depends on your device's USB OTG power output. Most phones provide 5V at 500m
### App Questions

**Q: Why is the app size so large?**
A: The app bundles Python runtime, Qt framework, and Arduino CLI. Total size ~150-200 MB to ensure offline functionality.
A: The app bundles Kotlin resources, Arduino CLI assets, and offline-friendly example content. Expect a footprint sized for on-device compilation while keeping native dependencies minimal.

**Q: Does it drain battery quickly?**
A: Normal editing uses minimal battery. Active serial monitoring or compilation increases usage. Enable battery saver mode in app settings.
Expand Down Expand Up @@ -491,30 +491,22 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.

### Technology Stack

- **Python 3.11**: Core application logic embedded via PySide6/Qt for Android
- **PySide6 + Qt for Android**: Qt 6 framework with the Qt Android deploy + Gradle toolchain
- **Kotlin + Jetpack**: Native Android application and UI layers
- **Material 3**: Modern theming and components
- **Gradle + Android SDK/NDK**: Packaging, signing, and APK generation
- **Arduino CLI ARM64**: Native ARM compilation binary
- **Kivy**: Alternative UI framework for some components
- **Arduino CLI ARM64**: Native ARM compilation binary for verification and upload workflows
- **View Binding**: Type-safe view access without synthetic imports

### App Structure

```
android/
├── README.md # This guide
├── BUILD_ANDROID.md # Additional build notes
├── BUILD_ANDROID.md # Android Studio build notes
├── ANDROID_ROADMAP.md # Feature roadmap
├── main.py # Android application entry point
├── ui_mobile/ # Mobile-optimized UI components
│ ├── touch_editor.py # Touch-friendly code editor
│ ├── mobile_toolbar.py # Compact toolbar for phones
│ └── gesture_handler.py # Touch gesture recognition
├── services_mobile/ # Android-specific services
│ ├── usb_service.py # USB OTG communication
│ ├── bluetooth_service.py # BLE and Classic Bluetooth
│ └── storage_service.py # Scoped storage handling
├── p4a-recipes/ # Legacy p4a recipes (not used by the Qt/Gradle toolchain)
└── android-studio/ # Committed Android Studio/Gradle project (open directly in IDE)
├── APK/ # Legacy placeholder artifacts (not the current Kotlin build)
├── android-studio/ # Committed Android Studio/Gradle project (open directly in IDE)
└── runtime/ # Legacy runtime staging (Qt/PySide6 placeholders; unused by Kotlin build)
```

---
Expand Down Expand Up @@ -544,9 +536,8 @@ This project is licensed under the MIT License, same as the desktop version. See
## Acknowledgments

- **Arduino Team**: For the Arduino platform and Arduino CLI
- **Qt for Android**: For excellent cross-platform mobile framework
- **PySide6 + Qt for Android**: For enabling Python apps on Android with Qt
- **Kivy Community**: For mobile UI components
- **Jetpack + Android Studio teams**: For the Kotlin-first Android tooling
- **Open-source library authors**: For the Android components that power the app
- **Beta Testers**: Everyone testing on their Android devices

---
Expand Down
5 changes: 2 additions & 3 deletions android/android-studio/app/proguard-rules.pro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,2 @@
# Keep PySide6 entry points and Qt bindings if minification is enabled.
#-keep class org.qtproject.** { *; }
#-keep class com.arduino.ide.** { *; }
# No custom ProGuard rules are required for the Kotlin-only build.
# Add keep rules here if future libraries require them.
10 changes: 5 additions & 5 deletions android/runtime/pyside6/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Bundled PySide6 runtime (placeholder)
# Legacy PySide6 runtime placeholders

Phase 0 commits a ready-to-import Android Studio project. The PySide6 runtime
assets are staged here so Gradle can package them without needing to rerun the
Qt deployment tooling. Replace these placeholders with the actual PySide6
Android deployment output when generating a production build.
The Android app ships as a Kotlin/Jetpack project and no longer embeds a Python
runtime or PySide6/Qt stack. This folder is left over from earlier prototypes
and is **not** referenced by the Gradle build. No action is required for modern
Kotlin builds.
15 changes: 5 additions & 10 deletions android/runtime/qt-runtime/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,6 @@
# Bundled Qt runtime
# Legacy Qt runtime placeholders

This folder is populated with the Qt for Android runtime expected by
`org.qtproject.qt.android.bindings.QtActivity`. The binaries are organized by
ABI (for example `arm64-v8a` and `armeabi-v7a`) so Gradle can pick them up as
both assets and native libraries during the sync step.

The placeholder `.so` files mirror the names produced by Qt's Android
deployment tooling. Replace them with the official Qt for Android runtime
artifacts for your targeted Qt release when producing a build destined for end
users.
The Android app is now a native **Kotlin** project and does not load Qt or
PySide6. This directory remains only as historical scaffolding from the prior
experiments and is **not** consumed by the current Gradle build. You can ignore
these placeholder `.so` files when building or debugging the Kotlin app.
Loading