From 8a152071b434d9ab53715dc8a77888b862171b83 Mon Sep 17 00:00:00 2001 From: mike wakerly Date: Mon, 28 Oct 2013 18:33:23 -0700 Subject: [PATCH] Update README.md --- README.md | 81 ++++++++++++++++++++++++++---------- UsbSerialExamples/.classpath | 2 +- UsbSerialLibrary/.classpath | 1 + 3 files changed, 62 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index db956d4..331b7f8 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,11 @@ functions for use with your own protocols. ## Quick Start -**1.** Download [usb-serial-for-android-v010.jar](https://github.com/mik3y/usb-serial-for-android/releases/download/v0.1.0/usb-serial-for-android-v010.jar) +**1.** [Link your project](https://github.com/mik3y/usb-serial-for-android/wiki/Building-From-Source) to the library. -**2.** Copy the jar to your Android project's `libs/` directory. (See [Android's FAQ](http://developer.android.com/guide/faq/commontasks.html#addexternallibrary) for help). +**2.** Copy [device_filter.xml](http://usb-serial-for-android.googlecode.com/git/UsbSerialExamples/res/xml/device_filter.xml) to your project's `res/xml/` directory. -**3.** Copy [device_filter.xml](http://usb-serial-for-android.googlecode.com/git/UsbSerialExamples/res/xml/device_filter.xml) to your project's `res/xml/` directory. - -**4.** 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). +**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). ```xml availableDrivers = UsbSerialProber.getDefaultProber().findAllDrivers(manager); +if (availableDrivers.isEmpty()) { + return; +} -// Find the first available driver. -UsbSerialDriver driver = UsbSerialProber.acquire(manager); +// Open a connection to the first available driver. +UsbSerialDriver driver = availableDrivers.get(0); +UsbDeviceConnection connection = manager.openDevice(driver.getDevice()); +if (connection == null) { + // You probably need to call UsbManager.requestPermission(driver.getDevice(), ..) + return; +} -if (driver != null) { - driver.open(); - try { - driver.setBaudRate(115200); - - byte buffer[] = new byte[16]; - int numBytesRead = driver.read(buffer, 1000); - Log.d(TAG, "Read " + numBytesRead + " bytes."); - } catch (IOException e) { - // Deal with error. - } finally { - driver.close(); - } +// Read some data! Most have just one port (port 0). +UsbSerialPort port = driver.getPort(0); +port.open(connection); +try { + port.setBaudRate(115200); + byte buffer[] = new byte[16]; + int numBytesRead = port.read(buffer, 1000); + Log.d(TAG, "Read " + numBytesRead + " bytes."); +} catch (IOException e) { + // Deal with error. +} finally { + port.close(); } ``` @@ -68,6 +74,39 @@ 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) is also available which can be used for testing. + +## 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: + +```java +// Probe for our custom CDC devices, which use VID 0x1234 +// and PIDS 0x0001 and 0x0002. +ProbeTable customTable = new ProbeTable(); +probeTable.addProduct(0x1234, 0x0001, CdcAcmSerialDriver.class); +probeTable.addProduct(0x1234, 0x0002, CdcAcmSerialDriver.class); + +UsbSerialProber prober = new UsbSerialProber(customTable); +List 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 * *Serial chips:* FT232R, CDC/ACM (eg Arduino Uno) and possibly others. diff --git a/UsbSerialExamples/.classpath b/UsbSerialExamples/.classpath index 202cbff..a789bb7 100644 --- a/UsbSerialExamples/.classpath +++ b/UsbSerialExamples/.classpath @@ -4,7 +4,7 @@ - + diff --git a/UsbSerialLibrary/.classpath b/UsbSerialLibrary/.classpath index 6aed2eb..7bc01d9 100644 --- a/UsbSerialLibrary/.classpath +++ b/UsbSerialLibrary/.classpath @@ -4,5 +4,6 @@ +