picocom.1

.\" Automatically generated by Pandoc 1.16.0.2
.\"
.ad l
.TH "PICOCOM" "1" "2018-04-03" "Picocom 3.2a" "User Commands"
.nh \" Turn off hyphenation by default.
.SH NAME
.PP
picocom \- minimal dumb\-terminal emulation program
.SH SYNOPSIS
.PP
\f[B]picocom\f[] [ \f[I]options\f[] ] \f[I]device\f[]
.SH DESCRIPTION
.PP
As its name suggests, \f[B]picocom(1)\f[] is a minimal dumb\-terminal
emulation program.
It is, in principle, very much like \f[B]minicom(1)\f[], only it\[aq]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 serial communications
program to allow access to all types of devices that provide serial
consoles.
It could also prove useful in many other similar tasks.
.PP
In effect, picocom is not an "emulator" per\-se.
It is a simple program that opens, configures, manages a serial port
(tty device) and its settings, and connects to it the terminal emulator
you are, most likely, already using (the terminal window application,
xterm, rxvt, system console, etc).
.PP
When picocom starts it opens the tty (serial port) given as its
non\-option argument (or the \f[I]last\f[] non\-option argument, if
multiple are given).
Unless the \f[B]\-\-noinit\f[] option is given, it configures the port
to the settings specified by the option\-arguments (or to some default
settings), and sets it to "raw" mode.
If \f[B]\-\-noinit\f[] is given, the initialization and configuration is
skipped; the port is just opened.
Following this, if standard input is a tty, picocom sets the tty to raw
mode.
Then 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.
Picocom also scans its input stream for a user\-specified control
character, called the \f[I]escape character\f[] (being by default
\f[B]C\-a\f[]).
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, picocom performs one
of the operations described in the \f[B]COMMANDS\f[] section below.
.SH COMMANDS
.PP
Commands are given to picocom by first keying the \f[I]espace
character\f[] which by default is \f[B]C\-a\f[] (see \f[B]OPTIONS\f[]
below for how to change it), and then keying one of the function
(command) characters shown here.
.TP
.B \f[I]escape character\f[]
Send the escape character to the serial port and return to "transparent"
mode.
This means that if the escape character (\f[B]C\-a\f[], by default) is
typed twice, the program sends the escape character to the serial port,
and remains in transparent mode.
.RS
.RE
.TP
.B \f[B]C\-x\f[]
Exit the program.
If the \f[B]\-\-noreset\f[] option is \f[I]not\f[] given, then the
serial port is reset to its original settings before exiting, and the
modem control lines (typically DTR and RTS) are cleared (lowered)
signaling a modem hangup.
If \f[B]\-\-noreset\f[] is given (and \f[B]\-\-hangup\f[] is not), then
the serial port settings are not reset, and the modem control lines
remain unaffected.
If both \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] are given, then the
serial port settings are not reset, but the modem\-control lines
\f[I]are\f[] cleared.
.RS
.RE
.TP
.B \f[B]C\-q\f[]
Quit the program \f[I]without\f[] resetting the serial port to its
original settings.
Terminating with the Quit command, picocom behaves \f[I]exactly\f[] as
if the \f[B]\-\-noreset\f[] option was given.
The serial port is \f[I]not\f[] reset to its original settings, and the
modem control lines remain unaffected or are cleared, subject to the
\f[B]\-\-hangup\f[] option.
.RS
.RE
.TP
.B \f[B]C\-p\f[]
Pulse the DTR line.
Lower it for 1 sec, and then raise it again.
.RS
.RE
.TP
.B \f[B]C\-t\f[]
Toggle the DTR line.
If DTR is up, then lower it.
If it is down, then raise it.
May not be supported on some systems.
.RS
.RE
.TP
.B \f[B]C\-g\f[]
Toggle the RTS line.
If RTS is up, then lower it.
If it is down, then raise it.
Not supported if the flow control mode is RTS/CTS.
May not be supported on some systems.
.RS
.RE
.TP
.B \f[B]C\-backslash\f[]
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 corresponding to several
character durations.
.RS
.RE
.TP
.B \f[B]C\-b\f[]
Set baudrate.
Prompts you to enter a baudrate numerically (in bps) and configures the
serial port accordingly.
.RS
.RE
.TP
.B \f[B]C\-u\f[]
Baud up.
Increase the baud\-rate.
The list of baud\-rates stepped\-through by this command is: 50, 75,
110, 134, 150, 200, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400,
57600, 115200.
If \f[C]HIGH_BAUD\f[] support is compiled\-in, then the following
baud\-rates are also added to the list: 230400, 460800, 500000, 576000,
921600, 1000000, 1152000, 1500000, 2000000, 2500000, 3000000, 3500000,
4000000.
Depending on you system, any of the higher baud rates may be missing.
.RS
.RE
.TP
.B \f[B]C\-d\f[]
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.
.RS
.RE
.TP
.B \f[B]C\-f\f[]
Cycle through flow\-control settings (RTS/CTS, XON/XOFF, none).
.RS
.RE
.TP
.B \f[B]C\-y\f[]
Cycle through parity settings (even, odd, none).
.RS
.RE
.TP
.B \f[B]C\-i\f[]
Cycle through databits\-number settings (5, 6, 7, 8).
.RS
.RE
.TP
.B \f[B]C\-j\f[]
Cycle through stopbits\-number settings (1, 2).
.RS
.RE
.TP
.B \f[B]C\-c\f[]
Toggle local\-echo mode.
.RS
.RE
.TP
.B \f[B]C\-w\f[]
Write hex.
Picocom prompts the user for a string of hexadecimal values.
Values can be entered with or without delimiters (separators).
The hexadecimal values are translated to binary and sent to the port,
exactly as if input at the terminal (i.e.
the \f[B]\-\-omap\f[], \f[B]\-\-echo\f[] and \f[B]\-\-emap\f[] options
are observed).
Example: The following sends the characters "ABCD" to the port.
.RS
.IP
.nf
\f[C]
C\-a\ C\-w
***\ hex:\ 41\ 4243:44
***\ wrote\ 4\ bytes\ ***
\f[]
.fi
.RE
.TP
.B \f[B]C\-s\f[]
Send (upload) a file.
See \f[B]SENDING AND RECEIVING FILES\f[] below.
.RS
.RE
.TP
.B \f[B]C\-r\f[]
Receive (download) a file.
See \f[B]SENDING AND RECEIVING FILES\f[] below.
.RS
.RE
.TP
.B \f[B]C\-v\f[]
Show program options (like baud rate, data bits, etc) as well as the
actual serial port settings.
Only the options and port settings that can be modified online (through
commands) are shown, not those that can only be set at the
command\-line.
See \f[B]DISPLAY OF OPTIONS AND PORT SETTINGS\f[] for details.
.RS
.RE
.TP
.B \f[B]C\-h\f[] or \f[B]C\-k\f[]
Show help, or show keys.
Prints a short description of all available function (command) keys.
.RS
.RE
.PP
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:
.RS
.PP
\f[B]C\-a\f[], \f[B]C\-u\f[], \f[B]C\-a\f[], \f[B]C\-u\f[]
.RE
.PP
assuming of\-course that \f[B]C\-a\f[] is the escape character.
.SH OPTIONS
.PP
Picocom accepts the following command\-line options.
.TP
.B \f[B]\-\-baud\f[] | \f[B]\-b\f[]
Defines the baud\-rate to set the serial\-port (terminal) to.
.RS
.RE
.TP
.B \f[B]\-\-flow\f[] | \f[B]\-f\f[]
Defines the flow\-control mode to set the serial\-port to.
Must be one of: \f[B]x\f[] for xon/xoff (software) mode, \f[B]h\f[] for
hardware flow control (RTS/CTS), \f[B]n\f[] for no flow control.
(Default: \f[B]n\f[])
.RS
.RE
.TP
.B \f[B]\-\-parity\f[] | \f[B]\-y\f[]
Defines the parity mode to set the serial\-port to.
Must be one of: \f[B]o\f[] for odd parity mode, \f[B]e\f[] for even
parity mode, \f[B]n\f[] for no parity mode.
(Default: \f[B]n\f[])
.RS
.RE
.TP
.B \f[B]\-\-databits\f[] | \f[B]\-d\f[]
Defines the number of data bits in every character.
Must be one of: \f[B]5\f[], \f[B]6\f[], \f[B]7\f[], \f[B]8\f[].
(Default: \f[B]8\f[])
.RS
.RE
.TP
.B \f[B]\-\-stopbits\f[] | \f[B]\-p\f[]
Defines the number of stop bits in every character.
Must be one of: \f[B]1\f[], or \f[B]2\f[].
(Default: \f[B]1\f[])
.RS
.RE
.TP
.B \f[B]\-\-escape\f[] | \f[B]\-e\f[]
Defines the character that will make picocom enter command\-mode (see
description above).
If \f[B]x\f[] is given, then \f[B]C\-x\f[] will make picocom enter
command mode.
See also the \f[B]\-\-no\-escape\f[] option.
(Default: \f[B]a\f[])
.RS
.RE
.TP
.B \f[B]\-\-no\-escape\f[] | \f[B]\-n\f[]
Disables the escape character.
Picocom will never enter command\-mode if this option is given.
To exit picocom, in this case, you must either close its standard input,
or send it the TERM or INT signal.
(Default: Disabled).
.RS
.RE
.TP
.B \f[B]\-\-echo\f[] | \f[B]\-c\f[]
Enable local echo.
Every character being read from the terminal (standard input) is echoed
to the terminal (standard output) subject to the echo\-mapping
configuration (see \f[B]\-\-emap\f[] option).
(Default: Disabled)
.RS
.RE
.TP
.B \f[B]\-\-noinit\f[] | \f[B]\-i\f[]
If given, picocom will not initialize, configure, or otherwise mess with
the serial port at start\-up.
It will just open it.
This is useful, for example, for connecting picocom to
already\-connected modems, or already configured ports without
terminating the connection, or altering their settings.
If required, serial port parameters can then be adjusted at run\-time by
commands.
See also the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] options.
(Default: Disabled)
.RS
.RE
.TP
.B \f[B]\-\-noreset\f[] | \f[B]\-r\f[]
If given, picocom will not reset the serial port when exiting.
It will just close the respective file descriptor and do nothing more.
The serial port settings will \f[I]not\f[] be restored to their original
values and, unless the \f[B]\-\-hangup\f[] option is also given, the
modem\-control lines will \f[I]not\f[] be affected.
This is useful, for example, for leaving modems connected when exiting
picocom.
Regardless whether the \f[B]\-\-noreset\f[] option is given, the user
can exit picocom using the "Quit" command (instead of "Exit"), which
makes picocom behave \f[I]exactly\f[] as if \f[B]\-\-noreset\f[] was
given.
See also the \f[B]\-\-hangup\f[] option.
(Default: Disabled)
.RS
.PP
NOTICE: Picocom clears the modem control lines on exit by setting the
\f[I]HUPCL\f[] control bit of the respective port.
Picocom always sets HUPCL according to the \f[B]\-\-noreset\f[] and
\f[B]\-\-hangup\f[] options.
If \f[B]\-\-noreset\f[] is given and \f[B]\-\-hangup\f[] is not, then
HUPCL for the port is cleared and will remain so after exiting picocom.
If \f[B]\-\-noreset\f[] is \f[I]not\f[] given, or if both
\f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] are given, then HUPCL is
set for the port and will remain so after exiting picocom.
This is true, regardless of the way picocom terminates (command, read
zero\-bytes from standard input, killed by signal, fatal error, etc),
and regardless of the \f[B]\-\-noinit\f[] option.
.RE
.TP
.B \f[B]\-\-hangup\f[] | \f[B]\-u\f[]
If given together with \f[B]\-\-noreset\f[], picocom will not reset the
serial port to it\[aq]s original settings on exit, but it \f[I]will\f[]
clear the modem control lines (typically DTR and RTS) to signal a modem
hangup.
Without the \f[B]\-\-noreset\f[] option (explicitly given, or implied by
exiting with the "Quit" command) \f[B]\-\-hangup\f[] has no effect
(without \f[B]\-\-noreset\f[] picocom always clears the modem control
lines on exit, anyway).
.RS
.RE
.TP
.B \f[B]\-\-nolock\f[] | \f[B]\-l\f[]
If given, picocom will \f[I]not\f[] attempt to lock the serial port
before opening it.
Normally, depending on how it\[aq]s compiled, picocom attempts to get a
UUCP\-style lock\-file (e.g.
\[aq]/var/lock/LCK..ttyS0\[aq]) before opening the port, or attempts to
lock the port device\-node using \f[B]flock(2)\f[].
Failing to do so, results in the program exiting after emitting an
error\-message.
It is possible that your picocom binary is compiled without support for
locking.
In this case the \f[B]\-\-nolock\f[] option is accepted, but has no
effect.
(Default: Disabled)
.RS
.RE
.TP
.B \f[B]\-\-send\-cmd\f[] | \f[B]\-s\f[]
Specifies the external program (and any arguments to it) that will be
used for transmitting files.
If the argument to \f[B]\-\-send\-cmd\f[] is the empty string
(\[aq]\[aq]), the send\-file command is disabled.
See \f[B]SENDING AND RECEIVING FILES\f[].
(Default: \f[B]sz \-vv\f[])
.RS
.RE
.TP
.B \f[B]\-\-receive\-cmd\f[] | \f[B]\-v\f[]
Specifies the external program (and any arguments to it) that will be
used for receiving files.
If the argument to \f[B]\-\-receive\-cmd\f[] is the empty string
(\[aq]\[aq]), the receive\-file command is disabled.
See \f[B]SENDING AND RECEIVING FILES\f[].
(Default: \f[B]rz \-vv\f[])
.RS
.RE
.TP
.B \f[B]\-\-imap\f[]
Specifies the input character map (i.e.
special characters to be replaced when read from the serial port).
See \f[B]INPUT, OUTPUT, AND ECHO MAPPING\f[].
(Default: Empty)
.RS
.RE
.TP
.B \f[B]\-\-omap\f[]
Specifies the output character map (i.e.
special characters to be replaced before being written to serial port).
See \f[B]INPUT, OUTPUT, AND ECHO MAPPING\f[].
(Default: Empty)
.RS
.RE
.TP
.B \f[B]\-\-emap\f[]
Specifies the local\-echo character map (i.e.
special characters to be replaced before being echoed\-back to the
terminal, if local\-echo is enabled).
See \f[B]INPUT, OUTPUT, AND ECHO MAPPING\f[].
(Defaul: \f[B]delbs,crcrlf\f[])
.RS
.RE
.TP
.B \f[B]\-\-logfile\f[] | \f[B]\-g\f[]
Use specified file for logging (recording) serial input, and possibly
serial output.
If the file exists, it is appended to.
Every character read from the serial port is written to the specified
file (before input mapping is performed).
If local\-echo mode is is enabled (see \f[B]\-\-echo\f[] option and
\f[B]C\-c\f[] command), then every character written to the serial port
(after output mapping is performed) is also logged to the same file.
(Default: no logging)
.RS
.RE
.TP
.B \f[B]\-\-initstring\f[] | \f[B]\-t\f[]
Send the provided string after opening and configuring the serial port.
The init string is sent exactly as if it was input at the terminal.
Sending the init string, picocom observes the \f[B]\-\-omap\f[] output
mapping, the \f[B]\-\-echo\f[] local\-echo setting, and the
\f[B]\-\-emap\f[] local\-echo mapping.
This feature is useful, for example, if the serial device needs some
special magic strings to start responding.
Use \f[B]echo(1)\f[] or \f[B]xxd(1)\f[] to generate special characters
like a CR or binary data.
Example:
.RS
.IP
.nf
\f[C]
picocom\ \-t\ "$(echo\ \-ne\ \[aq]AAATZ\\r\\n\[aq])"\ /dev/ttyS0
\f[]
.fi
.PP
Note, that the init string is not sent if \f[B]\-\-noinit\f[] is given.
(Default: empty).
.RE
.TP
.B \f[B]\-\-lower\-rts\f[]
Lower the RTS modem control signal after opening the serial port.
Only supported when flow\-control mode is not set to RTS/CTS, ignored
otherwise.
Only supported on some systems.
.RS
.PP
If neither \f[B]\-\-lower\-rts\f[] nor \f[B]\-\-raise\-rts\f[] are
given, the state of the RTS signal, after opening and configuring the
port, is system dependent.
On most systems the signal is raised.
.RE
.TP
.B \f[B]\-\-raise\-rts\f[]
Raise the RTS modem control signal after opening the serial port.
Only supported when flow\-control mode is not set to RTS/CTS, ignored
otherwise.
Only supported on some systems.
.RS
.PP
If neither \f[B]\-\-raise\-rts\f[] nor \f[B]\-\-lower\-rts\f[] are
given, the state of the RTS signal, after opening and configuring the
port, is system dependent.
On most systems the signal is raised.
.RE
.TP
.B \f[B]\-\-lower\-dtr\f[]
Lower the DTR control signal after opening the serial port.
Only supported on some systems.
.RS
.PP
If neither \f[B]\-\-lower\-dtr\f[] nor \f[B]\-\-raise\-dtr\f[] are
given, the state of the DTR signal, after opening and configuring the
port, is system dependent.
On most systems the signal is raised.
.RE
.TP
.B \f[B]\-\-raise\-dtr\f[]
Raise the DTR control signal after opening the serial port.
Only supported on some systems.
.RS
.PP
If neither \f[B]\-\-raise\-dtr\f[] nor \f[B]\-\-lower\-dtr\f[] are
given, the state of the DTR signal, after opening and configuring the
port, is system dependent.
On most systems the signal is raised.
.RE
.TP
.B \f[B]\-\-exit\-aftrer\f[] | \f[B]\-x\f[]
Exit picocom if it remains idle for the specified time (in
milliseconds).
Picocom is considered idle if: Nothing is read (received) from the
serial port, AND there is nothing to write (send) to the serial port,
AND nothing is read from the standard input (terminal).
If \f[B]\-\-exit\-after\f[] is set to zero, then picocom exits after
opening and configuring the serial port, after sending the init string
(if any, see option \f[B]\-\-initstring\f[]) and immediately when it
becomes idle.
When exiting after being idle, picocom drains the O/S serial port output
buffer (i.e.
waits for data already written to the port to be transmitted) and
observes the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] options as
usual.
(Default: not set).
.RS
.PP
NOTICE: If \f[B]\-\-exit\-after\f[] is set, reading zero bytes from the
standard input (which usually means that whatever was connected there
has been closed), will \f[I]not\f[] cause picocom to exit.
Instead, picocom will keep running, \f[I]without\f[] reading from stdin,
and will exit only when it becomes idle for the specified time, or if it
is killed by a signal.
If \f[B]\-\-exit\-after\f[] is \f[I]not\f[] set, then reading zero bytes
from the standard input causes picocom to exit, after the contents of
its output queue have been transmitted.
.RE
.TP
.B \f[B]\-\-exit\f[] | \f[B]\-X\f[]
Exit picocom immediately after opening and configuring the serial port.
Do \f[I]not\f[] read \f[I]anything\f[] from the standard input or from
the serial port.
When exiting the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[] options
are observed as usual.
With \f[B]\-\-exit\f[] and \f[B]\-\-noreset\f[] (and possibly
\f[B]\-\-hangup\f[]) picocom can be used as a very crude replacement of
\f[B]stty(1)\f[].
If an init string is also given (see \f[B]\-\-initstring\f[] option),
picocom exits imediatelly after sending (writing) the init string to the
serial port and draining the O/S serial port output buffer (i.e.
waiting for data written to the port to be transmitted).
Again, nothing is read from the standard input, or from the serial port.
The \f[B]\-\-exit\f[] option, overrides the \f[B]\-\-exit\-after\f[]
option.
(Default: Disabled)
.RS
.RE
.TP
.B \f[B]\-\-quiet\f[] | \f[B]\-q\f[]
Forces picocom to be quiet.
Suppresses the output of the initial status and options information, as
well as any other information or messages not explicitly requested by
the user.
Responses to user commands and any error or warning messages are still
printed.
.RS
.RE
.TP
.B \f[B]\-\-help\f[] | \f[B]\-h\f[]
Print a short help message describing the command\-line options.
Picocom\[aq]s version, compile\-time options, and enabled features are
also shown.
.RS
.RE
.SH DISPLAY OF OPTIONS AND PORT SETTINGS
.PP
The "show program options" command (\f[B]C\-v\f[]), as well as the
commands that change program options (\f[B]C\-b\f[], \f[B]C\-u\f[],
\f[B]C\-d\f[], \f[B]C\-f\f[], etc) print messages showing the current
values (or the new values, if they were changed) for the respective
options.
If picocom determines that an actual serial\-port setting differs from
the current value of the respective option (for whatever reason), then
the value of the option is shown followed by the value of the actual
serial\-port setting in parenthesis.
Example:
.IP
.nf
\f[C]
***\ baud:\ 115200\ (9600)
\f[]
.fi
.PP
This means that a baud rate of 115200bps has been selected (from the
command line, or using commands that change the baudrate) but the
serial\-port is actually operating at 9600bps (the driver may not
support the higher setting, and has silently replaced it with a safe
default, or the setting may have been changed from outside picocom).
If the option and the corresponding serial\-port setting are the same,
only a single value is shown.
Example:
.IP
.nf
\f[C]
***\ baud:\ 9600
\f[]
.fi
.PP
This behavior was introduced in picocom 2.0.
Older releases displayed only the option values, not the actual
serial\-port settings corresponding to them.
.PP
On startup, after the serial port is opened and configured (and assuming
that neither the \f[B]\-\-noinit\f[], nor the \f[B]\-\-quiet\f[] command
line options have been given), the port settings are silently checked.
If any mismatch is detected between the requested and the actual port
settings, a warning message is displayed.
You may then use the \f[B]C\-v\f[] command to determine the exact
mismatch or mismatches.
.SH SENDING AND RECEIVING FILES
.PP
Picocom 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:
.IP \[bu] 2
\f[B]rx(1)\f[] \- receive using the X\-MODEM protocol
.IP \[bu] 2
\f[B]rb(1)\f[] \- receive using the Y\-MODEM protocol
.IP \[bu] 2
\f[B]rz(1)\f[] \- receive using the Z\-MODEM protocol
.IP \[bu] 2
\f[B]sx(1)\f[] \- send using the X\-MODEM protocol
.IP \[bu] 2
\f[B]sb(1)\f[] \- send using the Y\-MODEM protocol
.IP \[bu] 2
\f[B]sz(1)\f[] \- send using the Z\-MODEM protocol
.IP \[bu] 2
\f[B]ascii\-xfr(1)\f[] \- receive or transmit ASCII files
.PP
The name of, and the command\-line options to, the program to be used
for transmitting files are given by the \f[B]\-\-send\-cmd\f[] option.
Similarly the program to receive files, and its arguments, are given by
the \f[B]\-\-receive\-cmd\f[] option.
For example, in order to start a picocom session that uses
\f[B]sz(1)\f[] to transmit files, and \f[B]rz(1)\f[] to receive files,
you have to say something like this:
.IP
.nf
\f[C]
picocom\ \-\-send\-cmd\ "sz\ \-vv"\ \-\-receive\-cmd\ "rz\ \-vv"\ ...
\f[]
.fi
.PP
If the argument to the \f[B]\-send\-cmd\f[] option, or the argument to
the \f[B]\-\-receive\-cmd\f[] option is the empty string, then the
respective command is disabled.
For example, in order to disable both the "send" and the "receive"
commands you can invoke picocom like this:
.IP
.nf
\f[C]
picocom\ \-\-send\-cmd\ \[aq]\[aq]\ \-\-receive\-cmd\ \[aq]\[aq]\ ...
\f[]
.fi
.PP
A picocom session with both, the send\- and the receive\-file commands
disabled does not \f[B]fork(2)\f[] and does not run any external
programs.
.PP
During the picocom session, if you key the "send" or "receive" commands
(e.g.
by pressing \f[B]C\-a\f[], \f[B]C\-s\f[], or \f[B]C\-a\f[],
\f[B]C\-r\f[]) 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.
Command\-line editing and rudimentary pathname completion are available
at this prompt, if you have compiled picocom with support for the
linenoise library.
Pressing \f[B]C\-c\f[] at this prompt will cancel the file transfer
command and return to normal picocom operation.
After entering a filename (and / or additional transmission or reception
program arguments) and assuming you have not canceled the operation by
pressing \f[B]C\-c\f[], picocom will start the external program as
specified by the \f[B]\-\-send\-cmd\f[], or \f[B]\-\-receive\-cmd\f[]
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 \f[B]C\-c\f[] while the external program is running will
prematurely terminate it (assuming that the program itself does not
ignore SIGINT), and return control to picocom.
Pressing \f[B]C\-c\f[] at any other time, has no special effect; the
character is normally passed to the serial port.
.SH INPUT, OUTPUT, AND ECHO MAPPING
.PP
Using the \f[B]\-\-imap\f[], \f[B]\-\-omap\f[], and \f[B]\-\-emap\f[]
options you can make picocom map (translate, replace) certain special
characters after being read from the serial port (with
\f[B]\-\-imap\f[]), before being written to the serial port (with
\f[B]\-\-omap\f[]), and before being locally echoed to the terminal
(standard output) if local echo is enabled (with \f[B]\-\-emap\f[]).
These mapping options take, each, a single argument which is a
comma\-separated list of one or more of the following identifiers:
.IP \[bu] 2
\f[B]crlf\f[] (map CR to LF),
.IP \[bu] 2
\f[B]crcrlf\f[] (map CR to CR + LF),
.IP \[bu] 2
\f[B]igncr\f[] (ignore CR),
.IP \[bu] 2
\f[B]lfcr\f[] (map LF to CR),
.IP \[bu] 2
\f[B]lfcrlf\f[] (map LF to CR + LF),
.IP \[bu] 2
\f[B]ignlf\f[] (ignore LF),
.IP \[bu] 2
\f[B]bsdel\f[] (map BS to DEL),
.IP \[bu] 2
\f[B]delbs\f[] (map DEL to BS)
.IP \[bu] 2
\f[B]spchex\f[] (map special chars (< 0x20 || 0x7f), excl.
CR, LF, and TAB to hex)
.IP \[bu] 2
\f[B]tabhex\f[] (map TAB to hex)
.IP \[bu] 2
\f[B]crhex\f[] (map CR to hex)
.IP \[bu] 2
\f[B]lfhex\f[] (map LF to hex)
.IP \[bu] 2
\f[B]8bithex\f[] (map chars with 8th\-bit set to hex)
.IP \[bu] 2
\f[B]nrmhex\f[] (map normal ascii chars (0x20 <= c < 0x7f) to hex)
.PP
The "to hex" mappings (\f[B]???hex\f[]) replace the respective
characters with their hexadecimal representation (in square brackets),
like this:
.IP
.nf
\f[C]
CR\ \-\->\ [0d]
\f[]
.fi
.PP
If more than one mappings are provided that apply to the same character,
then only the first mapping, in the order listed above, is applied.
.PP
For example the command:
.IP
.nf
\f[C]
picocom\ \-\-omap\ crlf,delbs\ \-\-imap\ ignlf,bsdel\ \-\-emap\ crcrlf\ ...
\f[]
.fi
.PP
will:
.IP \[bu] 2
Replace every CR (carriage return, 0x0d) character with LF (line feed,
0x0a) and every DEL (delete, 0x7f) character with BS (backspace, 0x08)
before writing it to the serial port.
.IP \[bu] 2
Ignore (not write to the terminal) every LF character read from the
serial port, and replace every BS character read from the serial port
with DEL.
.IP \[bu] 2
Replace every CR character with CR and LF when echoing to the terminal
(if local\-echo is enabled).
.SH EXITING PICOCOM
.PP
This section summarizes the conditions in which picocom terminates its
operation and what happens in each such condition:
.IP \[bu] 2
The exit command is seen in the standard input.
That is, the escape character is seen (default \f[B]C\-a\f[]), followed
by the exit command character (default \f[B]C\-x\f[]).
In this case: The contents of the output queue (data read from the
standard input, but not yet written to the port) as well as the contents
of the O/S serial port output buffer (data already written to the port,
but not yet transmitted) are discarded (flushed).
Then the serial port is reset to it\[aq]s original settings, and the
modem\-control lines are cleared signaling a modem reset, subject to the
\f[B]\-\-noreset\f[] and the \f[B]\-\-hangup\f[] options.
After that picocom exits with a success status.
.IP \[bu] 2
The quit command is seen in the standard input.
That is, the escape character is seen (default \f[B]C\-a\f[]), followed
by the quit command character (default \f[B]C\-q\f[]).
The behavior in this case is similar to that of the exit command, with
one difference: Picocom behaves as if the \f[B]\-\-noreset\f[] option is
given (regardless if it actually is, or not).
.IP \[bu] 2
The \f[B]\-\-exit\f[] option is given.
See the documentation of this option for a description of what exactly
happens in this case.
Picocom exits with a success exit status.
.IP \[bu] 2
The \f[B]\-\-exit\-after\f[] option is given.
See the documentation of this option for a description of what exactly
happens in this case.
Picocom exits with a success exit status.
.IP \[bu] 2
Zero bytes are read from the standard input.
This usually means that whatever was connected to picocom\[aq]s standard
input has been closed or, if a file was connected, then picocom has read
up to the end of the file.
In this case, if the \f[B]\-\-exit\-after\f[] option is \f[I]not\f[]
given, picocom stops reading from the standard input, and keeps
operating normally (i.e.
writing to, and reading from, the serial port) until its output queue
empties.
When this happens, picocom waits for the O/S serial port output buffer
to drain and then (subject to the \f[B]\-\-noreset\f[] and
\f[B]\-\-hangup\f[] options) resets the serial port to it\[aq]s initial
settings, clears the modem\-control lines, and exits.
If the \f[B]\-\-exit\-after\f[] option is given then, again, picocom
stops reading from the standard input and continues operating normally
but, in this case, it does so until it becomes idle for the specified
amount of time, before exiting.
Picocom exits with a success exit status.
.IP \[bu] 2
Picocom is killed by the TERM or INT signal, or an unrecoverable error
occurs.
In this case picocom behaves as if it had received the exit command,
that is: The contents of the output queue and the contents of the O/S
serial port output buffer are discarded (flushed).
Then, subject to the \f[B]\-\-noreset\f[] and \f[B]\-\-hangup\f[]
options, the serial port is reset to its original settings, the modem
control lines are cleared, and picocom exits with a failure status.
.SH AUTHOR
.PP
Written by Nick Patavalis <npat@efault.net>
.SH AVAILABILITY
.PP
Download the latest release from:
<https://github.com/npat-efault/picocom/releases>
.SH COPYRIGHT
.PP
Copyright (c) 2003\-2018 Nick Patavalis
.PP
This file is part of Picocom.
.PP
Picocom is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your
option) any later version.
.PP
Picocom is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111\-1307 USA