<?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 "2.26.0">
<!ENTITY manualversion "2.26.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><application>moserial</application> Manual V2.26.0</title>
    <copyright>
      <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> GNOME Documentation Project </publishername>
    </publisher>

       <legalnotice id="legalnotice">
         <para>
           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> 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>
           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>
           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>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>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">
        <firstname>Michael</firstname>
	<surname>Chudobiak</surname>
	<affiliation>
	  <address> <email>mjc@svn.gnome.org</email> </address>
        </affiliation>
      </author>
    </authorgroup>
    <!-- do not put authorname in the header except in copyright - use
         section "authors" below -->
    <revhistory>
      <revision>
	<revnumber>2.26.0</revnumber>
	<date>April 2009</date>
	<revdescription>
	  <para role="author">Michael J. Chudobiak</para>
	  <para role="publisher">GNOME Documentation Project</para>
	</revdescription>
      </revision>
    </revhistory>


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

  <indexterm>
    <primary>moserial</primary>
  </indexterm>
  <indexterm>
    <primary>serial</primary>
  </indexterm>
  <indexterm>
    <secondary>terminal</secondary>
  </indexterm>

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

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

  <sect1 id="intro">
    <title>Uvod</title>
    <para>
      <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>
      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>
      To further improve efficiency, <application>moserial</application> also supports profile files
      to store frequently-used configurations.
    </para>
  </sect1>

  <sect1 id="ports">
    <title>System Port Permissions</title>
    <para>
      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>
      There are a number of ways this is done on a Linux system.
      On Fedora 10, you may need to use the PolicyKit tool, invoked using
      <menuchoice><guisubmenu>System</guisubmenu>
                  <guisubmenu>Preferences</guisubmenu>
		  <guisubmenu>System</guisubmenu>
                  <guimenuitem>Authorizations</guimenuitem></menuchoice>. 
      Then, navigate to the
      <menuchoice><guisubmenu>org</guisubmenu>
                  <guisubmenu>freedesktop</guisubmenu>
                  <guisubmenu>device-access</guisubmenu>
                  <guimenuitem>Directly access serial modem devices</guimenuitem></menuchoice>,
      and click <guilabel>edit</guilabel>. Set <guilabel>Anyone:</guilabel> to "Yes".
    </para>
    <figure id="authorizations-fig">
    <title>Serial Port Authorizations on Fedora 10</title>
      <graphic format="PNG" fileref="figures/authorizations.png"/>
    </figure>
    <para>
      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.
    </para>
    <para>
      Alternatively, you can see what group the devices belong to, and make your account a member of
      that group.
    </para>
  </sect1>

  <sect1 id="basic-usage">
    <title>Basic Usage</title>
    <sect2 id="main-toolbar">
      <title>The Main Toolbar</title>
      <para>
        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>Port Setup</title>
      <para>
        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>
        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>
        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>Open the Connection</title>
      <para>
        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>
        This step is optional. If you skip it, <application>moserial</application> will try to connect
        automatically when needed.
      </para>
      <para>
        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>Basic Input and Output</title>
      <para>
        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>
        To switch between HEX and ASCII views, simply click on the 
        appropriate tabs.
      </para>
      <para>
        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>
        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>
        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>
        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>
        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>Recording Input and Output</title>
    <para>
      <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>
      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>
      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>
      <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>
      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>Sending Files</title>
    <para>
      <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>
      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>
      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>
      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>Receiving Files</title>
    <para>
      <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>
      To receive straight binary data streams, use the <link linkend="recording">Record</link>
      function instead of the <guibutton>Receive File</guibutton> function.
    </para>
    <para>
      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>
      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>
      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>
      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>Other Preferences</title>
    <para>
      <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>
      The color of the text area foreground, background, and highlighting
      can be configured, as can the font type and size.
    </para>
    <para>
      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>
      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>Using Profiles</title>
    <para>
      <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>
      Loading a profile will automatically disconnect any connected port.
    </para>
    <para>
      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>Special Keys</title>
    <para>
      <table id="moserial-TBL-keyword-shortcuts" frame="topbot">
      <title>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>Keyboard Shortcut</para></entry>
            <entry colname="COLSPEC1">
                <para>Description</para></entry>
          </row>
        </thead>
        <tbody>
          <row valign="top">
            <entry>
              <para>
		<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
              </para>
            </entry>
            <entry>
              <para>Copies text. This can be used in any of the text areas.</para>
            </entry>
          </row>
          <row valign="top">
            <entry>
              <para>
                <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
              </para>
            </entry>
            <entry>
              <para>Cuts text. This only works in the <guilabel>Outgoing</guilabel> single-line text box.</para>
            </entry>
          </row>
          <row valign="top">
            <entry>
              <para>
                <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
              </para>
            </entry>
            <entry>
              <para>
                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>
                <keycap>Esc</keycap>
              </para>
            </entry>
            <entry>
              <para>
                Moves the focus to the <guilabel>Outgoing</guilabel> single-line text box.
              </para>
            </entry>
          </row>

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

</article>
