Android Programming Press on the image to return to the main documentation page.

UsbSerial

This library is based on the usb-serial-for-android library with support added
for Prolific PL2303 and Android Accessory (ADK) devices.
https://code.google.com/p/usb-serial-for-android/

Unlike version 1.0 of this library it does not need a separate usb-serial-for-android jar file as this
is now incopoprated into the library.

usb-serial-for-android and therefore also this library is licensed under the GNU Lesser General Public License v3.
http://www.gnu.org/licenses/lgpl.html
Copies of both the General Public License and Lesser General Public License are in the provided archive.

List of types:

UsbSerial

UsbSerial

UsbSerial supports various popular chips that support serial emulation over a USB connection
and provides a common API to communicate with them all.
The devices recognised by this library include:

Various Prolific PL2303 based USB serial devices.

Various FTDI FT232 based devices including Arduinos that use FTDI USB serial chips.
The FTDI "status byte" bug on reading input in version 1.0 of this library is fixed.

Various Arduinos that use an Atmel 8U2 or 16U2 programmed as a CDC ACM Virtual Comport.
USB versions of the Roboclaw controller which act as an CDC ACM Virtual Comport in mode 15.

Silicon Labs CP2102 and possibly others of that series of USB to UART Bridges.

The above chips are all slave USB devices and need host capabilities in the Android device.
This usually implies that an On The Go (OTG) or "Camera" cable is needed to switch the
Android hardware into host mode. Note that access to the modem control signals is not implemented for
any of the above devices owing to the lack of technical data about the actual chips which the manufacturers
deem proprietary information made available only to their OEM customers.

Supported devices are recongised by the combination of their VendorID and Product ID, a list of which is
precomiled into the library. A device that is compatible with one of the four device drivers listed above
but that is not recognised may be supported using the SetCustomDevice method. this is most likely to be useful
for devices implementing the USB CDC (Communications Device Class) ACM (Abstract Control Model) which is a
vendor-independent publicly documented protocol.

For convenience this library also supports Android Accessory devices that implement the AOA protocol
(Android Open Accessory) using the same common API as the slave devices listed above.

Accessories are host mode devices and can connect directly to an Android device using the same cable
that is used to connect the Android device to a PC for program development or direct file transfer.

There is a bug in the Android USB Accessory handling when trying to reconnect to a disconnected Accessory.
In order to reliably connect to an Accessory with your program it is necessary to ensure that
the process of any previous instance of your program that communicated with the Arduino has been killed.
This is the reason why there is an Exit button that calls ExitApplication in the UsbSerial demo program
that you should use to kill the program. It is also necessary before restarting the program
or downloading and running a modified version again to physically disconnect and reconnect the Accessory again
If it is an Arduino ADK then pressing its Reset button will also work and will maintain the Accessory permission.

Events:

None

Members:


  Close

  DATABITS_5 As Int

  DATABITS_6 As Int

  DATABITS_7 As Int

  DATABITS_8 As Int

  DeviceInfo As String

  DRIVER_CDCACM As Int

  DRIVER_FTDI As Int

  DRIVER_PROLIFIC As Int

  DRIVER_SILABS As Int

  GetInputStream As java.io.InputStream

  GetOutputStream As java.io.OutputStream

  HasPermission As Boolean

  Open (BaudRate As Int) As Int

  PARITY_EVEN As Int

  PARITY_MARK As Int

  PARITY_NONE As Int

  PARITY_ODD As Int

  PARITY_SPACE As Int

  RequestPermission

  SetCustomDevice (driverID As Int, vendorID As Int, productID As Int)

  SetParameters (baudRate As Int, dataBits As Int, stopBits As Int, parity As Int)

  STOPBITS_1 As Int

  STOPBITS_1_5 As Int

  STOPBITS_2 As Int

  USB_ACCESSORY As Int

  USB_DEVICE As Int

  USB_NONE As Int

  UsbPresent As Int

  UsbTimeout As Int

  Version As Double [read only]

Members description:

