If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mik3y/usb-serial-for-android shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 4w ago
• 11 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 87% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mik3y/usb-serial-for-android repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mik3y/usb-serial-for-android.

What it runs against: a local clone of mik3y/usb-serial-for-android — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mik3y/usb-serial-for-android | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 55 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mik3y/usb-serial-for-android. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mik3y/usb-serial-for-android.git
#   cd usb-serial-for-android
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mik3y/usb-serial-for-android and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mik3y/usb-serial-for-android(\\.git)?\\b" \\
  && ok "origin remote is mik3y/usb-serial-for-android" \\
  || miss "origin remote is not mik3y/usb-serial-for-android (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/CdcAcmSerialDriver.java" \\
  && ok "usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/CdcAcmSerialDriver.java" \\
  || miss "missing critical file: usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/CdcAcmSerialDriver.java"
test -f "usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/Ch34xSerialDriver.java" \\
  && ok "usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/Ch34xSerialDriver.java" \\
  || miss "missing critical file: usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/Ch34xSerialDriver.java"
test -f "usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/ChromeCcdSerialDriver.java" \\
  && ok "usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/ChromeCcdSerialDriver.java" \\
  || miss "missing critical file: usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/ChromeCcdSerialDriver.java"
test -f "usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/MainActivity.java" \\
  && ok "usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/MainActivity.java" \\
  || miss "missing critical file: usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/MainActivity.java"
test -f "usbSerialForAndroid/build.gradle" \\
  && ok "usbSerialForAndroid/build.gradle" \\
  || miss "missing critical file: usbSerialForAndroid/build.gradle"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 55 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~25d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mik3y/usb-serial-for-android"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A pure-Java Android USB Host Mode library that enables communication with serial USB devices (Arduinos, FTDI chips, CDC devices) without root access or custom kernel drivers. It wraps the Android USB API to expose standard read/write operations, supporting CDC, FTDI, CH34x, and other serial protocols through pluggable driver implementations. Single-module library structure: usbSerialLibrary/ contains core driver implementations (likely UsbSerialDriver, UsbSerialProber, and protocol-specific drivers for CDC/FTDI/CH34x). Example app in usbSerialExamples/ demonstrates DevicesFragment, TerminalFragment, and CustomProber. Test hardware fixtures in test/ (Arduino sketches, firmware) validate against real target devices.

Android app developers building IoT, robotics, or hardware-integration applications who need to communicate with microcontrollers and USB serial devices connected via OTG cable, without writing low-level USB protocol code.

Production-ready and actively maintained. The library has CI/CD via GitHub Actions (build.yml), coverage tracking (codecov badge), and release versioning through JitPack (currently at 3.9.0). Codebase is substantial (~380K lines Java) with test fixtures including Arduino sketches and Raspberry Pi Pico firmware, indicating real-world testing infrastructure.

Single-maintainer repository (mik3y) with moderate activity risk—worth checking last commit date and open issue count. Hardware integration libraries inherently have device-compatibility variance; the test/ directory shows efforts to mitigate this across Arduino Leonardo, Pico, and custom CDC variants. Dependency surface is small (Android SDK only), reducing supply-chain risk.

Active maintenance with support for multiple CDC variants (castrated CDC, multi-CDC on Arduino Leonardo), Raspberry Pi Pico TinyUSB firmware, and RFC2217 server extensions. CI pipeline runs on push (GitHub Actions). Version 3.9.0 released via JitPack suggests recent updates.

git clone https://github.com/mik3y/usb-serial-for-android.git && cd usb-serial-for-android && ./gradlew build

Daily commands: ./gradlew assembleDebug in usbSerialExamples/ to build example APK; ./gradlew test to run unit tests.

• usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/CdcAcmSerialDriver.java — Core CDC (Communications Device Class) driver implementation; essential for understanding the primary serial port abstraction for standard USB serial devices.
• usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/Ch34xSerialDriver.java — CH34x chipset driver (WinChipHead USB-to-Serial); critical for supporting non-CDC devices commonly used in Arduino and IoT projects.
• usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/ChromeCcdSerialDriver.java — Chrome OS CCD driver implementation; required for cross-platform USB serial support and understanding driver abstraction patterns.
• usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/MainActivity.java — Primary example entry point demonstrating device enumeration and serial port lifecycle management in an Android app.
• usbSerialForAndroid/build.gradle — Library build configuration; defines artifact versioning, dependencies, and Android SDK targets critical for library consumers.
• README.md — Project overview and API documentation; mandatory reading for understanding scope, supported devices, and basic integration patterns.
• settings.gradle — Gradle module configuration defining library and examples module structure; required for understanding build layout and subproject dependencies.

Add Support for a New USB Serial Chipset

1. Create a new driver class extending UsbSerialPort in usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/ (e.g., Cp210xSerialDriver.java) (usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/Ch34xSerialDriver.java)
2. Implement probe() static method to match against USB vendor/product IDs and getPortCount() for multi-port devices (usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/Ch34xSerialDriver.java)
3. Override setBaudRate(), setDataBits(), setStopBits(), setParity() with chipset-specific USB control requests (usbSerialForAndroid/src/main/java/com/hoho/android/usbserial/driver/Ch34xSerialDriver.java)
4. Register your driver in the example's CustomProber.java to make it discoverable in the app (usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/CustomProber.java)
5. Create test firmware in test/ directory (Arduino .ino or UF2) with corresponding device for integration testing (test/arduino_leonardo_bridge/arduino_leonardo_bridge.ino)

Integrate USB Serial into Your Android App

1. Add library dependency via JitPack to your app's build.gradle referencing the published artifact version (usbSerialExamples/build.gradle)
2. Copy the device discovery and enumeration logic from DevicesFragment.java, adapting the USB device filter (usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/DevicesFragment.java)
3. Implement your own port read/write loop using UsbSerialPort.read() and write() following the TerminalFragment.java pattern (usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/TerminalFragment.java)
4. Add USB_HOST permission and device_filter.xml intent-filter to AndroidManifest.xml matching your target devices (usbSerialExamples/src/main/AndroidManifest.xml)
5. Handle onResume()/onPause() lifecycle to open/close serial ports and configure baud rate via setParameters() (usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/MainActivity.java)

Debug Device Connection Issues

1. Check USB vendor/product IDs match a registered driver's probe() method using logcat output from device discovery (usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/DevicesFragment.java)
2. Verify AndroidManifest.xml includes proper USB_HOST permission and matching device_filter.xml intent (usbSerialExamples/src/main/res/xml/device_filter.xml)
3. Run a quick echo test using the example app's TerminalFragment to confirm the device responds to serial commands (usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/TerminalFragment.java)
4. If device still not detected, register it in CustomProber.java and run the integration tests against test firmware (usbSerialExamples/src/main/java/com/hoho/android/usbserial/examples/CustomProber.java)

• Android USB Host API (android.hardware.usb) — Enables raw USB communication without requiring root or custom kernel drivers; available

Android-specific: USB permissions must be declared in AndroidManifest.xml; device hotplug detection requires android.hardware.usb.action.USB_DEVICE_ATTACHED intent-filter and device_filter.xml metadata. USB OTG hardware may not be available on all Android devices (API 12+, but reliable only from API 16+). Driver probing is synchronous and can block if many devices are attached; custom Prober implementations may be needed for unlisted device types. Test fixtures expect specific Arduino/Pico hardware; running tests without devices will fail.

