<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">
<!ENTITY appversion "3.0.0">
<!ENTITY manualversion "3.0.0">
<!ENTITY date "April 2009">
<!ENTITY appname "moserial">
<!ENTITY app "<application>moserial</application>">
<!-- replace version above with actual application version number --><!--  Template Version: 1.0.1  (do not remove this line) -->]>
<!-- =============Document Header ============================= -->
<article id="index" lang="sl"> <!-- please do not change the id -->

  <articleinfo>
    <title lang="en"><application>moserial</application> Manual V3.0.0</title>
    <copyright lang="en">
      <year>2009</year>
      <holder>Michael J. Chudobiak</holder>
    </copyright>

    <!-- translators: uncomment this:

    <copyright>
     <year>2000</year>
     <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
    </copyright>

    -->

    <!-- An address can be added to the publisher information.  If a role is
     not specified, the publisher/author is the same for all versions of the
     document.  -->
    <publisher>
      <publishername lang="en"> GNOME Documentation Project </publishername>
    </publisher>

       <legalnotice id="legalnotice">
         <para lang="en">
           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 <ulink type="help" url="ghelp:fdl">link</ulink> or in the file COPYING-DOCS
           distributed with this manual.
          </para>
          <para lang="en"> 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.
         </para>
 
         <para lang="en">
           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.
         </para>
 
         <para lang="en">
           DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED
           UNDER  THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE
           WITH THE FURTHER UNDERSTANDING THAT:
 
           <orderedlist>
                 <listitem>
                   <para lang="en">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
                   </para>
                 </listitem>
                 <listitem>
                   <para lang="en">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.
                   </para>
                 </listitem>
           </orderedlist>
         </para>
   </legalnotice>
 

    <authorgroup>
      <author role="maintainer" lang="en">
        <firstname>Michael</firstname>
	<surname>Chudobiak</surname>
	<affiliation>
	  <address> <email>mjc@avtechpulse.com</email> </address>
        </affiliation>
      </author>
    </authorgroup>
    <!-- do not put authorname in the header except in copyright - use
         section "authors" below -->
    <revhistory>
      <revision lang="en">
	<revnumber>3.0.0</revnumber>
	<date>April 2009</date>
	<revdescription>
	  <para role="author" lang="en">Michael J. Chudobiak</para>
	  <para role="publisher" lang="en">GNOME Documentation Project</para>
	</revdescription>
      </revision>
    </revhistory>


    <!-- this is version of manual, not application -->
    <releaseinfo lang="en">
      This is manual describes version 3.0.0 of moserial
    </releaseinfo>
    <abstract role="description"><para lang="en"><application>moserial</application> is a serial terminal for the GNOME desktop, optimized for logging and file capture.</para></abstract>
  </articleinfo>

  <indexterm lang="en">
    <primary>moserial</primary>
  </indexterm>
  <indexterm lang="en">
    <primary>serial</primary>
  </indexterm>
  <indexterm lang="en">
    <secondary>terminal</secondary>
  </indexterm>

  <!-- ============= Document Body ============================= -->

  <!-- ============= Introduction ============================== -->

  <sect1 id="intro">
    <title>Uvod</title>
    <para lang="en">
      <application>moserial</application> is a serial terminal for the GNOME desktop, optimized for logging 
      and file capture. <application>moserial</application> is primarily intended for technical users
      who need to communicate with embedded systems, consoles, and electronic
      test equipment. 
    </para>
    <para lang="en">
      Despite the technical orientation of the intended audience, <application>moserial</application> 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.
    </para>
    <para lang="en">
      To further improve efficiency, <application>moserial</application> also supports profile files
      to store frequently-used configurations.
    </para>
  </sect1>

  <sect1 id="ports">
    <title lang="en">System Port Permissions</title>
    <para lang="en">
      Before using <application>moserial</application> with a serial port, you need to make sure that
      you actually have permission to read and/or write to the port.
    </para>
    <para lang="en">
      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.
    </para>
    <para lang="en">
      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.
    </para>
  </sect1>

  <sect1 id="basic-usage">
    <title lang="en">Basic Usage</title>
    <sect2 id="main-toolbar">
      <title lang="en">The Main Toolbar</title>
      <para lang="en">
        Most <application>moserial</application> functions are accessed through the main toolbar, shown below:
      </para>
      <para>
        <graphic format="PNG" fileref="figures/main-toolbar.png"/>
      </para>
    </sect2>
    <sect2 id="port-setup">
      <title lang="en">Port Setup</title>
      <para lang="en">
        The first step in using <application>moserial</application> is to configure the serial port parameters. Click
        <guibutton>Port Setup</guibutton> 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.
      </para>
      <para lang="en">
        The <application>moserial</application> 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.
      </para>
      <para lang="en">
        A local echo can be enabled from this dialog. If enabled, all data that <application>moserial</application>
        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!) 
      </para>
      <para>
        <graphic format="PNG" fileref="figures/port-setup.png"/>
      </para>
    </sect2>
    <sect2 id="connect">
      <title lang="en">Open the Connection</title>
      <para lang="en">
        The next step in communicating with your remote device is to click 
        <guibutton>Connect</guibutton>. This opens the port. If you do not
        have the necessary privileges to open the port, an error will be reported.
      </para>
      <para>
	<graphic format="PNG" fileref="figures/connect.png"/>
      </para>
      <para lang="en">
        This step is optional. If you skip it, <application>moserial</application> will try to connect
        automatically when needed.
      </para>
      <para lang="en">
        Once you have connected, the <guibutton>Connect</guibutton> button will
        change into a <guibutton>Disconnect</guibutton> button. 
        Clicking <guibutton>Disconnect</guibutton> closes the port, and resets the
        TX and RX counters.
      </para>
      <para>
         <graphic format="PNG" fileref="figures/disconnect.png"/>
      </para>
    </sect2>
    <sect2 id="basic-io">
      <title lang="en">Basic Input and Output</title>
      <para lang="en">
        Once the port has been opened, any text received from the remote
        device will be displayed in the <guilabel>Received ASCII</guilabel>
        text area. If <application>moserial</application> detects a large number of unprintable characters,
        it will switch automatically to the <guilabel>Received HEX</guilabel>
        view.
      </para>
      <para>
        <graphic format="PNG" fileref="figures/received-tabs.png"/>
      </para>
      <para lang="en">
        To switch between HEX and ASCII views, simply click on the 
        appropriate tabs.
      </para>
      <para lang="en">
        To send data to the remote device, you can type text into the
        <guilabel>Outgoing</guilabel> single-line text box, and click
        the <guibutton>Send</guibutton> button. Your line of text will
	be terminated with the sequence selected in the area to the
        right of the <guibutton>Send</guibutton> button. If you aren't
        sure which termination sequence is best, start with "CR+LF end".
        The <guibutton>ASCII/HEX</guibutton> button should be set to
        ASCII to send text.
      </para>
      <para>
        <graphic format="PNG" fileref="figures/outgoing.png"/>
      </para>
      <para lang="en">
        If the <guibutton>ASCII/HEX</guibutton> button is set to HEX,
        do not enter text in the <guilabel>Outgoing</guilabel> area.
        Instead, enter hexadecimal numbers in the form "1234ABCD....".
      </para>
      <para lang="en">
        Once your data has been transmitted, a record of it will exist
        in the <guilabel>Sent ASCII</guilabel> and <guilabel>Sent HEX</guilabel>
        text areas. These text areas are not editable.
      </para>
      <para>
        <graphic format="PNG" fileref="figures/sent-tabs.png"/>
      </para>
      <para lang="en">
        The remote device may echo your sent data. If <application>moserial</application> detects
        echoed text in the <guilabel>Received ASCII</guilabel> text area,
        it will highlight the echoed text (using the highlight color defined
        in the preferences dialog).
      </para>
      <para lang="en">
        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.
      </para>
      <para>
        <graphic format="PNG" fileref="figures/statusbar.png"/>
      </para>
    </sect2>
  </sect1>
  <sect1 id="recording">
    <title lang="en">Recording Input and Output</title>
    <para lang="en">
      <application>moserial</application> 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).
    </para>
    <para>
      <graphic format="PNG" fileref="figures/record.png"/>
    </para>
    <para lang="en">
      When you are ready to record to a file, simply click <guibutton>Record</guibutton>,
      select the desired data to record (Incoming and/or Outgoing) in 
      the <guilabel>Stream to Record</guilabel> selection box, and enter the
      filename in the filechooser area.
    </para>
    <para>
      <graphic format="PNG" fileref="figures/record-dialog.png"/>
    </para>
    <para lang="en">
      When recording begins, the <guibutton>Record</guibutton> button will
      change into a <guibutton>Stop Recording</guibutton> 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.
    </para>
    <para>
      <graphic format="PNG" fileref="figures/stop-recording.png"/>
    </para>
    <para lang="en">
      <application>moserial</application> 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 
      <link linkend="preferences">Preferences</link> dialog to enable or
      disable these features.
    </para>
    <para lang="en">
      Note that if you wish to receive files using an error correction protocol
      (xmodem, ymodem, or zmodem), you will need to use the 
       <link linkend="receiving">Receive File</link>
      function instead. Unlike the <guibutton>Record</guibutton> function, the
      <guibutton>Receive File</guibutton> function can automatically determine when
      the file download is complete.
    </para>
    <para>
      <graphic format="PNG" fileref="figures/receive-file.png"/>
    </para>
  </sect1>
  <sect1 id="sending">
    <title lang="en">Sending Files</title>
    <para lang="en">
      <application>moserial</application> 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
      <guilabel>Sent ASCII</guilabel> or <guilabel>Sent HEX</guilabel>
      text areas. 
    </para>
    <para>
      <graphic format="PNG" fileref="figures/send-file.png"/>
    </para>
    <para lang="en">
      When you are ready to send a file, simply click <guibutton>Send File</guibutton>,
      select the desired file to send. You will also need to select the 
      appropriate protocol below.
    </para>
    <para>
      <graphic format="PNG" fileref="figures/send-file-dialog.png"/>
    </para>
    <para lang="en">
      When recording begins, a progress bar will display the status of the file
      transmission. 
    </para>
    <para>
      <graphic format="PNG" fileref="figures/send-progress.png"/>
    </para>
    <para lang="en">
      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.
    </para>
  </sect1>

  <sect1 id="receiving">
    <title lang="en">Receiving Files</title>
    <para lang="en">
      <application>moserial</application> 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
      <guilabel>Sent ASCII</guilabel> or <guilabel>Sent HEX</guilabel>
      text areas.
    </para>
    <para lang="en">
      To receive straight binary data streams, use the <link linkend="recording">Record</link>
      function instead of the <guibutton>Receive File</guibutton> function.
    </para>
    <para lang="en">
      To receive files sent with the xmodem, ymodem, or zmodem error correction
      protocols, using the <guibutton>Receive File</guibutton> function.
    </para>
    <para>
      <graphic format="PNG" fileref="figures/receive-file.png"/>
    </para>
    <para lang="en">
      When you are ready to receive a file, simply click <guibutton>Receive File</guibutton>,
      select a folder to store the received file. You will also need to select the
      appropriate protocol below.
    </para>
    <para>
      <graphic format="PNG" fileref="figures/receive-file-dialog.png"/>
    </para>
    <para lang="en">
      When recording begins, a progress bar will display the status of the file
      reception.
    </para>
    <para>
      <graphic format="PNG" fileref="figures/receive-progress.png"/>
    </para>
    <para lang="en">
      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.
    </para>
  </sect1>

  <sect1 id="preferences">
    <title lang="en">Other Preferences</title>
    <para lang="en">
      <application>moserial</application> has several options that can be configured from the
      <guilabel>Preferences</guilabel> dialog.
    </para>
    <para>
      <graphic format="PNG" fileref="figures/preferences.png"/>
    </para>
    <para lang="en">
      The color of the text area foreground, background, and highlighting
      can be configured, as can the font type and size.
    </para>
    <para lang="en">
      If <guilabel>Launch recorded files</guilabel> 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.
    </para>
    <para lang="en">
      If <guilabel>Enable timeout</guilabel> 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.
    </para>
  </sect1>

  <sect1 id="profiles">
    <title lang="en">Using Profiles</title>
    <para lang="en">
      <application>moserial</application> 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 <menuchoice><guisubmenu>File</guisubmenu><guimenuitem>Save</guimenuitem></menuchoice>
      or <menuchoice><guisubmenu>File</guisubmenu><guimenuitem>Save As</guimenuitem></menuchoice>
      dialogs. To load a profile, use the
      <menuchoice><guisubmenu>File</guisubmenu><guimenuitem>Open</guimenuitem></menuchoice>
      dialog.
    </para>
    <para lang="en">
      Loading a profile will automatically disconnect any connected port.
    </para>
    <para lang="en">
      When you quit <application>moserial</application>, the settings currently in use are stored in a 
      default profile file. These settings will automatically be recalled
      the next time you launch <application>moserial</application>.
    </para>
  </sect1>

  <sect1 id="keys">
    <title lang="en">Special Keys</title>
    <para>
      <table id="moserial-TBL-keyword-shortcuts" frame="topbot">
      <title lang="en">Special Keys</title>
      <tgroup cols="2" colsep="1" rowsep="1">
        <colspec colname="COLSPEC0" colwidth="50*"/>
        <colspec colname="COLSPEC1" colwidth="50*"/>
        <thead>
          <row valign="top" rowsep="1">
            <entry colname="COLSPEC0">
                <para lang="en">Keyboard Shortcut</para></entry>
            <entry colname="COLSPEC1">
                <para lang="en">Description</para></entry>
          </row>
        </thead>
        <tbody>
          <row valign="top">
            <entry>
              <para lang="en">
		<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
              </para>
            </entry>
            <entry>
              <para lang="en">Copies text. This can be used in any of the text areas.</para>
            </entry>
          </row>
          <row valign="top">
            <entry>
              <para lang="en">
                <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
              </para>
            </entry>
            <entry>
              <para lang="en">Cuts text. This only works in the <guilabel>Outgoing</guilabel> single-line text box.</para>
            </entry>
          </row>
          <row valign="top">
            <entry>
              <para lang="en">
                <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
              </para>
            </entry>
            <entry>
              <para lang="en">
                Pastes text into the <guilabel>Outgoing</guilabel> single-line text box,
                and moves the focus to that text box.
              </para>
            </entry>
          </row>
          <row valign="top">
            <entry>
              <para lang="en">
                <keycap>Esc</keycap>
              </para>
            </entry>
            <entry>
              <para lang="en">
                Moves the focus to the <guilabel>Outgoing</guilabel> single-line text box.
              </para>
            </entry>
          </row>

        </tbody>
      </tgroup>
      </table>
  </para>
  </sect1>

</article>
