gpl/picocom/picocom.8.html

<html>
<head>
<title>picocom(8)</title>
</head>

<body>

<center><table width="100%"><tr>
  <td align="left">picocom(8)</td>
  <td align="center"></td>
  <td align="right">picocom(8)</td>
</tr></table></center>

<h2>NAME</h2>
<center><table width="90%"><tr><td>
picocom -- minimal dumb-terminal emulation program
</td></tr></table></center>

<h2>SYNOPSIS</h2>
<center><table width="90%"><tr><td>
<ul>
  <li><b>
    picocom [ <i>options</i> ] <i>device</i>
  </b></li>
</ul>
</td></tr></table></center>

<h2>DESCRIPTION</h2>
<center><table width="90%"><tr><td>
  <p>
    As its name suggests, <b>picocom</b> is a minimal dumb-terminal
    emulation program. It is, in principle, very much like
    <a href=""><b>minicom</b>(1)</a>, only it's "pico" instead of
    "mini"! It was designed to serve as a simple, manual, modem
    configuration, testing, and debugging tool. It has also served
    (quite well) as a low-tech "terminal-window" to allow operator
    intervention in PPP connection scripts (something like the
    ms-windows "open terminal window before / after dialing" feature).
    It could also prove useful in many other similar tasks.
  </p>
  <p>
    When <b>picocom</b> starts it opens the terminal (serial device)
    given as its non-option argument. Unless the <i>--noinit</i>
    option is given, it configures the device to the settings
    specified by the option-arguments (or to some default settings),
    and sets it to "raw" mode. If <i>--noinit</i> is given, the
    initialization and configuration is skipped; the device is just
    opened. Following this, <b>picocom</b> sets the standard-input and
    standard-output to raw mode. Having done so, it goes in a loop
    where it listens for input from stdin, or from the serial port.
    Input from the serial port is copied to the standard output while
    input from the standard input is copied to the serial port. <b>picocom</b>
    also scans its input stream for a user-specified control
    character, called the "escape character" (being by default "C-a").
    If the escape character is seen, then instead of sending it to the
    serial-device, the program enters "command mode" and waits for the
    next character (which is called the "function character").
    Depending on the value of the function character, <b>picocom</b>
    performs one of the operations described in the "Commands" section
    below.
  </p>
</td></tr></table></center>

<h2>COMMANDS</h2>
<center><table width="90%"><tr><td>
  <p>
    Commands are given to <b>picocom</b> by first keying the "espace
    character" which by default is "C-a" (see "Options" below on how
    to change it), and then keying one for the function (command)
    characters shown here.
  </p>
  <dl>
    <dt><b>
      [escape character]
    </b></dt>
    <dd>
      <p>
        Send the escape character to the serial port and return to
        "transparent" mode. This means that if the escape character
        ("C-a", by default) is typed twice, the program sends the
        escape character to the serial port, and remains in
        transparent mode. This is a new behavior implemented in v1.4.
        Previously picocom used to ignore the escape-character when it
        was entered as a function character.
      </p>
    </dd>
    <dt><b>
      C-x
    </b></dt>
    <dd>
      <p>
        Exit the program: if the "--noreset" option was not given then
        the serial port is reset to its original settings before
        exiting; if it was given the serial port is not reset.
      </p>
    </dd>
    <dt><b>
      C-q
    </b></dt>
    <dd>
      <p>
        Quit the program *without* reseting the serial port,
        regardless of the "--noreset" option.
      </p>
    </dd>
    <dt><b>
      C-p
    </b></dt>
    <dd>
      <p>
        Pulse the DTR line. Lower it for 1 sec, and then raise it
        again.
      </p>
    </dd>
    <dt><b>
      C-t
    </b></dt>
    <dd>
      <p>
        Toggle the DTR line. If DTR is up, then lower it. If it is
        down, then raise it.
      </p>
    </dd>
    <dt><b>
      C-\e
    </b></dt>
    <dd>
      <p>
        Generate a break sequence on the serial line. A break sequence
        is usually generated by marking (driving to logical one) the
        serial Tx line for an amount of time coresponding to several
        character durations.
      </p>
    </dd>
    <dt><b>
      C-u
    </b></dt>
    <dd>
      <p>
        Baud up. Increase the baud-rate. The list of baud-rates
        stepped-through by this command is: 300, 600, 1200, 2400,
        4800, 9600, 19200, 38400, 57600, 115200.
      </p>
    </dd>
    <dt><b>
      C-d
    </b></dt>
    <dd>
      <p>
        Baud down. Decrease the baud-rate. The list of baud-rates
        stepped-through by this command is the same as for the
        "baud-up" command.
      </p>
    </dd>
    <dt><b>
      C-f
    </b></dt>
    <dd>
      <p>
        Cycle through flow-control settings (RTS/CTS, XON/XOFF, none).
      </p>
    </dd>
    <dt><b>
      C-y
    </b></dt>
    <dd>
      <p>
        Cycle through parity settings (even, odd, none).
      </p>
    </dd>
    <dt><b>
      C-b
    </b></dt>
    <dd>
      <p>
        Cycle through databits-number settings (5, 6, 7, 8).
      </p>
    </dd>
    <dt><b>
      C-v
    </b></dt>
    <dd>
      <p>
        Show program options (like baud rate, data bits, etc). Only
        the options that can be modified online (through commands) are
        shown, not those that can only be set at the command-line.
      </p>
    </dd>
    <dt><b>
      C-s
    </b></dt>
    <dd>
      <p>
        Send (upload) a file (see "Sending and Receiving Files" below)
      </p>
    </dd>
    <dt><b>
      C-r
    </b></dt>
    <dd>
      <p>
        Receive (download) a file (see "Sending and Receiving Files"
        below)
      </p>
    </dd>
  </dl>
  <p>
    After performing one of the above operations the program leaves
    the command mode and enters transparent mode. Example: To increase
    the baud-rate by two steps, you have to type:
  </p>
  <p>
    C-a, C-u, C-a, C-u
  </p>
  <p>
    assuming of-course that "C-a" is the escape character.
  </p>
