Difference between revisions of "Scanserial"

From wiki.emacinc.com
Jump to: navigation, search
m (Corrected TODO tag.)
m (Initial Content.)
Line 1: Line 1:
{{todo| NotStarted (11.04.2015-12:17->MD+)|Mike Dean| project=OE 5.0,MD,NotStarted }}
+
{{todo| InProgress (11.04.2015-12:17->MD+)|Mike Dean| project=OE 5.0,MD,InProgress }}
 
{{#seo:
 
{{#seo:
 
|title=scanserial
 
|title=scanserial
Line 10: Line 10:
 
<!-- /****************************************  Page Description Text  ****************************************/ -->
 
<!-- /****************************************  Page Description Text  ****************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
<span style="background:#00FF00;color:#FF0000;font-size:300%">'''''Put the page description text here.'''''</span>
+
EMAC provides a tool named <code>scanserial</code> to assist a user in finding out which device nodes on a computer correspond to its serial ports, and in finding out which particular device node corresponds to a particular serial port.  The <code>scanserial</code> tool was created because no existing tool provides this functionality in a convenient way.  Other methods for determining this all require a slow trial and error approach.
 +
 
 +
This guide walks the reader through the steps required to perform these tasks using the EMAC <code>scanserial</code> tool.
  
 
__TOC__
 
__TOC__
Line 18: Line 20:
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
{{:Templateimpl:bg | initials=MD | title=scanserial | desc=Using scanserial to find your serial ports. | project=OE 5.0 }}
 
{{:Templateimpl:bg | initials=MD | title=scanserial | desc=Using scanserial to find your serial ports. | project=OE 5.0 }}
 +
 +
Linux systems use virtual files to provide device nodes which represent hardware devices attached to a system.  These device nodes reside in the <code>/dev</code> directory.  Each device node corresponds to one device, or to one endpoint within a device.
 +
 +
The serial ports typically are represented by device nodes with one of the two following naming schemes:
 +
 +
;Standard Serial Devices
 +
: <code>/dev/ttyS</code>*
 +
;USB Serial Devices
 +
: <code>/dev/ttyUSB</code>*
 +
 +
Any given system may have one or both of these types of serial devices attached to it.  Serial ports provided by a motherboard or add-in PCI/PCIe card are classified in this document as Standard Serial Devices.  USB to serial devices, including USB devices which provide several serial ports, are classified in this document as USB Serial Devices.
 +
 +
Serial devices normally provide a character device (rather than a block or FIFO).  Each device node describes the type of device it is associated with, in this case character, and has an associated major and minor magic number.  The magic numbers are used to identify to the operating system kernel the specific device on the system to which the device node corresponds.  Further details about device nodes are beyond the scope of this document, but can be found on this site and elsewhere in documentation on Linux device drivers.
  
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
Line 23: Line 38:
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
{{:Templateimpl:geninfo | initials=MD | title=scanserial | desc=Using scanserial to find your serial ports. | project=OE 5.0 }}
 
{{:Templateimpl:geninfo | initials=MD | title=scanserial | desc=Using scanserial to find your serial ports. | project=OE 5.0 }}
 +
 +
The <code>scanserial</code> tool is provided by EMAC to assist customers in getting a development environment set up.  Since <code>scanserial</code> is an EMAC provided tool, you will need to install it unless you are using an EMAC LDC (which has it pre-installed).
 +
 +
If your Ubuntu machine isn't already configured to use the EMAC apt repository for installing software, you will need to [[Getting_Started_with_the_EMAC_OE_SDK| follow this guide]] on how to do so.  When your system is configured for the EMAC apt repository, you can install the <code>scanserial</code> tool by installing the <code>emac-tools-util</code> project.  To install it with <code>apt-get</code> on the command line, run:
 +
 +
{{cli|username=developer|hostname=developerpc| sudo apt-get install emac-tools-util}}
 +
 +
Alternatively, you may open the Ubuntu Software Center and search for the <code>emac-tools-util</code> project.  Clicking on the search result will provide you with an option to install the package.  Click the <b>Install</b> button to install it.
  
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
Line 28: Line 51:
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
{{:Templateimpl:using | initials=MD | title=scanserial | desc=Using scanserial to find your serial ports. | project=OE 5.0 }}
 
{{:Templateimpl:using | initials=MD | title=scanserial | desc=Using scanserial to find your serial ports. | project=OE 5.0 }}
 +
 +
The <code>scanserial</code> utility has a few options which allow you to customize the behavior of <code>scanserial</code> or find out more about it.  The list below describes these options.
 +
 +
;-v, --verbose
 +
: Display verbose output.  When displaying a list of devices, this will show metadata associated with each device node.
 +
 +
;-c, --color
 +
: Displays output in color (if available).
 +
 +
;-f, --find-loopback
 +
: Uses the same algorithm which is used to find a list of serial port device nodes, then scans the list of device nodes for loopback devices.  Displays every  device it finds which appears to have a loopback attached.  Note that this can be fooled by connected devices which echo input back to the port, such as a logged in console on a board.
 +
 +
;-h, --help
 +
: Displays help for using the scanserial tool.
 +
 +
;-l, --list-serials
 +
: Lists the serial device nodes found in /dev which appear to be serial ports.  If combined with the verbose option, this will also show metadata about each one.  Add the color switch to colorize the output to make it easier to read.
 +
 +
;--version
 +
: Displays the version number of the scanserial tool.
 +
 +
====Return Value====
 +
 +
The return value of <code>scanserial</code> corresponds to the success of its operation.  If the operation succeeded, it returns zero, as is the customary behavior for all *nix software.  If it fails, it will return a value greater than zero (which is also the standard behavior for software on Linux systems).
  
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
Line 33: Line 80:
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->
 
{{:Templateimpl:examples | initials=MD | title=scanserial | desc=Using scanserial to find your serial ports. | project=OE 5.0 }}
 
{{:Templateimpl:examples | initials=MD | title=scanserial | desc=Using scanserial to find your serial ports. | project=OE 5.0 }}
 +
 +
====Listing Available Serial Ports====
 +
 +
Use the <code>-l</code> (lowercase L) option to list available serial ports.  Here, there are 8 standard serial ports and 8 USB serial ports available.
 +
 +
{{clo}}
 +
{{clio|username=developer|hostname=developerpc|scanserial -l}}
 +
/dev/ttyS0/dev/ttyS1/dev/ttyS4/dev/ttyS5/dev/ttyS6/dev/ttyS7/dev/ttyUSB0/dev/ttyUSB1/dev/ttyUSB2/dev/ttyUSB3/dev/ttyUSB4/dev/ttyUSB5/dev/ttyUSB6/dev/ttyUSB7
 +
{{clos}}
 +
 +
====Listing Detailed Information About Serial Ports====
 +
 +
The verbose option, <code>--verbose</code> or <code>-v</code>, causes <code>scanserial</code> to output much more detailed information.
 +
 +
{{clop}}
 +
{{cliop | username=developer | hostname=developerpc | scanserial -lv }}
 +
 +
{{closp}}
 +
 +
''Further output was truncated for the sake of brevity in this example.''
 +
 +
  
 
<!-- /*********************************************************************************************************/ -->
 
<!-- /*********************************************************************************************************/ -->

Revision as of 17:15, 4 November 2015

TODO: {{#todo: InProgress (11.04.2015-12:17->MD+)|Mike Dean|OE 5.0,MD,InProgress}}

EMAC provides a tool named scanserial to assist a user in finding out which device nodes on a computer correspond to its serial ports, and in finding out which particular device node corresponds to a particular serial port. The scanserial tool was created because no existing tool provides this functionality in a convenient way. Other methods for determining this all require a slow trial and error approach.

This guide walks the reader through the steps required to perform these tasks using the EMAC scanserial tool.

Background

Linux systems use virtual files to provide device nodes which represent hardware devices attached to a system. These device nodes reside in the /dev directory. Each device node corresponds to one device, or to one endpoint within a device.

The serial ports typically are represented by device nodes with one of the two following naming schemes:

Standard Serial Devices
/dev/ttyS*
USB Serial Devices
/dev/ttyUSB*

Any given system may have one or both of these types of serial devices attached to it. Serial ports provided by a motherboard or add-in PCI/PCIe card are classified in this document as Standard Serial Devices. USB to serial devices, including USB devices which provide several serial ports, are classified in this document as USB Serial Devices.

Serial devices normally provide a character device (rather than a block or FIFO). Each device node describes the type of device it is associated with, in this case character, and has an associated major and minor magic number. The magic numbers are used to identify to the operating system kernel the specific device on the system to which the device node corresponds. Further details about device nodes are beyond the scope of this document, but can be found on this site and elsewhere in documentation on Linux device drivers.

General Information

The scanserial tool is provided by EMAC to assist customers in getting a development environment set up. Since scanserial is an EMAC provided tool, you will need to install it unless you are using an EMAC LDC (which has it pre-installed).

If your Ubuntu machine isn't already configured to use the EMAC apt repository for installing software, you will need to follow this guide on how to do so. When your system is configured for the EMAC apt repository, you can install the scanserial tool by installing the emac-tools-util project. To install it with apt-get on the command line, run:

developer@developerpc:~# sudo apt-get install emac-tools-util

Alternatively, you may open the Ubuntu Software Center and search for the emac-tools-util project. Clicking on the search result will provide you with an option to install the package. Click the Install button to install it.

scanserial

The scanserial utility has a few options which allow you to customize the behavior of scanserial or find out more about it. The list below describes these options.

-v, --verbose
Display verbose output. When displaying a list of devices, this will show metadata associated with each device node.
-c, --color
Displays output in color (if available).
-f, --find-loopback
Uses the same algorithm which is used to find a list of serial port device nodes, then scans the list of device nodes for loopback devices. Displays every device it finds which appears to have a loopback attached. Note that this can be fooled by connected devices which echo input back to the port, such as a logged in console on a board.
-h, --help
Displays help for using the scanserial tool.
-l, --list-serials
Lists the serial device nodes found in /dev which appear to be serial ports. If combined with the verbose option, this will also show metadata about each one. Add the color switch to colorize the output to make it easier to read.
--version
Displays the version number of the scanserial tool.

Return Value

The return value of scanserial corresponds to the success of its operation. If the operation succeeded, it returns zero, as is the customary behavior for all *nix software. If it fails, it will return a value greater than zero (which is also the standard behavior for software on Linux systems).

Examples

Listing Available Serial Ports

Use the -l (lowercase L) option to list available serial ports. Here, there are 8 standard serial ports and 8 USB serial ports available.

developer@developerpc:~# scanserial -l

/dev/ttyS0/dev/ttyS1/dev/ttyS4/dev/ttyS5/dev/ttyS6/dev/ttyS7/dev/ttyUSB0/dev/ttyUSB1/dev/ttyUSB2/dev/ttyUSB3/dev/ttyUSB4/dev/ttyUSB5/dev/ttyUSB6/dev/ttyUSB7

Listing Detailed Information About Serial Ports

The verbose option, --verbose or -v, causes scanserial to output much more detailed information.

developer@developerpc:~# scanserial -lv

Further output was truncated for the sake of brevity in this example.


Conclusion

Further Information

Where to Go Next
Pages with Related Content