• Android USB Host Mode (OTG) — Core capability unlocking device communication without root; requires understanding USB descriptors, endpoints, and the Android USB API layer this library wraps
• CDC (Communications Device Class) / ACM (Abstract Control Model) — Standard USB protocol for serial devices; CdcAcmSerialDriver implements this—understanding CDC state machines (SET_LINE_CODING, SEND_BREAK) is essential for debugging device handshakes
• USB Descriptors and Endpoints — Drivers parse device descriptors to identify interfaces and bulk/interrupt endpoints; knowledge of bInterfaceClass, bEndpointAddress is required to add new device support
• Strategy Pattern (Driver Probing) — UsbSerialProber and protocol-specific drivers (FtdiSerialDriver, Ch34xSerialDriver) use this pattern; new device support is added by implementing the strategy interface
• FTDI FT232 Protocol — Widely-used USB-to-UART bridge chip; FtdiSerialDriver implements proprietary command set for baud rate, flow control—understanding vendor-specific USB control requests is needed for FTDI device support
• Intent Filters and Metadata (AndroidManifest) — android.hardware.usb.action.USB_DEVICE_ATTACHED filter with device_filter.xml metadata enables automatic app launch on device hotplug; missing config prevents detection
• Bulk Transfer Timeouts and Flow Control — Serial devices require configurable read/write timeouts and backpressure handling (RTS/CTS, XON/XOFF); improper timeout tuning causes blocking or data loss

• felHR85/UsbSerial — Alternative pure-Java USB serial library for Android; same problem domain, can inform API design trade-offs
• arduino/arduino-core-nrf52 — Official Arduino BSP; integrates with this library on Android and defines CDC serial protocol expectations
• tinyusb/tinyusb — Embedded USB stack used in Raspberry Pi Pico firmware (test/pi_pico/) to validate cross-platform CDC interoperability
• google/android-usb-accessory-example — Official Android USB Host Mode sample; reference implementation for AndroidManifest intent-filter and UsbManager patterns
• mik3y/slugline — Historical predecessor by same maintainer; usb-serial-for-android evolved from this older implementation

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for UsbSerialDriver implementations

The repo contains multiple device-specific drivers (CDC, FTDI, Arduino, etc.) but the test/ directory only has Arduino firmware examples, not Java/Kotlin unit tests. Adding comprehensive unit tests for core driver implementations would improve code reliability and make contributions safer. This is critical for a driver library where bugs can cause serial communication failures.

• [ ] Create test/ subdirectory structure mirroring usbSerialExamples/src/main/java (e.g., test/java/com/hoho/android/usbserial/driver/)
• [ ] Add unit tests for CdcAcmSerialDriver covering open(), close(), read(), write() with mocked UsbDevice/UsbDeviceConnection
• [ ] Add unit tests for FtdiSerialDriver covering device-specific baud rate settings and control signal handling
• [ ] Set up JUnit4 or Mockito dependencies in build.gradle and verify CI runs tests via GitHub Actions

Create RFC 2217 (Telnet Serial) server implementation

The test/ directory contains test/rfc2217_server.diff suggesting RFC 2217 Telnet serial protocol support was considered but never merged. This would enable remote serial connections over network, significantly expanding use cases (remote Arduino access, networked device labs). The .diff file indicates the work is partially done and just needs modernization.

• [ ] Review test/rfc2217_server.diff and extract the core RFC2217SerialDriver class implementation
• [ ] Create usbSerialDriver/src/main/java/com/hoho/android/usbserial/driver/Rfc2217SerialDriver.java with proper error handling
• [ ] Add unit tests for RFC 2217 command parsing (COM_PORT_OPTION, NOTIFY_LINESTATE) in test/java/
• [ ] Update README.md with RFC 2217 driver documentation and example usage

Add multi-port CDC device support test and documentation

The test/arduino_leonardo_bridge_multi_cdc/ firmware exists for testing dual CDC ports, but there's no corresponding test in the test suite or example code showing how apps should handle multiple serial ports from a single USB device. This would prevent developers from misusing the library with multi-port devices.

• [ ] Create test/java/com/hoho/android/usbserial/driver/CdcAcmSerialDriverMultiPortTest.java to verify UsbSerialPort enumeration from devices with multiple CDC interfaces
• [ ] Add integration test documentation in test/arduino_leonardo_bridge_multi_cdc/README.md with step-by-step setup and verification instructions
• [ ] Create usbSerialExamples example showing MultiPortDeviceFragment.java that lists and independently manages multiple ports from single device
• [ ] Update main README.md with 'Multi-Port Devices' section referencing this example