</td></tr></table></center>

<h2>SENDING AND RECEIVING FILES</h2>
<center><table width="90%"><tr><td>
  <p>
    <b>picocom</b> can send and receive files over the serial port
    using external programs that implement the respective protocols.
    In Linux typical programs for this purpose are:
  </p>
  <ul>
    <li>
      <p>
        <a href=""><b>rx</b>(1)</a> - receive using the X-MODEM
        protocol
      </p>
    </li>
    <li>
      <p>
        <a href=""><b>rb</b>(1)</a> - receive using the Y-MODEM
        protocol
      </p>
    </li>
    <li>
      <p>
        <a href=""><b>rz</b>(1)</a> - receive using the Z-MODEM
        protocol
      </p>
    </li>
    <li>
      <p>
        <a href=""><b>sx</b>(1)</a> - send using the X-MODEM protocol
      </p>
    </li>
    <li>
      <p>
        <a href=""><b>sb</b>(1)</a> - send using the Y-MODEM protocol
      </p>
    </li>
    <li>
      <p>
        <a href=""><b>sz</b>(1)</a> - send using the Z-MODEM protocol
      </p>
    </li>
    <li>
      <p>
        <a href=""><b>ascii-xfr</b>(1)</a> - receive or transmit ASCII
        files
      </p>
    </li>
  </ul>
  <p>
    The name of, and the command-line options to, the program to be
    used for transmitting files are given by the "--send-cmd" option.
    Similarly the program to receive files, and its argumets, are
    given by the "--receive-cmd" option. For example, in order to
    start a <b>picocom</b> session that uses "sz" to transmit files,
    and "rz" to receive, you have to say something like this:
  </p>
  <p>
    picocom --send-cmd "sz -vv" --receive-cmd "rz -vv"
  </p>
  <p>
    During the picocom session, if you key the "send" or "receive"
    commands (e.g. by pressing C-a, C-s, or C-a, C-r) you will be
    prompted for a filename. At this prompt you can enter one or more
    file-names, and any additional arguments to the transmission or
    reception program. After that, picocom will start the the external
    program as specified by the "--send-cmd", or "--receive-cmd"
    option, and with any filenames and additional arguments you may
    have supplied. The standard input and output of the external
    program will be connected to the serial port. The standard error
    of the external program will be connected to the terminal
    which---while the program is running---will revert to canonical
    mode. Pressing 'C-c' while the external program is running will
    prematurely terminate it, and return control to <b>picocom</b>.
    Pressing 'C-c' at any other time, has no special effect; the
    character is normally passed to the serial port.
  </p>
</td></tr></table></center>

