Setserial Command on Linux with Examples

Serial ports might seem like a relic of the past in today’s wireless world, but they remain crucial for many Linux systems. From connecting legacy hardware to configuring embedded systems, understanding how to manage serial ports is an essential skill for Linux administrators and enthusiasts. The setserial command provides powerful functionality for viewing and configuring serial port parameters in Linux environments. This comprehensive guide explores everything you need to know about using the setserial command effectively.

Understanding Serial Ports in Linux

Before diving into the setserial command, it’s important to understand how serial ports function in Linux systems. Serial communication involves transferring data one bit at a time over a communication channel, making it simpler but slower than parallel communication methods.

Serial Port Basics

In Linux, serial ports are represented as device files in the /dev directory. The traditional hardware serial ports are named /dev/ttyS0 through /dev/ttyS3, corresponding to COM1 through COM4 in Windows systems. USB-to-serial adapters typically appear as /dev/ttyUSB0, /dev/ttyUSB1, and so on, while modern USB devices using the Abstract Control Model are represented as /dev/ttyACM0 and similar.

Serial Port Parameters

For successful serial communication, several key parameters must be configured correctly:

• Baud rate: Controls communication speed (bits per second)
• Data bits: Defines the number of bits per character (typically 7 or 8)
• Parity: Provides error detection (none, odd, or even)
• Stop bits: Signals the end of a character (usually 1 or 2)
• Flow control: Regulates data transmission between devices

These parameters must match between communicating devices to ensure proper data exchange. The setserial command plays a vital role in configuring and verifying these settings.

Installation and Availability

The setserial command isn’t included by default in all Linux distributions, so you might need to install it manually.

Installing Setserial

For Debian/Ubuntu-based systems:

sudo apt-get install setserial

For CentOS/RHEL 7:

sudo yum install setserial

For CentOS 8 or newer:

sudo dnf install setserial

For Arch Linux-based systems:

sudo pacman -S setserial

Verifying Installation

After installation, verify that setserial is properly installed by checking its version:

setserial -V

The command should display version information, confirming successful installation.

Distribution Compatibility

The setserial command works across most Linux distributions, including:

• Debian and Ubuntu
• Red Hat, CentOS, and Fedora
• Arch Linux and Manjaro
• Alpine Linux
• Kali Linux
• Raspbian

While the core functionality remains consistent, some feature variations might exist between different distributions.

Basic Syntax and Options

Understanding the command structure and available options is essential for effective use of setserial.

Command Structure

The basic syntax of the setserial command follows this pattern:

setserial [options] device [parameter1 [arg]] ...

Here, device refers to the serial port (e.g., /dev/ttyS0), and parameter1 [arg] specifies the settings you wish to configure.

Common Options

The setserial command supports several options that modify its behavior:

Important Parameters

Several key parameters can be configured with setserial:

• port <address>: Sets the I/O port address (e.g., 0x3f8)
• irq <number>: Assigns an Interrupt Request (IRQ) line
• uart <type>: Specifies the UART type (e.g., 16550A)
• baud_base <rate>: Sets the base baud rate
• spd_normal, spd_hi, spd_vhi, spd_shi: Configures predefined speed settings
• divisor <n>: Sets a custom divisor for baud rate calculation
• autoconfig: Automatically detects and configures port settings

Mastering these options and parameters is crucial for effective serial port management in Linux.

Viewing Serial Port Information

The setserial command provides various ways to retrieve information about serial ports on your system.

Listing Available Serial Ports

To get a quick overview of all serial ports, use the -g option with a wildcard:

setserial -g /dev/ttyS[0-9]

This displays basic information for serial ports from ttyS0 through ttyS9, helping you identify which ports are available on your system.

Detailed Port Information

For comprehensive details about a specific serial port, use the -a option:

setserial -a /dev/ttyS0

This command reveals detailed configuration including:

• UART type and capabilities
• Port address and IRQ assignment
• Baud rate settings and divisor values
• Various flags affecting port behavior

A typical output might look like:

/dev/ttyS0, Line 0, UART: 16550A, Port: 0x03f8, IRQ: 4
Baud_base: 115200, close_delay: 50, divisor: 0
closing_wait: 3000
Flags: spd_normal skip_test