Close
Closes the USB device or Accessory.
There seems to be a bug in the Android USB Accessory handling when trying to reconnect to a disconnected Accessory.
In order to reliably connect to an Accessory with your program it is necessary to ensure that
the process of any previous instance of your program that communicated with the Arduino has been killed.
This is the reason why there is an Exit button that calls ExitApplication in the UsbSerial demo program
that you should use to kill the program. It is also necessary before restarting the program
or downloading and running a modified version again to physically disconnect and reconnect the Accessory again
If it is an Arduino ADK then pressing its Reset button will also work and will maintain the Accessry permission.
DATABITS_5 As Int
DATABITS_6 As Int
DATABITS_7 As Int
DATABITS_8 As Int
DeviceInfo As String
Returns a multi-line string containing the details for the connected device.
You need to have obtained permission before calling this method.
DRIVER_CDCACM As Int
DRIVER_FTDI As Int
DRIVER_PROLIFIC As Int
DRIVER_SILABS As Int
GetInputStream As java.io.InputStream
Returns an InputStream for working with AsyncStreams from the RandomAccessFile library.
GetOutputStream As java.io.OutputStream
Returns an OutputStream for working with AsyncStreams from the RandomAccessFile library.
HasPermission As Boolean
Tests whether your application has permission to access this device or Accessory.
Call RequestPermission to receive such permission.
Returns True if the user already has permission.
Open (BaudRate As Int) As Int
Searches for a valid USB device or Accessory and tries to open it.
Returns USB_DEVICE if a device was opened successfully.
Returns USB_ACCESSORY if an accessory was opened successfully.
Returns USB_NONE if neither a device nor an accessory was found.
The BaudRate parameter is ignored if the connected device is an Accessory
PARITY_EVEN As Int
PARITY_MARK As Int
PARITY_NONE As Int
PARITY_ODD As Int
PARITY_SPACE As Int
RequestPermission
Shows a dialog that asks the user to allow your application to access the USB device or Accessory.
Note that this dialog is non-modal so your code that invokes it will carry on running and not wait for the dialog to close.
SetCustomDevice (driverID As Int, vendorID As Int, productID As Int)
If a device might be supported by an existing driver in this library but is not recognised
then it can be added by this method.

The driverID parameter can be one of

DRIVER_PROLIFIC for a device that is compatible with the Prolific PL2303.
DRIVER_SILABS for a device that is compatible with the Silicon Labs CP2102
DRIVER_CDCACM for a device that is compatible with the CDC ACM model.
DRIVER_FTDI for a device that is compatible with the FTDI FT232.

DRIVER_NONE can be used in the unlikely event of needing to unrecongise a device

The vendorID and productID parameters are those of the device in question.
SetParameters (baudRate As Int, dataBits As Int, stopBits As Int, parity As Int)
Sets the parameters of the serial port.
This must be called after the permission is obtained and the port has been opened.
This method is ignored if the connected device is an Accessory which doesn't need these parameters.

baudRate baud rate is an integer, for example 115200.
dataBits is one of DATABITS_5, DATABITS_6, DATABITS_7, or DATABITS_8.
stopBits is one of STOPBITS_1, STOPBITS_1_5, or STOPBITS_2.
parity is one of PARITY_NONE, PARITY_ODD, PARITY_EVEN, PARITY_MARK, or PARITY_SPACE.
STOPBITS_1 As Int
STOPBITS_1_5 As Int
STOPBITS_2 As Int
USB_ACCESSORY As Int
USB_DEVICE As Int
USB_NONE As Int
UsbPresent As Int
Checks is there is a supported device or Accessory connected to the USB port.
Returns USB_DEVICE if a supported slave device is present
Returns USB_ACCESSORY if an Accessory that supports is present
Returns USB_NONE if neither a recognised device nor an accessory was found.
UsbTimeout As Int
This is exposed for dignostic purpose. It sets the timeout that USB reads and writes wait.
The default value of 200mS will probably not need to be changed in normal use.
If you seem to be losing data at high baud rates try reducing or increasing this value
Version As Double [read only]
Returns the version of the library.
Top