<h2>OPTIONS</h2>
<center><table width="90%"><tr><td>
  <p>
    <b>picocom</b> accepts the following command-line options
  </p>
  <dl>
    <dt><b>
      --baud | -b
    </b></dt>
    <dd>
      <p>
        Defines the baud-rate to set the serial-port (terminal) to.
      </p>
    </dd>
    <dt><b>
      --flow | -f
    </b></dt>
    <dd>
      <p>
        Defines the flow-control mode to set the serial-port to. Must
        be one of:
      </p>
      <ul>
        <li>
          <p>
            \'x' for xon/xoff (software) mode
          </p>
        </li>
        <li>
          <p>
            \'h' for hardware flow control (RTS/CTS)
          </p>
        </li>
        <li>
          <p>
            \'n' for no flow control
          </p>
        </li>
      </ul>
      <p>
        (Default: 'n')
      </p>
    </dd>
    <dt><b>
      --parity | -p
    </b></dt>
    <dd>
      <p>
        Defines the parity mode to set the serial-port to. Must be one
        of:
      </p>
      <ul>
        <li>
          <p>
            \'o' for odd parity mode.
          </p>
        </li>
        <li>
          <p>
            \'e' for even parity mode.
          </p>
        </li>
        <li>
          <p>
            \'n' for no parity, mode.
          </p>
        </li>
      </ul>
      <p>
        (Default: 'n')
      </p>
    </dd>
    <dt><b>
      --databits | -d
    </b></dt>
    <dd>
      <p>
        Defines the number of data bits in every character. Must be
        one of: 5, 6, 7, 8
      </p>
      <p>
        (Default: 8)
      </p>
    </dd>
    <dt><b>
      --esacpe | -e
    </b></dt>
    <dd>
      <p>
        Defines the character that will make picocom enter
        command-mode (see description above). If 'x' is given, then
        C-x will make picocom enter command mode.
      </p>
      <p>
        (Default: 'a')
      </p>
    </dd>
    <dt><b>
      --noinit | -i
    </b></dt>
    <dd>
      <p>
        If given, <b>picocom</b> will not initialize, reset, or
        otherwise meddle with the serial port at start-up. It will
        just open it. This is useful, for example, for connecting <b>picocom</b>
        to already-connected modems, or already configured ports
        without terminating the connection, or altering the settings.
        If required serial port parameters can then be adjusted at
        run-time by commands.
      </p>
    </dd>
    <dt><b>
      --noreset | -r
    </b></dt>
    <dd>
      <p>
        If given, <b>picocom</b> will not *reset* the serial port when
        exiting. It will just close the filedes and do nothing more.
        This is useful, for example, for leaving modems connected when
        exiting <b>picocom</b>. Regardless whether the "--noreset"
        option is given the user can exit <b>picocom</b> using the
        "Quit" command (instead of "Exit"), which never resets the
        serial port. If "--noreset" is given then "Quit" and "Exit"
        behave essentially the same.
      </p>
    </dd>
    <dt><b>
      --nolock | -l
    </b></dt>
    <dd>
      <p>
        If given, <b>picocom</b> will *not* attempt to lock the serial
        port before opening it. Normally picocom attempts to get a
        UUCP-style lock-file (e.g. "/var/lock/LCK..ttyS0") before
        opening the port. Failing to do so, results in the program
        exiting after emitting an error-message. It is possible that
        your picocom binary is compiled without this option.
      </p>
    </dd>
    <dt><b>
      --send-cmd | -s
    </b></dt>
    <dd>
      <p>
        Specifies the external program (and any arguments to it) that
        will be used for transmitting files.
      </p>
      <p>
        Default: "sz -vv"
      </p>
    </dd>
    <dt><b>
      --receive-cmd | -v
    </b></dt>
    <dd>
      <p>
        Specifies the external program (and any arguments to it) that
        will be used for receiving files.
      </p>
      <p>
        (Default: "rz -vv")
      </p>
    </dd>
    <dt><b>
      --help | -h
    </b></dt>
    <dd>
      <p>
        Print a short help message describing the command-line
        options.
      </p>
    </dd>
  </dl>
</td></tr></table></center>

<h2>AUTHOR</h2>
<center><table width="90%"><tr><td>
  <p>
    picocom was written by Nick Patavalis (npat@efault.net)
  </p>
</td></tr></table></center>

<h2>AVAILABILITY</h2>
<center><table width="90%"><tr><td>
  <p>
    The latest version of "picocom" can be downloaded from:
    <a href="http://efault.net/npat/hacks/picocom/">http://efault.net/npat/hacks/picocom/</a>
  </p>
</td></tr></table></center>

<center><table width="100%"><tr>
  <td align="left"></td>
  <td align="center"></td>
  <td align="right">picocom(8)</td>
</tr></table></center>

</body>
</html>