• Add unit tests for UsbSerialProber.findAllDrivers() with mock UsbManager objects—currently only integration-tested via hardware in test/
• Document the CustomProber example in README with step-by-step for adding support for a new USB serial device (e.g., custom VID/PID)—only code example exists in usbSerialExamples/
• Extract common CDC driver logic from CdcAcmSerialDriver and the castrated/multi-CDC variants in test/ into a shared base class to reduce duplication and improve maintainability

The USB Serial for Android library maintains a moderate security posture. Primary concerns center on the inherent attack surface of USB driver development (protocol parsing, malformed input handling), missing dependency management strategies, and lack of visible security infrastructure documentation. The codebase uses relatively up-to-date build tools and appears well-maintained, but would benefit from formal security testing (fuzzing), input validation hardening, and explicit dependency management. Test fixtures require audit to ensure no credential leakage. Overall, the project requires standard security practices for system-level drivers but shows no critical misconfigurations or obvious exploitable vulnerabilities in the visible structure.

• High · Outdated Gradle Build Tools — build.gradle (buildscript dependencies). The project uses Gradle 8.9.1, which may contain known vulnerabilities. While this is a relatively recent version, regular updates should be monitored for security patches and bug fixes. Fix: Regularly update gradle and com.android.tools.build:gradle to the latest stable version. Monitor security advisories for Android build tools.
• Medium · Missing Dependency Version Pinning — build.gradle (allprojects repositories and dependencies). The build.gradle file uses implicit version resolution for repositories (mavenCentral, google) without explicit dependency version management strategy. This could lead to transitive dependency vulnerabilities if vulnerable versions are pulled in. Fix: Implement dependency locking with gradle.lockfile or use explicit version constraints for all dependencies. Consider using a bill-of-materials (BOM) or dependency management plugin to control transitive dependencies.
• Medium · USB Serial Driver Library Attack Surface — usbSerialForAndroid/src (entire driver implementation). The library directly handles USB communication and serial data parsing. USB drivers are historically high-risk components for malformed input attacks, buffer overflows, and protocol violations. The file structure suggests multiple device type handlers (CDC, FTDI, Arduino) which increases complexity. Fix: Implement strict input validation for all USB data received. Use fuzzing and security testing on protocol parsers. Ensure proper bounds checking on all buffer operations. Consider security code review focusing on USB descriptor parsing and device enumeration logic.
• Medium · Test Fixtures May Contain Sensitive Information — test/ directory (arduino_leonardo_bridge, pi_pico, rfc2217_server.diff). Test directories contain Arduino firmware and device configuration files. If these are based on real deployments or contain hardcoded credentials/tokens, they could expose sensitive information. Fix: Audit all test fixtures and example code to ensure no hardcoded credentials, API keys, or sensitive configuration. Use generic/placeholder values in test files. Add pre-commit hooks to prevent committing secrets.
• Low · ProGuard Rules Not Fully Reviewed — usbSerialForAndroid/proguard-rules.pro. The presence of proguard-rules.pro suggests obfuscation is configured, but the rules file content is not visible for review. Improper ProGuard configuration could expose sensitive APIs or leave debugging information. Fix: Review ProGuard rules to ensure sensitive classes/methods are properly obfuscated. Verify that only necessary debugging information is retained. Keep rules updated with new API changes.
• Low · CI/CD Pipeline Configuration Not Visible — .github/workflows/build.yml. GitHub Actions workflow file (.github/workflows/build.yml) is listed but content not provided. Without reviewing the CI/CD pipeline, potential secrets exposure, insecure artifact handling, or privilege escalation risks cannot be fully assessed. Fix: Review CI/CD workflow to ensure: (1) No secrets passed as plain text, (2) Build artifacts signed and verified, (3) Proper access controls on deployment steps, (4) No dangerous checkout permissions (pull_request_target), (5) Code signing configured for releases.
• Low · Missing Security Policy and Vulnerability Disclosure — Repository root. No SECURITY.md or vulnerability disclosure policy is visible in the repository structure, making it unclear how security issues should be reported. Fix: Create SECURITY.md file with responsible disclosure policy. Provide clear instructions for reporting vulnerabilities privately before public disclosure.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.