UsbSerial

Additional

Language
Java
Version
6.1.0 (Jul 12, 2019)
Created
Mar 20, 2014
Updated
Sep 3, 2019
Owner
Felipe Herranz (felHR85)
Contributors
Arneball
gitter-badger
St├ęphane B. (StephaneBg)
Henry Addo (eyedol)
ge0rg
Felipe Herranz (felHR85)
autowp
josejuansanchez
jimcondon
eziosoft
Quang Nguyen (quangctkm9207)
rabidaudio
LeviticusMB
jaromor
rafaellehmkuhl
jkhan777
johngray1965
twsmith85
Show all (23)23
Activity
Badge
Generate
Download
Source code
APK file

Show card

UsbSerial

UsbSerial wiki available. Read it first

Getting startedUsbSerial video tutorialsDebugging over Wifi
Projects using UsbSerial
Multiple Serial ports
InputStream and OutputStream I/O
Synchronous api
Asynchronous api
Create UsbSerialDevice objects


Support UsbSerial

If UsbSerial helped you with your projects please consider donating a little sumOr consider buying DroidTerm Pro: A Usb serial port terminal using UsbSerial

Devices Supported

CP210X devices Default: 9600,8,1,None,flow off

CDC devices Default 115200,8,1,None,flow off

FTDI devices Default: 9600,8,1,None,flow off

PL2303 devices Default 9600,8,1,None,flow off

CH34x devices Default 9600,8,1,None,flow off

CP2130 SPI-USB

Known Issue

Due to a bug in Android itself, it's highly recommended to not use it with a device running Android 5.1.1 Lollipop. See issue #142 for more details.

How to use it?

Instantiate a new object of the UsbSerialDevice class

UsbDevice device;
UsbDeviceConnection usbConnection;
...
UsbSerialDevice serial = UsbSerialDevice.createUsbSerialDevice(device, usbConnection); 

Open the device and set it up as desired

serial.open();
serial.setBaudRate(115200);
serial.setDataBits(UsbSerialInterface.DATA_BITS_8);
serial.setParity(UsbSerialInterface.PARITY_ODD);
serial.setFlowControl(UsbSerialInterface.FLOW_CONTROL_OFF); 

If flow control is needed (currently only supported in CP201x and FTDI devices)

/**
Values:
    UsbSerialInterface.FLOW_CONTROL_OFF
    UsbSerialInterface.FLOW_CONTROL_RTS_CTS 
    UsbSerialInterface.FLOW_CONTROL_DSR_DTR
**/
serial.setFlowControl(UsbSerialInterface.FLOW_CONTROL_RTS_CTS);

There is no need to be polling if you want to perform a bulk transaction to a IN endpoint. Define a simply callback

private UsbSerialInterface.UsbReadCallback mCallback = new UsbSerialInterface.UsbReadCallback() {

  @Override
  public void onReceivedData(byte[] arg0) 
  {
   // Code here :)
  }
  
};

And pass a reference of it

serial.read(mCallback);

Changes in the CTS and DSR lines will be received in the same manner. Define a callback and pass a reference of it.

private UsbSerialInterface.UsbCTSCallback ctsCallback = new UsbSerialInterface.UsbCTSCallback() {
        @Override
        public void onCTSChanged(boolean state) {
           // Code here :)
        }
    };
    
private UsbSerialInterface.UsbDSRCallback dsrCallback = new UsbSerialInterface.UsbDSRCallback() {
        @Override
        public void onDSRChanged(boolean state) {
           // Code here :)
        }
    };
    
serial.getCTS(ctsCallback);
//serial.getDSR(dsrCallback);

Write something

serial.write("DATA".getBytes()); // Async-like operation now! :)

Raise the state of the RTS or DTR lines

serial.setRTS(true); // Raised
serial.setRTS(false); // Not Raised
serial.setDTR(true); // Raised
serial.setDTR(false); // Not Raised

Close the device:

serial.close();

I recommend using UsbSerial as shown above but if you want to perform write and read operations in synchronous way it is possible using these methods:

public boolean syncOpen();
public int syncWrite(byte[] buffer, int timeout)
public int syncRead(byte[] buffer, int timeout)
public void syncClose();

In Android usb api, when a usb device has been close it must be reopened

UsbDevice device;
...
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
manager.openDevice(UsbDevice device)

How to use the SPI interface (BETA)

Support for USB to SPI devices was added recently but it is still in beta. Although I tried to keep the api as close to standard UsbSerial api as possible, be aware because the beta nature of this feature this api may change in the future. Only CP2130 chipset is supported at the moment.

UsbSpiDevice spi = UsbSpiDevice.createUsbSerialDevice(device, connection);
spi.connectSPI();
spi.selectSlave(0);
spi.setClock(CP2130SpiDevice.CLOCK_3MHz);

Define the usual callback

private UsbSpiInterface.UsbMISOCallback misoCallback = new UsbSpiInterface.UsbMISOCallback()
    {
        @Override
        public int onReceivedData(byte[] data) {
             // Your code here :)
        }
    };
//...
spi.setMISOCallback(misoCallback);
spi.writeMOSI("Hola!".getBytes()); // Write "Hola!" to the selected slave through MOSI (MASTER OUTPUT SLAVE INPUT)
spi.readMISO(5); // Read 5 bytes from the MISO (MASTER INPUT SLAVE OUTPUT) line. Data will be received through UsbMISOCallback
spi.writeRead("Hola!".getBytes(), 15); // Write "Hola!" and read 15 bytes synchronously

Close the device when done

spi.closeSPI();

Gradle

Add the jitpack repo to your your project's build.gradle at the end of repositories

/build.gradle

allprojects {
 repositories {
  jcenter()
  maven { url "https://jitpack.io" }
 }
}

Then add the dependency to your module's build.gradle:

/app/build.gradle

implementation 'com.github.felHR85:UsbSerial:6.1.0'

TO-DO

  • RTS/CTS and DSR/DTR implementations for PL2303 and CDC