Formatted Output for Scripting

When you need to capture port information for use in scripts or configuration files, the -G option formats the output as reusable command arguments:

setserial -G /dev/ttyS0

This produces output that can be directly fed back to setserial as command arguments:

/dev/ttyS0 uart 16550A port 0x03f8 irq 4 baud_base 115200 spd_normal skip_test

Checking Multiple Ports

To compare configurations across multiple ports:

setserial -g /dev/ttyS0 /dev/ttyS1 /dev/ttyS2

This consolidated view helps identify inconsistencies or conflicts between serial ports.

Configuring Serial Port Parameters

Proper configuration of serial port parameters is essential for successful communication with attached devices.

Setting Basic Port Parameters

To configure fundamental port settings:

Set the I/O port address:

setserial /dev/ttyS0 port 0x3f8

Assign an IRQ line:

setserial /dev/ttyS0 irq 4

Specify the UART type:

setserial /dev/ttyS0 uart 16550A

These basic settings define how the serial port interfaces with the system hardware.

Configuring Baud Rate Settings

The baud rate determines communication speed and can be configured in several ways:

Set the base baud rate:

setserial /dev/ttyS0 baud_base 115200

Use predefined speed settings:

setserial /dev/ttyS0 spd_normal    # Standard speed
setserial /dev/ttyS0 spd_hi        # High speed (38400 bps)
setserial /dev/ttyS0 spd_vhi       # Very high speed (57600 bps)
setserial /dev/ttyS0 spd_shi       # Super high speed (115200 bps)

For custom baud rates, use the divisor parameter:

setserial /dev/ttyS0 spd_cust divisor 2

The actual baud rate is calculated as baud_base ÷ divisor.

Advanced Configuration Options

For specialized requirements, additional parameters provide fine-grained control:

Configure closing behavior:

setserial /dev/ttyS0 closing_wait 30
setserial /dev/ttyS0 close_delay 50

Enable low latency mode (disables FIFO buffers):

setserial /dev/ttyS0 low_latency

Automatically detect port configuration:

setserial /dev/ttyS0 autoconfig

These advanced options allow precise tuning for optimal performance with specific hardware devices and applications.

Persistent Configuration

By default, changes made with setserial are temporary and will be lost after system reboot. Several methods exist to make configurations permanent.

Using /etc/serial.conf

In modern distributions (setserial version 2.15 and later), the recommended approach is to use the serial.conf configuration file:

1. Create or edit the serial configuration file:

   sudo nano /etc/serial.conf

2. Add your configuration line:

   /dev/ttyS0 uart 16550A port 0x3f8 irq 4 baud_base 115200 spd_normal

3. Ensure that the serial service is enabled to run at boot:

   sudo systemctl enable serial-getty@ttyS0.service

For automatic saving of configurations, make sure “###AUTOSAVE###” or similar text appears on the first line of serial.conf.

Using rc.local for Older Systems

On systems using traditional init scripts:

1. Edit the rc.local file:

   sudo nano /etc/rc.local

2. Add your setserial commands before the exit 0 line:

   setserial /dev/ttyS0 uart 16550A port 0x3f8 irq 4 baud_base 115200

3. Make sure rc.local is executable:

   sudo chmod +x /etc/rc.local

Distribution-Specific Configurations

Different Linux distributions may use different methods for persistent configuration:

• In Debian-based systems, look for a file named 0setserial in the startup scripts
• In Red Hat-based systems prior to version 6.0, configuration might be in /usr/doc/setserial/ and need to be moved to the /etc directory
• Some distributions might use /etc/rc.d/rc.serial or similar scripts

Use the locate command to find relevant files:

locate "*serial*"

This helps identify configuration files specific to your distribution.

Practical Examples with Use Cases

Let’s explore real-world applications of the setserial command through practical examples.

Example 1: Identifying Hardware Serial Ports

When working with new or unknown hardware, it’s helpful to identify all available serial ports:

setserial -g -a /dev/ttyS*

