How to configure USB serial adapters in Linux

The serial USB driver in Linux contains many product IDs for Sealevel devices. However, the newest devices may not be currently included in the driver. This guide consists of example USB device installation instructions using either driver load time parameters or modification of the device driver to natively support the device. There are often subtle differences in Linux distributions. Any distribution specific conflicts should be resolved by consulting the distribution’s documentation.

Option 1: Serial USB Installation Instructions (No Recompile Necessary)

Notes:

• Commands preceded by ‘$’ can be issued by user-level privileges.
• Commands preceded by ‘#’ require root-level privileges.
• This method will ONLY work with single and dual port devices. Any device with more than two ports requires a driver modification and recompile (see Option 2 below).

1) Plug in the Sealevel USB device(s).

2) Open a terminal window and attain root privileges. This varies by distribution, but the most common method is to use the su command as demonstrated below.

$ su
Password:
#

3) Ensure that the device has been detected by the USB subsystem. This can be accomplished by using the lsusb command as demonstrated below. The -s 0c52 parameter returns only information about Sealevel devices attached to the system’s USB subsystem. For this example, we will attach the device driver to the e402 Sealevel hardware, which is the USB to RS-485 bridge used in Sealevel SeaI/O U-series data acquisition modules.

# lsusb -s 0c52  Bus  002 Device 011: ID 0c52:e402 Sealevel Systems, Inc.  Bus  002 Device 010: ID 0c52:2101 Sealevel Systems, Inc.

4) The kernel driver module for all FTDI based USB serial devices is sometimes configured for automatic load at boot time. Depending on distribution, it may be necessary to unload the driver if it is already loaded. This can be achieved by issuing the following command. This command can be issued without detriment when the driver is not loaded.

# modprobe -r ftdi_sio

5) The FTDI serial USB driver in Linux contains many product IDs for Sealevel devices. However, the newest devices may not be currently included in the driver. The driver allows a single vendor and product pair to be passed at module load time. Using these parameters, it is unnecessary to recompile the driver. To inform the FTDI driver of the Sealevel device’s identification information, issue the following command.

# modprobe ftdi_sio vendor=0x0C52 product=0xE402

6) The driver should now have identified the Sealevel device and is ready for communications. It may now be necessary to create the character special file used to interface with the device. Most modern distributions include a method of automatically creating these files in the /dev file system when they are identified by a device driver. The character special files typically use the ttyUSB# nomenclature. Verify their creation by issuing the following command.

# ls -al /dev/ttyUSB*
crw-rw----1 root uucp 188, 0 2008-05-08 10:59 /dev/ttyUSB0
crw-rw----1 root uucp 188, 1 2008-05-08 10:59 /dev/ttyUSB1

7) If the character special files have not been created automatically, or more than one appears, it is necessary to identify the driver major and device minor numbers. The driver major can be determined by searching the devices file in the /proc file system as demonstrated in the following command. The major number is highlighted in yellow below.

# cat /proc/devices | grep -i "ttyUSB"
188 ttyUSB

The device minor number can also be determined by searching a file located in the /proc file system. The tty directory contains information about all of the currently loaded tty drivers. Executing the next command will display a list of all USB serial ports detected by any USB serial drivers currently loaded. If multiple USB serial ports are detected by the system, identify which corresponds to the Sealevel device by checking the vendor and product IDs.

# cat /proc/tty/driver/usbserial
usbserinfo:1.0 driver:2.0
0: module:ftdi_sio name:"FTDI USB Serial Device" vendor:0c52 product:2101 
num_ports:1
port:1 path:usb-0000:00:1d.1-1.2
1: module:ftdi_sio name:"FTDI USB Serial Device" vendor:0c52 product:e402 
num_ports:1
port:1 path:usb-0000:00:1d.1-1.4

8) If the character special file for the Sealevel device was not present in step 6, it may be created by executing the following command. It may also be beneficial to you to create any extra special files corresponding to other USB serial devices that are not currently present. Be sure to replace the major and minor numbers listed below with those listed by the commands demonstrated in step 7 as they may vary from system to system.

# mknod /dev/ttyUSB0 c 188 0
# mknod /dev/ttyUSB1 c 188 1

