Developing USB Accessories

Overview of the USB accessory APIs in Android and the USB Open Accessory protocol.

Transcript

1. Talk to Your Toaster:
   Developing USB Accessories Dave Smith @devunwired Get the Examples: h.p://github.com/devunwired/accessory-samples
2. About the Author 2
3. USB Device Basics 3 Host Master A-Device Powers Enumerates Ini@ates Device Slave B-Device USB OTG
4. USB Device Architecture • Endpoint: Smallest building block of USB devices – Control: ConfiguraJon, status, and control commands • Always one per device called “endpoint 0” – Interrupt: Small, High-priority control commands – Bulk: Data transfer – Isochronous: Real-Jme data transfer • Interface: CollecJon of zero or more endpoints – Represents a “logical” device class. • ConfiguraJon: CollecJon of one or more interfaces – Only one can be acJve at a Jme • Device Class/Subclass/Protocol – USB.org SpecificaJon for device funcJonality – Special Device Class Codes • Human Interface Device (HID) (Class 0x03) • Mass Storage (Class 0x08) • 0x00 = Per-Interface (Composite) • 0xFF = Vendor-Specific 4 ConfiguraJon 0 Interface 1 Interface 0 Endpoint 0 Endpoint Interrupt IN Endpoint 0 Endpoint Bulk IN Endpoint Bulk OUT
5. Standard Descriptors 5 Configura@on Field Size Descrip@on Length 1 Descriptor Size Type 1 0x02 Total Length 2 Total Length of response Interface Count 1 Number of interfaces Value 1 SelecJon Index String Index 1 String Descriptor of Name Abributes 1 Power Type, Remote Wakeup Max Power 1 Power ConsumpJon (2mA units) Device Field Size Descrip@on Length 1 Descriptor Size Type 1 0x01 USB Spec 2 USB SpecificaJon Version Class 1 Class Code SubClass 1 SubClass Code Protocol 1 Protocol Code Max Packet Size 1 Packet size for EP0: 8, 16, 32, 64 VendorID 2 USB.org Vendor ID ProductID 2 Usb.org Product ID Device Release 2 Device Release Number Manufacturer 1 Manufacturer String Descriptor Product 1 Product String Descriptor Serial Number 1 Serial Number String Descriptor Config Count 1 Number of configuraJons
6. Standard Descriptors 6 Interface Field Size Descrip@on Length 1 Descriptor Size Type 1 0x04 Value 1 SelecJon Index Alternate Seeng 1 Endpoint Count 1 Number of endpoints Class 1 Interface Class Code Subclass 1 Interface Subclass Code Protocol 1 Interface Protocol Code String Index 1 String Descriptor of Name Endpoint Field Size Descrip@on Length 1 Descriptor Size Type 1 0x05 Address 1 Number and DirecJon Abributes 1 Type and SynchronizaJon Max Packet Size 2 Max bytes capable of RX/TX Interval 1 Interval for polling, in frames String Field Size Descrip@on Length 1 Descriptor Size Type 1 0x03 String N Unicode Characters
7. USB Open Accessory 7
8. USB Accessories • Official USB Accessory support in 3.1 (android.hardware.usb) – Some 2.3.4+ devices have Add-On library (com.android.future.usb) – CommunicaJon with apps only • AddiJonal features added in 4.1 – CommunicaJon directly with OS • Android Open Accessory (AOA) Protocol – Google custom protocol • Accessory is a USB Host – Responsible for power, enumerate, iniJate • Accessory responsible for configuring Android device in accessory mode 8
9. Open Accessory Protocol • AOA v1.0 – Android 3.1 (Add-On 2.3.4) – Single interface to communicate with an Android applicaJon • Bulk data transfer between applicaJon and accessory • AOA v2.0 – Android 4.1 – Adds Audio Support • Android device may send audio to accessory (only currently supported mode) – Adds Accessory HID • Accessory may act as one or more USB Devices implemenJng a standard HID device class • AOA acts as a thin proxy to pass data directly to Android Input System 9
10. Open Accessory Protocol 10 Accessory Android GET_PROTOCOL_VERSION <1> STRING(manufacturer, model, description, version, URL, serial) ACCESSORY_START Bus Detach/Re-attach Accessory Android Enumerate SET_CONFIGURATION(1) VID(0x18D1) + PID(0x2D00/0x2D01) GET_DESCRIPTOR(CONFIGURATION) Claim Interface 0, EP 0/1
11. Open Accessory Protocol • Android USB PID values – 0x2D00 = Accessory – 0x2D01 = Accessory + ADB – 0x2D02 = Audio (2.0 only) – 0x2D03 = Audio + ADB (2.0 only) – 0x2D04 = Accessory + Audio (2.0 only) – 0x2D05 = Accessory + Audio + ADB (2.0 only) • Audio Support – Send SET_AUDIO_MODE (0x3A) request before sending ACCESSORY_START • 0 = No Audio (default), 1 = 16-bit PCM, 44.1 kHz • Accessory HID – ACCESSORY_REGISTER_HID (0x36) / ACCESSORY_UNREGISTER_HID (0x37) • Tell Android about the new device – ACCESSORY_SEND_HID_REPORT_DESC (0x38) • Send descriptor for HID report events – ACCESSORY_SEND_HID_EVENT (0x39) • Send input events to Android as HID reports 11
12. Accessory Development Kits (ADK) • Many planorms have bundled firmware libraries for OpenAccessory on the following: – Arduino Mega Based (AVR) ADK2011 • USB Host added – Arduino Due Based (ARM) ADK2012 • Bluetooth added – Microchip PIC24F Kits – SparkFun IOIO – FTDI Vinculum-II • ADK DocumentaJon – hbp://developer.android.com/tools/adk/index.html • All schemaJcs for ADK boards and demo shields – hbp://source.android.com/tech/accessories/index.html • Step by step guide to implemenJng OpenAccessory manually
13. USB Accessory APIs 13 UsbAccessory FileDescriptor FileInputStream(fd) FileOutputStream(fd) openAccessory() UsbAccessory (Unknown State) UsbManager getAccessoryList() getParcelableExtra(EXTRA_ACCESSORY) Intent Action USB_ACCESSORY_ATTACHED UsbAccessory (Accessible) Already Granted? User Dialog YES NO UsbManager.requestPermission() Broadcast Action
14. USB Accessory APIs 14 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
 <uses-feature android:name="android.hardware.usb.accessory" />
 
 <application>
 <activity>
 <intent-filter>
 <action android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED" />
 </intent-filter>
 
 <meta-data
 android:name="android.hardware.usb.action.USB_ACCESSORY_ATTACHED"
 android:resource="@xml/accessory_filter" />
 </activity>
 </application>
 </manifest> <resources>
 <usb-accessory manufacturer="..."
 model="..."
 version="..." />
 </resources>