This provides a comprehensive view of all serial ports, their UART types, addresses, and IRQ assignments, helping determine which ports are physically present on the system.

Example 2: Setting Up a Serial Console

To configure a serial port for use as a console connection:

setserial /dev/ttyS0 uart 16550A port 0x3f8 irq 4 baud_base 115200 spd_normal

This prepares the port for use as a console, which is particularly useful for headless servers or remote system management.

Example 3: Configuring a Legacy Device

For older equipment with specific requirements:

setserial /dev/ttyS1 uart 16450 port 0x2f8 irq 3 baud_base 9600 spd_normal

This ensures compatibility with legacy devices that might not support modern UART features or higher speeds.

Example 4: High-Speed Data Acquisition

For applications requiring maximum throughput:

setserial /dev/ttyS0 uart 16550A port 0x3f8 irq 4 baud_base 921600 low_latency

The low_latency option disables FIFO buffering, reducing latency for time-sensitive applications and enabling higher data transfer rates.

Example 5: Troubleshooting an Unresponsive Port

When a port isn’t responding as expected:

setserial /dev/ttyS0 autoconfig

This attempts to automatically detect and apply appropriate settings based on hardware capabilities, which can resolve configuration mismatches.

These examples demonstrate the versatility of the setserial command in addressing various serial communication scenarios.

Troubleshooting Common Issues

Serial port communication can be complex, with several potential points of failure. Here are solutions to common problems.

Hardware Detection Problems

If setserial reports “unknown” for the UART type, several issues might be at play:

• The physical serial port might not exist at the specified address
• The port could be disabled in BIOS settings
• There might be a hardware failure

Verify physical connections and BIOS settings before proceeding with software troubleshooting.

IRQ Conflicts

When multiple devices share an IRQ line, communication issues may arise. To identify conflicts:

cat /proc/interrupts

If conflicts are detected, reassign IRQs using setserial:

setserial /dev/ttyS0 irq 5

You can also test if IRQ conflicts are the issue by temporarily setting the IRQ to 0 (polling mode):

setserial /dev/ttyS0 irq 0

If this resolves the issue, it confirms an IRQ conflict, though polling mode should not be used permanently as it increases CPU load.

Permission Issues

Serial port access requires appropriate permissions. If you encounter “Permission denied” errors:

sudo usermod -a -G dialout $USER

Log out and back in to apply group changes.

Baud Rate Mismatches

If data appears garbled or corrupted, check for baud rate mismatches:

setserial -a /dev/ttyS0 | grep Baud_base

Ensure both communicating devices use identical baud rates and communication parameters.

Boot-Time Configuration Issues

If settings don’t persist after rebooting, verify your configuration file:

cat /etc/serial.conf

And ensure the serial service is enabled:

systemctl status serial-getty@ttyS0.service

These troubleshooting techniques address the most common issues encountered when working with serial ports in Linux.

Integration with Other Linux Tools

The setserial command works best when used alongside other Linux utilities for comprehensive serial port management.

Using Setserial with Stty

While setserial configures hardware parameters, stty manages terminal settings:

setserial /dev/ttyS0 baud_base 115200
stty -F /dev/ttyS0 115200 cs8 -parenb -cstopb

This combination provides complete control over both hardware and software aspects of serial communication.

Monitoring with Dmesg

The kernel ring buffer often contains valuable diagnostic information:

dmesg | grep tty

This helps identify driver loading issues and hardware detection problems.

Hardware Information with lspci and lsusb

For USB-to-serial adapters:

lsusb | grep -i serial

For PCI serial cards:

lspci | grep -i serial

These commands help identify hardware details and verify that devices are properly recognized by the system.

Testing Connections with Screen

The screen utility can test bidirectional communication:

screen /dev/ttyS0 115200

This opens a terminal connection using the specified serial port, allowing direct interaction with connected devices.

Advanced Testing with Minicom

For comprehensive testing and configuration:

minicom -D /dev/ttyS0 -b 115200

This terminal emulator offers advanced features for serial communication testing, including file transfer capabilities and connection monitoring.

Combining setserial with these tools creates a powerful toolkit for managing serial communication in Linux environments.