No Description
kai-morich 73d669c4dc remove FT231X also from device_filter.xml 1 week ago
.github/workflows Create build.yml 9 months ago
.idea modernize example app 4 months ago
gradle/wrapper make all SerialPort classes public 2 months ago
test support multi-port CDC devices 7 months ago
usbSerialExamples remove FT231X also from device_filter.xml 1 week ago
usbSerialForAndroid throw UnsupportedOperationException instead of returning false 1 week ago
.gitignore make all SerialPort classes public 2 months ago
CHANGELOG.txt Update build tools. 6 years ago
LICENSE.txt move from LGPL to MIT license (#244) 1 week ago
README.md move from LGPL to MIT license (#244) 1 week ago
build.gradle tests UsbDeviceConnection close behavior 3 weeks ago
gradle.properties modernize example app 4 months ago
gradlew build with jitpack 10 months ago
gradlew.bat build with jitpack 10 months ago
settings.gradle Convert to gradle. 6 years ago

README.md

Actions Status Jitpack Codacy codecov

usb-serial-for-android

This is a driver library for communication with Arduinos and other USB serial hardware on Android, using the Android USB Host Mode (OTG) available since Android 3.1 and working reliably since Android 4.2.

No root access, ADK, or special kernel drivers are required; all drivers are implemented in Java. You get a raw serial port with read(), write(), and other basic functions for use with your own protocols.

Quick Start

1. Add library to your project:

Add jitpack.io repository to your root build.gradle:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Add library to dependencies

dependencies {
    implementation 'com.github.mik3y:usb-serial-for-android:Tag'
}

2. If the app should be notified when a device is attached, add device_filter.xml to your project’s res/xml/ directory and configure in your AndroidManifest.xml.

<activity
    android:name="..."
    ...>
    <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" />
</activity>

3. Use it! Example code snippet:

open device:

    // Find all available drivers from attached devices.
    UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
    List<UsbSerialDriver> availableDrivers = UsbSerialProber.getDefaultProber().findAllDrivers(manager);
    if (availableDrivers.isEmpty()) {
        return;
    }

    // Open a connection to the first available driver.
    UsbSerialDriver driver = availableDrivers.get(0);
    UsbDeviceConnection connection = manager.openDevice(driver.getDevice());
    if (connection == null) {
        // add UsbManager.requestPermission(driver.getDevice(), ..) handling here
        return;
    }

    UsbSerialPort port = driver.getPorts().get(0); // Most devices have just one port (port 0)
    port.open(connection);
    port.setParameters(115200, 8, UsbSerialPort.STOPBITS_1, UsbSerialPort.PARITY_NONE);

then use direct read/write

    port.write(request, WRITE_WAIT_MILLIS);
    len = port.read(response, READ_WAIT_MILLIS);

or direct write + event driven read:

    usbIoManager = new SerialInputOutputManager(usbSerialPort, this);
    Executors.newSingleThreadExecutor().submit(usbIoManager);
    ...
    port.write("hello".getBytes(), WRITE_WAIT_MILLIS);
    
@Override
public void onNewData(byte[] data) {
    runOnUiThread(() -> { textView.append(new String(data)); });
}

and finally:

    port.close();

For a simple example, see UsbSerialExamples folder in this project.

For a more complete example with background service to stay connected while the app is not visible or rotating, see separate github project SimpleUsbTerminal.

Probing for Unrecognized Devices

Sometimes you may need to do a little extra work to support devices which usb-serial-for-android doesn’t (yet) know about -- but which you know to be compatible with one of the built-in drivers. This may be the case for a brand new device or for one using a custom VID/PID pair.

UsbSerialProber is a class to help you find and instantiate compatible UsbSerialDrivers from the tree of connected UsbDevices. Normally, you will use the default prober returned by UsbSerialProber.getDefaultProber(), which uses the built-in list of well-known VIDs and PIDs that are supported by our drivers.

To use your own set of rules, create and use a custom prober:

// Probe for our custom CDC devices, which use VID 0x1234
// and PIDS 0x0001 and 0x0002.
ProbeTable customTable = new ProbeTable();
customTable.addProduct(0x1234, 0x0001, CdcAcmSerialDriver.class);
customTable.addProduct(0x1234, 0x0002, CdcAcmSerialDriver.class);

UsbSerialProber prober = new UsbSerialProber(customTable);
List<UsbSerialDriver> drivers = prober.findAllDrivers(usbManager);
// ...

Of course, nothing requires you to use UsbSerialProber at all: you can instantiate driver classes directly if you know what you’re doing; just supply a compatible UsbDevice.

Compatible Devices

This library supports USB to serial converter chips:

  • FTDI FT232, FT2232, …
  • Prolific PL2303
  • Silabs CP2102, CP2105, …
  • Qinheng CH340, CH341A

and devices implementing the CDC/ACM protocol like

  • Arduino using ATmega32U4
  • Digispark using V-USB software USB
  • BBC micro:bit using ARM mbed DAPLink firmware

Help & Discussion

For common problems, see the Troubleshooting wiki page.

Are you using the library? Add your project to ProjectsUsingUsbSerialForAndroid.