15. ADK Accessory Demo 15
16. USB Host Mode 16
17. USB Host • Available on some devices running 3.1+ – Common on tablets, emerging on phones • Communicate with any standard USB Device – Protocol-level, few high-level funcJons • Android device responsible for power, enumerate, iniJate • High-power device support uncommon – Typically OTG circuitry – <1 power unit typical (<100mA) 17
18. USB Host APIs 18 UsbDevice (Unknown State) UsbManager getDeviceList() getParcelableExtra(EXTRA_DEVICE) Intent Action USB_DEVICE_ATTACHED UsbDevice (Accessible) Already Granted? User Dialog YES NO UsbManager.requestPermission() Broadcast Action UsbDevice UsbEndpoint UsbInterface getInterface(n) getEndpoint(n) UsbDeviceConnection openDevice() claimInterface()
19. USB Host APIs 19 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
 <uses-feature android:name="android.hardware.usb.host" />
 
 <application>
 <activity>
 <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>
 </application>
 </manifest> <resources>
 <usb-device vendor-id="..." product-id="..." class="..." subclass="..." protocol="..." />
 </resources>
20. Data Transfer • UsbDeviceConnecJon.controlTransfer() – Always on "endpoint 0" – Synchronous • UsbDeviceConnecJon.bulkTransfer() – IniJate a bulk transfer on a specific UsbEndpoint – Synchronous • UsbRequest.iniJalize() -> UsbRequest.queue() – Create request on a specific UsbEndpoint – Bulk or Interrupt endpoints – Asynchronous 20
21. USB Host Demos 21
22. Come Find Me! 22 • Dave Smith • Twiber/App.Net: @devunwired • Google+: hbp://plus.google.com/+DaveSmithDev • Blog: hbp://wiresareobsolete.com • Our Work: hbp://www.doubleencore.com • Samples • hbp://www.github.com/devunwired/ accessory-samples