# moserial Manual V3.0.0

2009
Michael J. Chudobiak
GNOME Documentation Project

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (GFDL), Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL at this link or in the file COPYING-DOCS distributed with this manual.

This manual is part of a collection of GNOME manuals distributed under the GFDL. If you want to distribute this manual separately from the collection, you can do so by adding a copy of the license to the manual, as described in section 6 of the license.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and the members of the GNOME Documentation Project are made aware of those trademarks, then the names are in capital letters or initial capital letters.

DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER UNDERSTANDING THAT:

1. DOCUMENT IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND

2. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.

Michael
Chudobiak

     mjc@svn.gnome.org

3.0.0
April 2009

Michael J. Chudobiak

GNOME Documentation Project

This is manual describes version 3.0.0 of moserial

moserial is a serial terminal for the GNOME desktop, optimized for logging and file capture.

## Uvod

moserial is a serial terminal for the GNOME desktop, optimized for logging and file capture. moserial 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, moserial 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, moserial also supports profile files to store frequently-used configurations.

## System Port Permissions

Before using moserial 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 moserial functions are accessed through the main toolbar, shown below:

### Port Setup

The first step in using moserial 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 moserial 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 moserial 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, moserial 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 moserial 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 moserial 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

moserial 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.

moserial 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

moserial 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

moserial 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

moserial 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

moserial 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 moserial, the settings currently in use are stored in a default profile file. These settings will automatically be recalled the next time you launch moserial.

## 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.