# &app; Manual V&manualversion;

2009 Michael J. Chudobiak
GNOME Documentation Project &legal;
Michael Chudobiak

     mjc@svn.gnome.org

&manualversion;
&date;

Michael J. Chudobiak

GNOME Documentation Project

This is manual describes version &appversion; of &appname;

&app; is a serial terminal for the GNOME desktop, optimized for logging and file capture.

## Introduction

&app; is a serial terminal for the GNOME desktop, optimized for logging and file capture. &app; is primarily intended for technical users who need to communicate with embedded systems, consoles, and electronic test equipment.

Despite the technical orientation of the intended audience, &app; is designed to be user-friendly. Care has been taken to ensure that operations are simple to execute, by minimizing the number of clicks needed. The number of configuration options has also been kept small.

To further improve efficiency, &app; also supports profile files to store frequently-used configurations.

## System Port Permissions

Before using &app; with a serial port, you need to make sure that you actually have permission to read and/or write to the port.

On some systems, you may need to do something like "sudo chmod o+rw /dev/ttyS*" and "sudo chmod o+rw /dev/ttyUSB*" to obtain read/write permissions (for all users) on the serial ports. Unfortunately, this may not be persistent after reboots.

Alternatively, you can see what group the devices belong to, and make your account a member of that group. In Fedora 15, for example, you should add yourself to the "dialout" group.

## Basic Usage

### The Main Toolbar

Most &app; functions are accessed through the main toolbar, shown below:

### Port Setup

The first step in using &app; is to configure the serial port parameters. Click Port Setup to do this. In the port setup dialog, you will set the port to use, whether the port should be open for reads, writes, or both, its baud rate, its parity, the number of data and stop bits, and the handshaking method. The settings specified in this dialog will override any system default settings for the port.

The &app; port setup dialog will only list the /dev/ttySnn, /dev/ttyUSBnn, and /dev/rfcommnn ports that actually exist on the system, for values of "nn" between 0 and 31.

A local echo can be enabled from this dialog. If enabled, all data that &app; receives will be echoed back to the sending device. This should normally be disabled, as it can cause unexpected behaviour, especially if the remote device also has echo enabled. (This would cause an infinite loop of echoes!)

### Open the Connection

The next step in communicating with your remote device is to click Connect. This opens the port. If you do not have the necessary privileges to open the port, an error will be reported.

This step is optional. If you skip it, &app; will try to connect automatically when needed.

Once you have connected, the Connect button will change into a Disconnect button. Clicking Disconnect closes the port, and resets the TX and RX counters.

### Basic Input and Output

Once the port has been opened, any text received from the remote device will be displayed in the Received ASCII text area. If &app; detects a large number of unprintable characters, it will switch automatically to the Received HEX view.

To switch between HEX and ASCII views, simply click on the appropriate tabs.

To send data to the remote device, you can type text into the Outgoing single-line text box, and click the Send button. Your line of text will be terminated with the sequence selected in the area to the right of the Send button. If you aren't sure which termination sequence is best, start with "CR+LF end". The ASCII/HEX button should be set to ASCII to send text.

If the ASCII/HEX button is set to HEX, do not enter text in the Outgoing area. Instead, enter hexadecimal numbers in the form "1234ABCD....".

Once your data has been transmitted, a record of it will exist in the Sent ASCII and Sent HEX text areas. These text areas are not editable.

The remote device may echo your sent data. If &app; detects echoed text in the Received ASCII text area, it will highlight the echoed text (using the highlight color defined in the preferences dialog).

The statusbar at the bottom of the main window shows the state of port, and a count of the sent (TX) and received (RX) bytes. If some of the received data is unprintable, a count of these items is shown as well.

## Recording Input and Output

&app; can be used to record your sent and received data to a file. This function is also useful for receiving and storing straight binary data dumped from a remote device. For instance, some oscilloscopes will dump screenshots to a serial port, without using any error correction protocols (like the Tektronix 11801).

When you are ready to record to a file, simply click Record, select the desired data to record (Incoming and/or Outgoing) in the Stream to Record selection box, and enter the filename in the filechooser area.

When recording begins, the Record button will change into a Stop Recording button. You will need to click this when you wish to stop recording, or you have received the entire binary file that you wanted to download.

&app; can optionally launch the recorded file with the default application for its file type, when recording has finished. It can also terminate recording after a period of inactivity. Use the Preferences dialog to enable or disable these features.

Note that if you wish to receive files using an error correction protocol (xmodem, ymodem, or zmodem), you will need to use the Receive File function instead. Unlike the Record function, the Receive File function can automatically determine when the file download is complete.

## Sending Files

&app; can transmit files in a straight binary data stream, and it can also send files using the xmodem, ymodem, and zmodem error correction protocols. During file transmission, the sent data is not logged to the Sent ASCII or Sent HEX text areas.

When you are ready to send a file, simply click Send File, select the desired file to send. You will also need to select the appropriate protocol below.

When recording begins, a progress bar will display the status of the file transmission.

moserial does not implement the xmodem, ymodem, or zmodem protocols directly. It relies on the standard rz and sz utilities to send and receive data. These utilities, part of the lrzsz package, must be installed on your system.

## Receiving Files

&app; can receive files sent in a straight binary data stream, and it can also receive files using the xmodem, ymodem, and zmodem error correction protocols. During file transmission, the received data is not logged to the Sent ASCII or Sent HEX text areas.

To receive straight binary data streams, use the Record function instead of the Receive File function.

To receive files sent with the xmodem, ymodem, or zmodem error correction protocols, using the Receive File function.

When you are ready to receive a file, simply click Receive File, select a folder to store the received file. You will also need to select the appropriate protocol below.

When recording begins, a progress bar will display the status of the file reception.

moserial does not implement the xmodem, ymodem, or zmodem protocols directly. It relies on the standard rz and sz utilities to send and receive data. These utilities, part of the lrzsz package, must be installed on your system.

## Other Preferences

&app; has several options that can be configured from the Preferences dialog.

The color of the text area foreground, background, and highlighting can be configured, as can the font type and size.

If Launch recorded files is enabled, a recorded file will be opened immediately after it is saved, using the default application for the file type. The default application is defined by the desktop environment.

If Enable timeout is enabled, recording will be automatically stopped after an adjustable period of inactivity after receiving some data. That is, moserial will wait indefinitely to record the first data byte before activating the inactivity timer.

## Using Profiles

&app; can load and save its settings from profile files, so that you can store and recall commonly used configurations. To save a profile, simply use the File Save or File Save As dialogs. To load a profile, use the File Open dialog.

Loading a profile will automatically disconnect any connected port.

When you quit &app;, the settings currently in use are stored in a default profile file. These settings will automatically be recalled the next time you launch &app;.

## Special Keys

Special Keys

Keyboard Shortcut | Description
--- | ---
Ctrl C | Copies text. This can be used in any of the text areas.
Ctrl X | Cuts text. This only works in the Outgoing single-line text box.
Ctrl V | Pastes text into the Outgoing single-line text box, and moves the focus to that text box.
Esc | Moves the focus to the Outgoing single-line text box.

&appname;
serial
terminal