Serial port programming

Jump to: navigation, search

This is a step-by-step guide to using the serial port from a program running under Linux; it was written for the Raspberry Pi serial port with the Raspbian Wheezy distribution. However, the same code should work on other systems.

Step 0: Note whether your Raspberry Pi has Wireless/Bluetooth capability

By default the Raspberry Pi 3 and Raspberry Pi Zero W devices use the more capable /dev/ttyACM0 to communicate over bluetooth, so if you want to program the serial port to control the IO pins on the header, you should use the auxiliary UART device /dev/ttyS0 instead. On these wireless devices, it is possible switch the GPIO serial port back to /dev/ACM0 with `/boot/config.txt` directives by disabling bluetooth with `bdtoverlay=`pi3-disable-bt` or by forcing the bluetooth to use the mini-UART with `dtoverlay=pi3-miniuart-bt`. See for details.

Step 1: Connect to a terminal emulator using a PC

Follow the instructions at RPi_Serial_Connection#Connections_and_signal_levels, and RPi_Serial_Connection#Connection_to_a_PC, so that you end up with your Pi's serial port connected to a PC, running a terminal emulator such as minicom or PuTTY.

The default Wheezy installation sends console messages to the serial port as it boots, and runs getty so you can log in using the terminal emulator. If you can do this, the serial port hardware is working.


Problem Possible causes
Nothing at all shown on terminal emulator Connected to wrong pins on GPIO header

Faulty USB-serial cable or level shifter

/boot/cmdline.txt and /etc/inittab have already been edited (see below)

Flow control turned on in terminal emulator

Wrong baud rate in terminal emulator

Text appears corrupted Wrong baud rate, parity, or data settings in terminal emulator

Faulty level shifter

Can receive but not send

(nothing happens when you type)

Connected to wrong pins on GPIO header

Flow control turned on in terminal emulator

Faulty level shifter

Step 2: Test with Python and a terminal emulator

You will now need to edit files /etc/inittab and /boot/cmdline.txt as described at RPi_Serial_Connection#Preventing_Linux_using_the_serial_port. When you have done this - remember to reboot after editing - the terminal emulator set up in Step 1 will no longer show any output from Linux - it is now free for use by programs. Leave the terminal emulator connected and running throughout this step.

We will now write a simple Python program which we can talk to with the terminal emulator. You will need to install the PySerial package:

sudo apt-get install python-serial

Now, on the Raspberry Pi, type the following code into a text editor, taking care to get the indentation correct (Note that for devices with wireless (3, zero W) you must use /dev/ttyS0 instead of /dev/ttyAMA0):

import serial

port = serial.Serial("/dev/ttyAMA0", baudrate=115200, timeout=3.0)

while True:
    port.write("\r\nSay something:")
    rcv =
    port.write("\r\nYou sent:" + repr(rcv))

Save the result as file, and then run it with:


If all is working, you should see the following lines appearing repeatedly, one every 3 seconds, on the terminal emulator:

Say something:
You sent:''

Try typing some characters in the terminal emulator window. You will not see the characters you type appear straight away - instead you will see something like this:

Say something:
You sent:'abcabc'

If you typed Enter in the terminal emulator, it will appear as the character sequence \r - this is Python's way of representing the ASCII "CR" (Control-M) character.


Problem Possible causes
Python error "No module named serial" python-serial package not installed
Python error "[Errno 13] Permission denied: '/dev/ttyAMA0" User not in group 'dialout'

getty is still running (from /etc/inittab)

/dev/ttyAMA0 doesn't have rw access by group 'dialout'

For other problems (e.g. text appears corrupted) refer to the troubleshooting table in Step 1.

More about reading serial input

The serial connection we are using above is:

  • bi-directional - the PC transmits characters (actually, 8-bit values which are interpreted as ASCII characters) which are received by the Pi, and the Pi can transmit characters which are received by the PC.
  • full-duplex - meaning that the PC-to-Pi transmission can happen at the same time as the Pi-to-PC transmission
  • byte-oriented - each byte is transmitted and received independently of the next byte. In other words, the serial communication does not group transmitted data into packets, or lines of text; if you want to send messages longer than one byte, you will need to add your own means of grouping bytes together.

So, the line rcv = will wait for characters to arrive from the PC, and:

  • if it has read 10 characters, the call to read() will finish, returning those 10 characters as a string.
  • if it has been waiting for the timeout period given to serial.Serial() - in this case, 3 seconds - it will return whatever characters have arrived so far. (If no characters arrive, this will return an empty string).

Any characters which arrive after the read() call has finished will be saved (buffered) by the kernel and can be retrieved the next time you call read(). However, there is a limit to how many characters can be saved; once the buffer is full characters will be lost.

This means that a call such as is only useful if you know the transmitting end is going to send exactly 10 bytes of data; if it sends more that 10, they will not be returned from the call, and if it sends fewer than 10, your program will pause until the timeout has expired.

Using the readline() call

If you are reading data from the serial port organised as (possibly variable-length) lines of text, you may want to use PySerial's readline() method. To see the effect of this, replace the rcv = with rcv = port.readline() in the program above.

The documentation for readline() says it will receive characters from the serial port until a newline (Python '\n') character is received; when it gets one it returns the line of text it has got so far. You may expect, therefore, that typing a few characters on the terminal emulator, followed by the Enter key, will return those characters immediately.

However, on many terminal emulators this won't work! Pressing the Enter key sends an ASCII CR (13 decimal, Control-M) character, but a newline character is ASCII LF (10 decimal, Control-J). So, readline() will not finish until you type Control-J in the terminal (or until the timeout has expired).

PySerial's documentation gives various means of reading other newline characters; however, the most reliable solution is to do it yourself:

import serial
import time

def readlineCR(port):
    rv = ""
    while True:
        ch =
        rv += ch
        if ch=='\r' or ch=='':
            return rv

port = serial.Serial("/dev/ttyAMA0", baudrate=115200, timeout=3.0)

while True:
    port.write("\r\nSay something:")
    rcv = readlineCR(port)
    port.write("\r\nYou sent:" + repr(rcv))