Serial Port Troubleshooting on Linux

A serial port (i.e. for programming a microcontroller) can have multiple resons why it is not working. This guide will try to cover most cases with a few questions.

Hints

It is always a good idea to try to look up the problem in your distributions wiki/documentation first!

You can manually connect to a serial port using screen /dev/ttySomething. Quit with Ctrl+a and pressing k after that.

Is your Serial port showing up?

Use ls /dev/tty* to get a list of terminal devices on your Linux machine. If you find a ttyUSB0 or a ttyACM0 that is a usb to serial converter and you can probably skip this section.

lsusb will give you a list of connected USB devices, if you microcontroller is not among them you either have a bad cable, a bad microcontroller or (for some micros) the controller is not in programming mode.

If the device shows up in lsusb but there is no serial port, you have a driver problem.

Is it the correct Serial port?

Sometimes you have more than one device attached, make sure you are trying to talk to the right one. If you unplug your device and the port still shows up you are trying to talk to the wrong device.

Driver Problems

Do you need a reboot?

If you are not using a very uncommon setup check if /lib/modules (the directory kernel modules are in) contains a directory called the same as the output of uname -r (the version of the currently running kernel).

If that is not the case your package manager has cleaned up the old modules during an update and you have not rebooted yet (still running the old kernel). The solution in this case is a reboot, then the hardware management will be able to find the modules the kernel needs because the running version matches the version of the modules in the filesystem.

Missing Package

If a reboot did or would not fix your problem try searching for a driver package (usually the package name contains ftdi for USB to serial adaptors).

Do you have permission for accessing serial ports?

By default on many distributions the hardware management comes preconfigured in a way that only permits users in the dialout group to use serial ports. Check if are a member of that group using the groups command.

Note: the dialout group may have a different name on some distributions. (look up serial ports in the distributions wiki).

You can give a user permission by running sudo usermod -a -G dialout <name> and logging out and back in after that.

Is something else using the port?

Since a program doesn't really know what is on the other side of a serial port some programs simply connect and try to find out which may interfere with whatever you are trying to do.

One of these is brltty which is preconfigured by most big distributions to do exactly that to make sure plugging a braille display into an USB port is equivalent to plugging a screen into a HDMI port. (which is very good, your little arduino isn't nearly as important!)

To fix that behaviour either configure the "offending" program or stop (and disable) the service it belongs to if you don't need it.

Example of how to disable and stop the brltty service on most systemd based distributions.
Do not do this if you rely on a working braille display!
sudo systemctl disable --now brltty