Documentation/usb/usb-serial.rst

   1 ==========
   2 USB serial
   3 ==========
   4
   5 Introduction
   6 ============
   7
   8   The USB serial driver currently supports a number of different USB to
   9   serial converter products, as well as some devices that use a serial
  10   interface from userspace to talk to the device.
  11
  12   See the individual product section below for specific information about
  13   the different devices.
  14
  15
  16 Configuration
  17 =============
  18
  19   Currently the driver can handle up to 256 different serial interfaces at
  20   one time.
  21
  22     The major number that the driver uses is 188 so to use the driver,
  23     create the following nodes::
  24
  25         mknod /dev/ttyUSB0 c 188 0
  26         mknod /dev/ttyUSB1 c 188 1
  27         mknod /dev/ttyUSB2 c 188 2
  28         mknod /dev/ttyUSB3 c 188 3
  29                 .
  30                 .
  31                 .
  32         mknod /dev/ttyUSB254 c 188 254
  33         mknod /dev/ttyUSB255 c 188 255
  34
  35   When the device is connected and recognized by the driver, the driver
  36   will print to the system log, which node(s) the device has been bound
  37   to.
  38
  39
  40 Specific Devices Supported
  41 ==========================
  42
  43
  44 ConnectTech WhiteHEAT 4 port converter
  45 --------------------------------------
  46
  47   ConnectTech has been very forthcoming with information about their
  48   device, including providing a unit to test with.
  49
  50   The driver is officially supported by Connect Tech Inc.
  51   http://www.connecttech.com
  52
  53   For any questions or problems with this driver, please contact
  54   Connect Tech's Support Department at support@connecttech.com
  55
  56
  57 HandSpring Visor, Palm USB, and Clié USB driver
  58 -----------------------------------------------
  59
  60   This driver works with all HandSpring USB, Palm USB, and Sony Clié USB
  61   devices.
  62
  63   Only when the device tries to connect to the host, will the device show
  64   up to the host as a valid USB device. When this happens, the device is
  65   properly enumerated, assigned a port, and then communication _should_ be
  66   possible. The driver cleans up properly when the device is removed, or
  67   the connection is canceled on the device.
  68
  69   NOTE:
  70     This means that in order to talk to the device, the sync button must be
  71     pressed BEFORE trying to get any program to communicate to the device.
  72     This goes against the current documentation for pilot-xfer and other
  73     packages, but is the only way that it will work due to the hardware
  74     in the device.
  75
  76   When the device is connected, try talking to it on the second port
  77   (this is usually /dev/ttyUSB1 if you do not have any other usb-serial
  78   devices in the system.) The system log should tell you which port is
  79   the port to use for the HotSync transfer. The "Generic" port can be used
  80   for other device communication, such as a PPP link.
  81
  82   For some Sony Clié devices, /dev/ttyUSB0 must be used to talk to the
  83   device.  This is true for all OS version 3.5 devices, and most devices
  84   that have had a flash upgrade to a newer version of the OS.  See the
  85   kernel system log for information on which is the correct port to use.
  86
  87   If after pressing the sync button, nothing shows up in the system log,
  88   try resetting the device, first a hot reset, and then a cold reset if
  89   necessary.  Some devices need this before they can talk to the USB port
  90   properly.
  91
  92   Devices that are not compiled into the kernel can be specified with module
  93   parameters.  e.g. modprobe visor vendor=0x54c product=0x66
  94
  95   There is a webpage and mailing lists for this portion of the driver at:
  96   http://sourceforge.net/projects/usbvisor/
  97
  98   For any questions or problems with this driver, please contact Greg
  99   Kroah-Hartman at greg@kroah.com
 100
 101
 102 PocketPC PDA Driver
 103 -------------------
 104
 105   This driver can be used to connect to Compaq iPAQ, HP Jornada, Casio EM500
 106   and other PDAs running Windows CE 3.0 or PocketPC 2002 using a USB
 107   cable/cradle.
 108   Most devices supported by ActiveSync are supported out of the box.
 109   For others, please use module parameters to specify the product and vendor
 110   id. e.g. modprobe ipaq vendor=0x3f0 product=0x1125
 111
 112   The driver presents a serial interface (usually on /dev/ttyUSB0) over
 113   which one may run ppp and establish a TCP/IP link to the PDA. Once this
 114   is done, you can transfer files, backup, download email etc. The most
 115   significant advantage of using USB is speed - I can get 73 to 113
 116   kbytes/sec for download/upload to my iPAQ.
 117
 118   This driver is only one of a set of components required to utilize
 119   the USB connection. Please visit http://synce.sourceforge.net which
 120   contains the necessary packages and a simple step-by-step howto.
 121
 122   Once connected, you can use Win CE programs like ftpView, Pocket Outlook
 123   from the PDA and xcerdisp, synce utilities from the Linux side.
 124
 125   To use Pocket IE, follow the instructions given at
 126   http://www.tekguru.co.uk/EM500/usbtonet.htm to achieve the same thing
 127   on Win98. Omit the proxy server part; Linux is quite capable of forwarding
 128   packets unlike Win98. Another modification is required at least for the
 129   iPAQ - disable autosync by going to the Start/Settings/Connections menu
 130   and unchecking the "Automatically synchronize ..." box. Go to
 131   Start/Programs/Connections, connect the cable and select "usbdial" (or
 132   whatever you named your new USB connection). You should finally wind
 133   up with a "Connected to usbdial" window with status shown as connected.
 134   Now start up PIE and browse away.
 135
 136   If it doesn't work for some reason, load both the usbserial and ipaq module
 137   with the module parameter "debug" set to 1 and examine the system log.
 138   You can also try soft-resetting your PDA before attempting a connection.
 139
 140   Other functionality may be possible depending on your PDA. According to
 141   Wes Cilldhaire <billybobjoehenrybob@hotmail.com>, with the Toshiba E570,
 142   ...if you boot into the bootloader (hold down the power when hitting the
 143   reset button, continuing to hold onto the power until the bootloader screen
 144   is displayed), then put it in the cradle with the ipaq driver loaded, open
 145   a terminal on /dev/ttyUSB0, it gives you a "USB Reflash" terminal, which can
 146   be used to flash the ROM, as well as the microP code..  so much for needing
 147   Toshiba's $350 serial cable for flashing!! :D
 148   NOTE: This has NOT been tested. Use at your own risk.
 149
 150   For any questions or problems with the driver, please contact Ganesh
 151   Varadarajan <ganesh@veritas.com>
 152
 153
 154 Keyspan PDA Serial Adapter
 155 --------------------------
 156
 157   Single port DB-9 serial adapter, pushed as a PDA adapter for iMacs (mostly
 158   sold in Macintosh catalogs, comes in a translucent white/green dongle).
 159   Fairly simple device. Firmware is homebrew.
 160   This driver also works for the Xircom/Entrega single port serial adapter.
 161
 162   Current status:
 163
 164    Things that work:
 165      - basic input/output (tested with 'cu')
 166      - blocking write when serial line can't keep up
 167      - changing baud rates (up to 115200)
 168      - getting/setting modem control pins (TIOCM{GET,SET,BIS,BIC})
 169      - sending break (although duration looks suspect)
 170
 171    Things that don't:
 172      - device strings (as logged by kernel) have trailing binary garbage
 173      - device ID isn't right, might collide with other Keyspan products
 174      - changing baud rates ought to flush tx/rx to avoid mangled half characters
 175
 176    Big Things on the todo list:
 177      - parity, 7 vs 8 bits per char, 1 or 2 stop bits
 178      - HW flow control
 179      - not all of the standard USB descriptors are handled:
 180        Get_Status, Set_Feature, O_NONBLOCK, select()
 181
 182   For any questions or problems with this driver, please contact Brian
 183   Warner at warner@lothar.com
 184
 185
 186 Keyspan USA-series Serial Adapters
 187 ----------------------------------
 188
 189   Single, Dual and Quad port adapters - driver uses Keyspan supplied
 190   firmware and is being developed with their support.
 191
 192   Current status:
 193
 194     The USA-18X, USA-28X, USA-19, USA-19W and USA-49W are supported and
 195     have been pretty thoroughly tested at various baud rates with 8-N-1
 196     character settings.  Other character lengths and parity setups are
 197     presently untested.
 198
 199     The USA-28 isn't yet supported though doing so should be pretty
 200     straightforward.  Contact the maintainer if you require this
 201     functionality.
 202
 203   More information is available at:
 204
 205         http://www.carnationsoftware.com/carnation/Keyspan.html
 206
 207   For any questions or problems with this driver, please contact Hugh
 208   Blemings at hugh@misc.nu
 209
 210
 211 FTDI Single Port Serial Driver
 212 ------------------------------
 213
 214   This is a single port DB-25 serial adapter.
 215
 216   Devices supported include:
 217
 218                 - TripNav TN-200 USB GPS
 219                 - Navis Engineering Bureau CH-4711 USB GPS
 220
 221   For any questions or problems with this driver, please contact Bill Ryder.
 222
 223
 224 ZyXEL omni.net lcd plus ISDN TA
 225 -------------------------------
 226
 227   This is an ISDN TA. Please report both successes and troubles to
 228   azummo@towertech.it
 229
 230
 231 Cypress M8 CY4601 Family Serial Driver
 232 --------------------------------------
 233
 234   This driver was in most part developed by Neil "koyama" Whelchel.  It
 235   has been improved since that previous form to support dynamic serial
 236   line settings and improved line handling.  The driver is for the most
 237   part stable and has been tested on an smp machine. (dual p2)
 238
 239     Chipsets supported under CY4601 family:
 240
 241                 CY7C63723, CY7C63742, CY7C63743, CY7C64013
 242
 243     Devices supported:
 244
 245                 - DeLorme's USB Earthmate GPS (SiRF Star II lp arch)
 246                 - Cypress HID->COM RS232 adapter
 247
 248                 Note:
 249                         Cypress Semiconductor claims no affiliation with the
 250                         hid->com device.
 251
 252      Most devices using chipsets under the CY4601 family should
 253      work with the driver.  As long as they stay true to the CY4601
 254      usbserial specification.
 255
 256     Technical notes:
 257
 258         The Earthmate starts out at 4800 8N1 by default... the driver will
 259         upon start init to this setting.  usbserial core provides the rest
 260         of the termios settings, along with some custom termios so that the
 261         output is in proper format and parsable.
 262
 263         The device can be put into sirf mode by issuing NMEA command::
 264
 265                 $PSRF100,<protocol>,<baud>,<databits>,<stopbits>,<parity>*CHECKSUM
 266                 $PSRF100,0,9600,8,1,0*0C
 267
 268                 It should then be sufficient to change the port termios to match this
 269                 to begin communicating.
 270
 271         As far as I can tell it supports pretty much every sirf command as
 272         documented online available with firmware 2.31, with some unknown
 273         message ids.
 274
 275         The hid->com adapter can run at a maximum baud of 115200bps.  Please note
 276         that the device has trouble or is incapable of raising line voltage properly.
 277         It will be fine with null modem links, as long as you do not try to link two
 278         together without hacking the adapter to set the line high.
 279
 280         The driver is smp safe.  Performance with the driver is rather low when using
 281         it for transferring files.  This is being worked on, but I would be willing to
 282         accept patches.  An urb queue or packet buffer would likely fit the bill here.
 283
 284         If you have any questions, problems, patches, feature requests, etc. you can
 285         contact me here via email:
 286
 287                                         dignome@gmail.com
 288
 289                 (your problems/patches can alternately be submitted to usb-devel)
 290
 291
 292 Digi AccelePort Driver
 293 ----------------------
 294
 295   This driver supports the Digi AccelePort USB 2 and 4 devices, 2 port
 296   (plus a parallel port) and 4 port USB serial converters.  The driver
 297   does NOT yet support the Digi AccelePort USB 8.
 298
 299   This driver works under SMP with the usb-uhci driver.  It does not
 300   work under SMP with the uhci driver.
 301
 302   The driver is generally working, though we still have a few more ioctls
 303   to implement and final testing and debugging to do.  The parallel port
 304   on the USB 2 is supported as a serial to parallel converter; in other
 305   words, it appears as another USB serial port on Linux, even though
 306   physically it is really a parallel port.  The Digi Acceleport USB 8
 307   is not yet supported.
 308
 309   Please contact Peter Berger (pberger@brimson.com) or Al Borchers
 310   (alborchers@steinerpoint.com) for questions or problems with this
 311   driver.
 312
 313
 314 Belkin USB Serial Adapter F5U103
 315 --------------------------------
 316
 317   Single port DB-9/PS-2 serial adapter from Belkin with firmware by eTEK Labs.
 318   The Peracom single port serial adapter also works with this driver, as
 319   well as the GoHubs adapter.
 320
 321   Current status:
 322
 323     The following have been tested and work:
 324
 325       - Baud rate    300-230400
 326       - Data bits    5-8
 327       - Stop bits    1-2
 328       - Parity       N,E,O,M,S
 329       - Handshake    None, Software (XON/XOFF), Hardware (CTSRTS,CTSDTR) [1]_
 330       - Break        Set and clear
 331       - Line control Input/Output query and control [2]_
 332
 333   .. [1]
 334          Hardware input flow control is only enabled for firmware
 335          levels above 2.06.  Read source code comments describing Belkin
 336          firmware errata.  Hardware output flow control is working for all
 337          firmware versions.
 338
 339   .. [2]
 340          Queries of inputs (CTS,DSR,CD,RI) show the last
 341          reported state.  Queries of outputs (DTR,RTS) show the last
 342          requested state and may not reflect current state as set by
 343          automatic hardware flow control.
 344
 345   TO DO List:
 346     - Add true modem control line query capability.  Currently tracks the
 347       states reported by the interrupt and the states requested.
 348     - Add error reporting back to application for UART error conditions.
 349     - Add support for flush ioctls.
 350     - Add everything else that is missing :)
 351
 352   For any questions or problems with this driver, please contact William
 353   Greathouse at wgreathouse@smva.com
 354
 355
 356 Empeg empeg-car Mark I/II Driver
 357 --------------------------------
 358
 359   This is an experimental driver to provide connectivity support for the
 360   client synchronization tools for an Empeg empeg-car mp3 player.
 361
 362   Tips:
 363     * Don't forget to create the device nodes for ttyUSB{0,1,2,...}
 364     * modprobe empeg (modprobe is your friend)
 365     * emptool --usb /dev/ttyUSB0 (or whatever you named your device node)
 366
 367   For any questions or problems with this driver, please contact Gary
 368   Brubaker at xavyer@ix.netcom.com
 369
 370
 371 MCT USB Single Port Serial Adapter U232
 372 ---------------------------------------
 373
 374   This driver is for the MCT USB-RS232 Converter (25 pin, Model No.
 375   U232-P25) from Magic Control Technology Corp. (there is also a 9 pin
 376   Model No. U232-P9). More information about this device can be found at
 377   the manufacturer's web-site: http://www.mct.com.tw.
 378
 379   The driver is generally working, though it still needs some more testing.
 380   It is derived from the Belkin USB Serial Adapter F5U103 driver and its
 381   TODO list is valid for this driver as well.
 382
 383   This driver has also been found to work for other products, which have
 384   the same Vendor ID but different Product IDs. Sitecom's U232-P25 serial
 385   converter uses Product ID 0x230 and Vendor ID 0x711 and works with this
 386   driver. Also, D-Link's DU-H3SP USB BAY also works with this driver.
 387
 388   For any questions or problems with this driver, please contact Wolfgang
 389   Grandegger at wolfgang@ces.ch
 390
 391
 392 Inside Out Networks Edgeport Driver
 393 -----------------------------------
 394
 395   This driver supports all devices made by Inside Out Networks, specifically
 396   the following models:
 397
 398        - Edgeport/4
 399        - Rapidport/4
 400        - Edgeport/4t
 401        - Edgeport/2
 402        - Edgeport/4i
 403        - Edgeport/2i
 404        - Edgeport/421
 405        - Edgeport/21
 406        - Edgeport/8
 407        - Edgeport/8 Dual
 408        - Edgeport/2D8
 409        - Edgeport/4D8
 410        - Edgeport/8i
 411        - Edgeport/2 DIN
 412        - Edgeport/4 DIN
 413        - Edgeport/16 Dual
 414
 415   For any questions or problems with this driver, please contact Greg
 416   Kroah-Hartman at greg@kroah.com
 417
 418
 419 REINER SCT cyberJack pinpad/e-com USB chipcard reader
 420 -----------------------------------------------------
 421
 422   Interface to ISO 7816 compatible contactbased chipcards, e.g. GSM SIMs.
 423
 424   Current status:
 425
 426     This is the kernel part of the driver for this USB card reader.
 427     There is also a user part for a CT-API driver available. A site
 428     for downloading is TBA. For now, you can request it from the
 429     maintainer (linux-usb@sii.li).
 430
 431   For any questions or problems with this driver, please contact
 432   linux-usb@sii.li
 433
 434
 435 Prolific PL2303 Driver
 436 ----------------------
 437
 438   This driver supports any device that has the PL2303 chip from Prolific
 439   in it.  This includes a number of single port USB to serial converters,
 440   more than 70% of USB GPS devices (in 2010), and some USB UPSes. Devices
 441   from Aten (the UC-232) and IO-Data work with this driver, as does
 442   the DCU-11 mobile-phone cable.
 443
 444   For any questions or problems with this driver, please contact Greg
 445   Kroah-Hartman at greg@kroah.com
 446
 447
 448 KL5KUSB105 chipset / PalmConnect USB single-port adapter
 449 --------------------------------------------------------
 450
 451 Current status:
 452
 453   The driver was put together by looking at the usb bus transactions
 454   done by Palm's driver under Windows, so a lot of functionality is
 455   still missing.  Notably, serial ioctls are sometimes faked or not yet
 456   implemented.  Support for finding out about DSR and CTS line status is
 457   however implemented (though not nicely), so your favorite autopilot(1)
 458   and pilot-manager -daemon calls will work.  Baud rates up to 115200
 459   are supported, but handshaking (software or hardware) is not, which is
 460   why it is wise to cut down on the rate used is wise for large
 461   transfers until this is settled.
 462
 463   See http://www.uuhaus.de/linux/palmconnect.html for up-to-date
 464   information on this driver.
 465
 466 Winchiphead CH341 Driver
 467 ------------------------
 468
 469   This driver is for the Winchiphead CH341 USB-RS232 Converter. This chip
 470   also implements an IEEE 1284 parallel port, I2C and SPI, but that is not
 471   supported by the driver. The protocol was analyzed from the behaviour
 472   of the Windows driver, no datasheet is available at present.
 473
 474   The manufacturer's website: http://www.winchiphead.com/.
 475
 476   For any questions or problems with this driver, please contact
 477   frank@kingswood-consulting.co.uk.
 478
 479 Moschip MCS7720, MCS7715 driver
 480 -------------------------------
 481
 482   These chips are present in devices sold by various manufacturers, such as Syba
 483   and Cables Unlimited.  There may be others.  The 7720 provides two serial
 484   ports, and the 7715 provides one serial and one standard PC parallel port.
 485   Support for the 7715's parallel port is enabled by a separate option, which
 486   will not appear unless parallel port support is first enabled at the top-level
 487   of the Device Drivers config menu.  Currently only compatibility mode is
 488   supported on the parallel port (no ECP/EPP).
 489
 490   TODO:
 491     - Implement ECP/EPP modes for the parallel port.
 492     - Baud rates higher than 115200 are currently broken.
 493     - Devices with a single serial port based on the Moschip MCS7703 may work
 494       with this driver with a simple addition to the usb_device_id table.  I
 495       don't have one of these devices, so I can't say for sure.
 496
 497 Generic Serial driver
 498 ---------------------
 499
 500   If your device is not one of the above listed devices, compatible with
 501   the above models, you can try out the "generic" interface. This
 502   interface does not provide any type of control messages sent to the
 503   device, and does not support any kind of device flow control. All that
 504   is required of your device is that it has at least one bulk in endpoint,
 505   or one bulk out endpoint.
 506
 507   To enable the generic driver to recognize your device, provide::
 508
 509         echo <vid> <pid> >/sys/bus/usb-serial/drivers/generic/new_id
 510
 511   where the <vid> and <pid> is replaced with the hex representation of your
 512   device's vendor id and product id.
 513   If the driver is compiled as a module you can also provide one id when
 514   loading the module::
 515
 516         insmod usbserial vendor=0x#### product=0x####
 517
 518   This driver has been successfully used to connect to the NetChip USB
 519   development board, providing a way to develop USB firmware without
 520   having to write a custom driver.
 521
 522   For any questions or problems with this driver, please contact Greg
 523   Kroah-Hartman at greg@kroah.com
 524
 525
 526 Contact
 527 =======
 528
 529   If anyone has any problems using these drivers, with any of the above
 530   specified products, please contact the specific driver's author listed
 531   above, or join the Linux-USB mailing list (information on joining the
 532   mailing list, as well as a link to its searchable archive is at
 533   http://www.linux-usb.org/ )
 534
 535
 536 Greg Kroah-Hartman
 537 greg@kroah.com