You are on page 1of 5

3/20/2014 Serial port programming - eLinux.

org 1/5
Serial port programming
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
1 Step 1: Connect to a terminal emulator using a PC
1.1 Troubleshooting
2 Step 2: Test with Python and a terminal emulator
2.1 Troubleshooting
2.2 More about reading serial input
2.3 Using the readline() call
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.
3/20/2014 Serial port programming - 2/5
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:
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:
3/20/2014 Serial port programming - 3/5
If all is working, you should see the following lines appearing repeatedly, one every 3 seconds, on the terminal
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:
User not in group 'dialout'
getty is still running (from /etc/inittab)
/dev/ttyAMA0 doesn't have rw access by group
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
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
3/20/2014 Serial port programming - 4/5
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
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))
Retrieved from ""
This page was last modified on 20 April 2013, at 10:11.
This page has been accessed 32,783 times.
Content is available under a Creative Commons Attribution-ShareAlike 3.0 Unported License unless
3/20/2014 Serial port programming - 5/5
otherwise noted.