Revision as of 19:14, 31 October 2008

Contents

Introduction

grabserial is a small program which reads a serial port and writes the
data to standard output. The main purpose of this tool is to collect
messages written to the serial console from a target board running
Linux, and save the messages on a host machine.

Download and Installation

Grabserial requires the python "serial" module. This module is not shipped with
most distributions of python by default. Here's a copy you can install
if you don't have it. (You can check if you already have it by typing:
'python', then "import serial" in the interactive python interpreter.

To install this, download the archive, unzip it, and following the installation
instructions in pyserial-2.2/README.txt.

The latest Pyserial can be obtained from: [1]
The latest version as of this writing is 2.4, which is newer than what I've
got here.

Usage

The grabserial program is very simple, but it provides some useful
extra features that make it more than a mere 'cat' program.

Use 'grabserial -h' to see online usage for the program.

You can special the serial configuration options, including the Linux
device node to use, and the port speed settings on the grabserial
command line. If no options are specified, grabserial uses serial port
/dev/ttyS0, at 115200 baud with "8, None and 1" (8N1)
settings.

Normally, the program runs in an infinite loop,
reading from the serial port and writing to standard out until it is
interrupted by the user (usually by typing control-C). However, you
can tell the program to stop after a certain amount of time. This is
useful for including the script in automated test scenarios.

Also, you can tell the program to provide timing information for each
line received. This is useful to measure the time it takes for events
to happen on the target. A common thing to measure on
a target running embedded Linux is bootup time.
With grabserial, you can specify a pattern
to match against the lines read from the serial port. When this
pattern is seen, it sets a "base time", and all subsequent time values
printed out will be relative to this base. Thus, you can customize
the start time for the time measurements, to make it easier to see the
duration of events in the system.

Usage Examples

Here are some examples of use:

grabserial

This will echo data seen on device /dev/ttyS0, until the user pressed ctrl-C.

This opens /dev/ttyUSB0, at baud rate 115200, and 8-bit chars, No parity and 1 stop bit.
This will capture and display data for 30 seconds, putting a timestamp on each line
received, and restarting the timestamp at 0 when a line containing "Kernel start" is seen.
The '-v' makes grabserial verbose (printing some extra messages before starting.

Sample Output

Here is sample output from grabserial. This shows the reboot of an ARM-based system (OMAP Starter Kit).
Note that the U-Boot prompt appears at time 1.084614. The grabserial command specifies to restart the
timestamps when "Starting kernel.*" is seen. This happens at time 11.557150 after grabserial was started.

Note that the first kernel message appears 3.14 seconds later. Actually, the kernel starts well before this,
but it takes this long before the kernel to initialize the serial port and start emitting messages. You will
notice that a bunch of messages come out in rapid succession. These are messages that were queued up during
the boot, before the serial console was initialized.