flywithu/usb-serial-for-android
1
0
Fork 0
mirror of https://github.com/mik3y/usb-serial-for-android synced 2025-10-30 09:57:19 +00:00
Code Issues Releases Wiki Activity

README cleanup

Browse Source
This commit is contained in:
Kai Morich 2019-10-06 10:19:04 +02:00
parent 6e58180f91
commit 508c39e66a
1 changed files with 141 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

284
README.md
View File

@ -1,143 +1,141 @@
# usb-serial-for-android # usb-serial-for-android
This is a driver library for communication with Arduinos and other USB serial hardware on This is a driver library for communication with Arduinos and other USB serial hardware on
Android, using the Android, using the
[Android USB Host API](http://developer.android.com/guide/topics/connectivity/usb/host.html) [Android USB Host Mode (OTG)](http://developer.android.com/guide/topics/connectivity/usb/host.html)
available since Android 3.1 and asynchronous interrupt transfer working reliably since Android 4.2 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 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 Java. You get a raw serial port with `read()`, `write()`, and other basic
functions for use with your own protocols. functions for use with your own protocols.
* **Homepage**: https://github.com/mik3y/usb-serial-for-android ## Quick Start
* **Google group**: http://groups.google.com/group/usb-serial-for-android
* **Latest release**: [v0.1.0](https://github.com/mik3y/usb-serial-for-android/releases) **1.** [Link your project](https://github.com/mik3y/usb-serial-for-android/wiki/Building-From-Source) to the library.
## Quick Start **2.** Copy [device_filter.xml](https://github.com/mik3y/usb-serial-for-android/blob/master/usbSerialExamples/src/main/res/xml/device_filter.xml) to your project's `res/xml/` directory.
**1.** [Link your project](https://github.com/mik3y/usb-serial-for-android/wiki/Building-From-Source) to the library. **3.** Configure your `AndroidManifest.xml` to notify your app when a device is attached (see [Android USB Host documentation](http://developer.android.com/guide/topics/connectivity/usb/host.html#discovering-d) for help).
**2.** Copy [device_filter.xml](https://github.com/mik3y/usb-serial-for-android/blob/master/usbSerialExamples/src/main/res/xml/device_filter.xml) to your project's `res/xml/` directory. ```xml
<activity
**3.** Configure your `AndroidManifest.xml` to notify your app when a device is attached (see [Android USB Host documentation](http://developer.android.com/guide/topics/connectivity/usb/host.html#discovering-d) for help). android:name="..."
...>
```xml <intent-filter>
<activity <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
android:name="..." </intent-filter>
...> <meta-data
<intent-filter> android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
<action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" /> android:resource="@xml/device_filter" />
</intent-filter> </activity>
<meta-data ```
android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED"
android:resource="@xml/device_filter" /> **4.** Use it! Example code snippet:
</activity>
``` ```java
// Find all available drivers from attached devices.
**4.** Use it! Example code snippet: UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE);
List<UsbSerialDriver> availableDrivers = UsbSerialProber.getDefaultProber().findAllDrivers(manager);
```java if (availableDrivers.isEmpty()) {
// Find all available drivers from attached devices. return;
UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); }
List<UsbSerialDriver> availableDrivers = UsbSerialProber.getDefaultProber().findAllDrivers(manager);
if (availableDrivers.isEmpty()) { // Open a connection to the first available driver.
return; UsbSerialDriver driver = availableDrivers.get(0);
} UsbDeviceConnection connection = manager.openDevice(driver.getDevice());
if (connection == null) {
// Open a connection to the first available driver. // You probably need to call UsbManager.requestPermission(driver.getDevice(), ..)
UsbSerialDriver driver = availableDrivers.get(0); return;
UsbDeviceConnection connection = manager.openDevice(driver.getDevice()); }
if (connection == null) {
// You probably need to call UsbManager.requestPermission(driver.getDevice(), ..) // Read some data! Most have just one port (port 0).
return; UsbSerialPort port = driver.getPorts().get(0);
} try {
port.open(connection);
// Read some data! Most have just one port (port 0). port.setParameters(115200, 8, UsbSerialPort.STOPBITS_1, UsbSerialPort.PARITY_NONE);
UsbSerialPort port = driver.getPorts().get(0);
try { byte buffer[] = new byte[16];
port.open(connection); int numBytesRead = port.read(buffer, 1000);
port.setParameters(115200, 8, UsbSerialPort.STOPBITS_1, UsbSerialPort.PARITY_NONE); Log.d(TAG, "Read " + numBytesRead + " bytes.");
} catch (IOException e) {
byte buffer[] = new byte[16]; // Deal with error.
int numBytesRead = port.read(buffer, 1000); } finally {
Log.d(TAG, "Read " + numBytesRead + " bytes."); port.close();
} catch (IOException e) { }
// Deal with error. ```
} finally {
port.close(); For a simple example, see the
} [UsbSerialExamples project](https://github.com/mik3y/usb-serial-for-android/blob/master/usbSerialExamples)
``` in git, which is a simple application for reading and showing serial data.
For a more complete example, see the For a more complete example, see separate github project
[UsbSerialExamples project](https://github.com/mik3y/usb-serial-for-android/blob/master/usbSerialExamples) [SimpleUsbTerminal](https://github.com/kai-morich/SimpleUsbTerminal)
in git, which is a simple application for reading and showing serial data.
A [simple Arduino application](https://github.com/mik3y/usb-serial-for-android/blob/master/arduino)
A [simple Arduino application](https://github.com/mik3y/usb-serial-for-android/blob/master/arduino) is also available which can be used for testing.
is also available which can be used for testing.
## Probing for Unrecognized Devices
## 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
Sometimes you may need to do a little extra work to support devices which compatible with one of the built-in drivers. This may be the case for a brand
usb-serial-for-android doesn't [yet] know about -- but which you know to be new device or for one using a custom VID/PID pair.
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
UsbSerialProber is a class to help you find and instantiate compatible the default prober returned by ``UsbSerialProber.getDefaultProber()``, which
UsbSerialDrivers from the tree of connected UsbDevices. Normally, you will use uses the built-in list of well-known VIDs and PIDs that are supported by our
the default prober returned by ``UsbSerialProber.getDefaultProber()``, which drivers.
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:
To use your own set of rules, create and use a custom prober: ```java
// Probe for our custom CDC devices, which use VID 0x1234
```java // and PIDS 0x0001 and 0x0002.
// Probe for our custom CDC devices, which use VID 0x1234 ProbeTable customTable = new ProbeTable();
// and PIDS 0x0001 and 0x0002. customTable.addProduct(0x1234, 0x0001, CdcAcmSerialDriver.class);
ProbeTable customTable = new ProbeTable(); customTable.addProduct(0x1234, 0x0002, CdcAcmSerialDriver.class);
customTable.addProduct(0x1234, 0x0001, CdcAcmSerialDriver.class);
customTable.addProduct(0x1234, 0x0002, CdcAcmSerialDriver.class); UsbSerialProber prober = new UsbSerialProber(customTable);
List<UsbSerialDriver> drivers = prober.findAllDrivers(usbManager);
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
Of course, nothing requires you to use UsbSerialProber at all: you can a compatible UsbDevice.
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:
## Compatible Devices * FTDI FT232, FT2232, ...
* Prolific PL2303
* *Serial chips:* FT232R, CDC/ACM (eg Arduino Uno) and possibly others. * Silabs CP2102, CP2105, ...
See [CompatibleSerialDevices](https://github.com/mik3y/usb-serial-for-android/wiki/Compatible-Serial-Devices). * Qinheng CH340
* *Android phones and tablets:* Nexus 7, Motorola Xoom, and many others.
See [CompatibleAndroidDevices](https://github.com/mik3y/usb-serial-for-android/wiki/Compatible-Android-Devices). and devices implementing the CDC/ACM protocol like
* Arduino using ATmega32U4
* Digispark using V-USB software USB
## Author, License, and Copyright * BBC micro:bit using ARM mbed DAPLink firmware
* ...
usb-serial-for-android is written and maintained by *mike wakerly*.
## Author, License, and Copyright
This library is licensed under *LGPL Version 2.1*. Please see LICENSE.txt for the
complete license. usb-serial-for-android is written and maintained by *mike wakerly* and *kai morich*
Copyright 2011-2012, Google Inc. All Rights Reserved. This library is licensed under *LGPL Version 2.1*. Please see LICENSE.txt for the
complete license.
Portions of this library are based on libftdi
(http://www.intra2net.com/en/developer/libftdi). Please see Copyright 2011-2012, Google Inc. All Rights Reserved.
FtdiSerialDriver.java for more information.
Portions of this library are based on [libftdi](http://www.intra2net.com/en/developer/libftdi).
## Help & Discussion Please see FtdiSerialDriver.java for more information.
For common problems, see the ## Help & Discussion
[Troubleshooting](https://github.com/mik3y/usb-serial-for-android/wiki/Troubleshooting)
wiki page. For common problems, see the
[Troubleshooting](https://github.com/mik3y/usb-serial-for-android/wiki/Troubleshooting)
For other help and discussion, please join our Google Group, wiki page.
[usb-serial-for-android](https://groups.google.com/forum/?fromgroups#!forum/usb-serial-for-android).
Are you using the library? Let us know on the group and we'll add your project to
Are you using the library? Let us know on the group and we'll add your project to [ProjectsUsingUsbSerialForAndroid](https://github.com/mik3y/usb-serial-for-android/wiki/Projects-Using-usb-serial-for-android).
[ProjectsUsingUsbSerialForAndroid](https://github.com/mik3y/usb-serial-for-android/wiki/Projects-Using-usb-serial-for-android).