9) User applications may now interactive with Sealevel device through the character special file with major and minor numbers corresponding to those determined in step 7. To check the major and minor numbers that are associated with the character special files in /dev file system, use the ls command as demonstrated. The major/minor pair is highlighted in yellow for each file.

# ls -al /dev/ttyUSB*
crw-rw----1 root uucp 188, 0 2008-05-08 10:59 /dev/ttyUSB0
crw-rw----1 root uucp 188, 1 2008-05-08 10:59 /dev/ttyUSB1

10) Ensure that all users account which must access the Sealevel device may do so. There are many ways to configure the file permissions to accomplish this goal, depending on the system and requirements. Distribution documentation on the chmod and chown commands should be consulted. To simply allow full access to any USB serial device, use the following command.

# chmod 777 /dev/ttyUSB*

The Sealevel device can now be accessed through the character special file corresponding to the major/minor pair of the device. In the examples shown here, the file would be /dev/ttyUSB1.

Option 2: Serial USB Installation Instructions (Hardcoded Driver Support)

Notes:

• Commands preceded by ‘$’ can be issued by user-level privileges.
• Commands preceded by ‘#’ require root-level privileges.
• This is the ONLY way a device with more than 2 ports will work in Linux.
• This method requires full Kernel source (see your distribution documentation for specific instructions to acquire and configure)

1) Open the ftdi_sio.h file for editing located in your kernel source directory.
(<source>/drivers/usb/serial/ftdi_sio.h)

2) Search for SEALEVEL_VID. This will bring you to a list of #define‘s for Sealevel USB serial devices.

3) Add new entries for each Sealevel listing discovered with the lspci command as described in Step 3 of the previous section.

...
#define SEALEVEL_2803_8_PID 0x2883 // SeaLINK+8 2803
#define SEALEVEL_E402_PID   0xE402 // << adding new E402 product ID
...

4) Close and save the changes to the header file.

5) Next open the ftdi_sio.c file for editing. It is located in the same directory as the header file.

6) Search for SEALEVEL_VID. This will bring you to an array of vendor/product id structures.

7) Add new entries for each new #define added in Step 3.

...
{ USB_DEVICE(SEALEVEL_VID, SEALEVEL_2803_8_PID) },
{ USB_DEVICE(SEALEVEL_VID, SEALEVEL_E402_PID) }, // << adding new E402 ID
...

8) Now recompile kernel driver modules. Consult your specific distribution documentation.

# cd <source>
# make modules && make modules_install

9) Now reload the ftdi_sio kernel module.

# modprobe -r ftdi_sio
# modprobe ftdi_sio

10) Continue from Step 6 of Option 1 above.

Option 3: Serial USB Installation Instructions (Non-persistent)

Notes:

• This method does not make any permanent changes to the system. It will not persist through a system reboot.
• This method assumes the Sealevel device is connected to the system
• The device used in this example is a 2801.
• To automate the process, download the bash script here. See README.txt for more details.
• Load ftdi_sio driver.

root@it:/home/it# modprobe ftdi_sio

• Search for connected Sealevel USB devices.

root@it:/home/it# lsusb -d 0c52:
   Bus   004 Device 018: ID 0c52:a022 Sealevel Systems, Inc.
   Bus   004 Device 019: ID 0c52:a023 Sealevel Systems, Inc.
   Bus   004 Device 020: ID 0c52:a024 Sealevel Systems, Inc.
   Bus   004 Device 021: ID 0c52:a025 Sealevel Systems, Inc.

• Add each device ID (a022 – a025 in this example) associated with a Sealevel USB Serial device to the ID mapping file.

root@it:/home/it# printf "0c52 a02%s\n" {2..5} > /sys/bus/usb-serial/drivers/ftdi_sio/new_id

• Validate that all ttyUSB ports are present.

root@it:/home/it# ls /dev/ttyU*
/dev/ttyUSB0  /dev/ttyUSB2  /dev/ttyUSB4  /dev/ttyUSB6
/dev/ttyUSB1  /dev/ttyUSB3  /dev/ttyUSB5  /dev/ttyUSB7