MINICOM (1)
friendly serial communication program
SYNOPSIS
minicom
[-somlz8] [-c on|off] [-S script] [-d entry]
15
[-a on|off] [-t term] [-p pty] [-C capturefile] [ configuration ]
DESCRIPTION
minicom
is a communication program which somewhat resembles the shareware
program TELIX but is free with source code and runs under most unices.
Features include dialing directory with auto-redial, support for
UUCP-style lock files on serial devices, a seperate script language
interpreter, capture to file, multiple users with individual
configurations, and more.
COMMAND-LINE
-s
S etup.
Root edits the system-wide defaults in /etc/minirc.dfl with this option.
When it is used, minicom does
not
initialize, but puts you directly into the
configuration menu. This is very handy if minicom refuses to start up
because your system has changed, or for the first time you run
minicom. For most systems, reasonable defaults are already compiled in.
-o
Do not initialize. Minicom will skip the initialization code. This
option is handy if you quitted from minicom without resetting, and
then want to restart a session. It is potentially dangerous though: no
check for lock files etc. is made, so a normal user could interfere
with things like uucp... Maybe this will be taken out later. For now
it is assumed, that users who are given access to a modem are
responsible enough for their actions.
-m
Override command-key with the Meta or ALT key. This is the default in 1.80
and it can also be configured in one of minicom's menus, but if you use
different terminals all the time, of which some don't have a Meta or ALT key,
it's handy to set the default command key to Ctrl-A and use this option
when you have a keyboard supporting Meta or ALT keys. Minicom
assumes that your Meta key sends the ESC prefix, not the other variant
that sets the highest bit of the character.
-M
Same as -m, but assumes that your Meta key sets the 8th bit of the
character high (sends 128 + character code).
-z
Use terminal status line. This only works on terminals that support it
and that have the relevant information in their termcap or
terminfo database entry.
-l
L iteral
translation of characters with the high bit set. With this flag on,
minicom will not try to translate the IBM line characters to ASCII,
but passes them straight trough. Many PC-unix clones will display
them correctly without translation (Linux in a special mode, Coherent
and Sco).
-a
A ttribute
usage. Some terminals, notably televideo's, have a rotten attribute
handling (serial instead of parallel). By default, minicom uses '-a
on', but if you are using such a terminal you can (must!) supply the
option '-a off'. The trailing 'on' or 'off' is needed.
-t
T erminal
type. With this flag, you can override the environment TERM variable.
This is handy for use in the MINICOM environment variable; one can create
a special termcap entry for use with minicom on the console, that
initializes the screen to raw mode so that in conjunction with the -l
flag, the IBM line characters are displayed untranslated.
-c
C olor
usage. Some terminals (such as the Linux console) support color with
the standard ANSI escape sequences. Because there is apparently no
termcap support for color, these escape sequences are hard-coded into
minicom. Therefore this option is off by default. You can turn it on
with '-c on'. This, and the '-m' option, are good candidates to put
into the MINICOM environment variable.
-S
script .
Run the named script at startup. So far, passing username and password
to a startup script is not supported. If you also use the -d option to
start dialing at startup, the -S script will be run BEFORE dialing the
entry specified with -d.
-d
D ial
an entry from the dialing directory on startup. You can specify an
index number, but also a substring of the name of the entry. The dialing
will start after all other program initialization procedures.
-p
P seudo
terminal
to use. This overrrides the terminal port defined in the configuration
files, but only if it is a pseudo tty. The filename supplied must be of
the form (/dev/)tty[p-z][0-f].
-C
filename .
Open capture file at startup.
-8
'8bit clean' and 'continuous' mode. '8bit clean' means Minicom let
8bit characters pass through without any modification. 'Continuous'
means no locate/attribute control sequences are inserted without
real change of locate/attribute. This mode is to display 8bit
multibyte characters such as Japanese. Not needed in every language with
8bit characters. (For example displaying Finnish text doesn't need this.)
When
minicom
starts, it first searches the MINICOM environment variable for
command-line arguments, which can be over-ridden on the command line.
Thus, if you have done
MINICOM='-m -c on'
export MINICOM
or the equivalent, and start minicom, minicom will assume that your
terminal
has
a Meta or <ALT> key and that color is supported. If you then log in
from a terminal without color support, and you have set MINICOM in your
startup (.profile or equivalent) file, and don't want to re-set your
environment variable, you can type 'minicom -c off' and run without
color support for that session.
configuration
The
configuration
argument is more interesting. Normally, minicom gets its defaults from
a file called "minirc.dfl". If you however give an argument to
minicom, it will try to get its defaults from a file called
"minirc.configuration\|". So it is possible to create multiple
configuration files, for different ports, different users etc. Most
sensible is to use device names, such as tty1, tty64, sio2 etc. If a
user creates his own configuration file, it will show up in his home
directory as '.minirc.dfl'.
USE
Minicom is windows-based. To popup a window with the function you
want, press Control-A (from now on, we will use C-A to mean
Control-A), and then the function key (a-z or A-Z). By pressing C-A
first and then 'z', a help screen comes up with a short summary of all
commands. This escape key can be altered when minicom is configured
(-s option or C-A O), but we'll stick to Control-A for now.
For every menu the next keys can be used:
UP
DOWN
LEFT
RIGHT
CHOOSE
CANCEL
The screen is divided into two portions: the upper 24 lines are the
terminal-emulator screen. In this window, ANSI or VT100 escape
sequences are interpreted. If there is a line left at the
bottom, a status line is placed there. If this is not possible the
status line will be showed every time you press C-A. On terminals
that have a special status line that will be used if the termcap
information is complete and the -k flag has been given.
Possible commands are listed next, in alphabetical order.
C-A
Pressing C-A a second time will just send a C-A to the remote system.
If you have changed your "escape character" to something other than
C-A, this works analogously for that character.
A
Toggle 'Add Linefeed' on/off. If it is on, a linefeed is added before
every carriage return displayed on the screen.
B
Gives you a scroll back buffer. You can scroll up with u, down with
d, a page up with b, a page down with f, and if you have them
the arrow and page up/page down keys can also be used. You can
search for text in the buffer with s (case-sensitive) or S
(case-insensitive). N will find the next occurrence of the string.
c will enter citation mode. A text cursor appears and you
specify the start line by hitting Enter key. Then scroll back mode will
finish and the contents with prefix '>' will be sent.
C
D
Dial a number, or go to the dialing directory.
E
Toggle local echo on and off (if your version of minicom supports it).
F
A break signal is sent to the modem.
G
Run script (Go). Runs a login script.
H
I
Toggle the type of escape sequence that the cursor keys send between
normal and applications mode. (See also the comment about the status
line below).
J
Jump to a shell. On return, the whole screen will be redrawn.
K
Clears the screen, runs kermit and redraws the screen upon return.
L
Turn Capture file on off. If turned on, all output sent to the screen
will be captured in the file too.
M
Sends the modem initialization string. If you are online and the DCD line
setting is on, you are asked for confirmation before the modem is
initialized.
O
Configure minicom. Puts you in the configuration menu.
P
Communication Parameters. Allows you to change the bps rate, parity and
number of bits.
Q
Exit minicom without resetting the modem. If macros changed and were not
saved, you will have a chance to do so.
R
Receive files. Choose from various protocols (external). If you have the
filename selection window and the prompt for download directory enabled,
you'll get a selection window for choosing the directory for
downloading. Otherwise the download directory defined in the Filenames and
paths menu will be used.
S
Send files. Choose the protocol like you do with the receive command. If
you don't have the filename selection window enabled (in the File transfer
protocols menu), you'll just have to write the filename(s) in a dialog
window. If you have the selection window enabled, a window will pop up
showing the filenames in your upload directory. You can tag and untag
filenames by pressing spacebar, and move the cursor up and down with the
cursor keys or j/k. The selected filenames are shown highlighted. Directory
names are shown [within brackets] and you can move up or down in the
directory tree by pressing the spacebar twice. Finally, send the files by
pressing ENTER or quit by pressing ESC.
T
Choose Terminal emulation: Ansi(color) or vt100.
You can also change the backspace key here and turn the status line on or off.
W
X
Exit minicom, reset modem. If macros changed and were not saved, you will
have a chance to do so.
Z
DIALING DIRECTORY
By pressing C-A D the program puts you in the dialing directory. You can
add, delete or edit entries. By choosing "dial" the phone numbers of the
tagged entries, or if nothing is tagged, the number of the highlighted
entry will be dialed. While the modem is dialing, you can press escape to
cancel dialing. Any other key will close the dial window, but won't cancel
the dialing itself. Your dialing directory will be saved into a the file
".dialdir" in your home directory. You can scroll up and down with the
arrow keys, but you can also scroll complete pages by pressing the PageUp
or PageDown key. If you don't have those, use Control-B (Backward) and
Control-F (Forward). You can use the space bar to tag a number of
entries and minicom will rotate trough this list if a connection can't be
made. A '>' symbol is drawn in the directory before the names of the tagged
entries.
The "edit" menu speaks for itself, but I will discuss it briefly here.
A - Name
B - Number
and its telephone number.
C - Dial string #
Which specific dial string you want to use to connect. There are three
different dial strings (prefixes and suffixes) that can be configured
in the Modem and dialing menu.
D - Local echo
can be on or off for this system (if your version of minicom supports it).
E - Script
The script that must be executed after a succesfull connection is made
(see the manual for runscript)
F - Username
The username that is passed to the runscript program. It
is passed in the environment string "$LOGIN".
G - Password
The password is passed as "$PASS".
H - Terminal Emulation
Use ANSI or VT100 emulation.
I - Backspace key sends
What code (Backspace or Delete) the backspace key sends.
J - Linewrap
K - Line settings
Bps rate, bits and parity to use for this connection. You can choose
current for the speed, so that it will use whatever speed is being
used at that moment (useful if you have multiple modems).
L - Conversion table
You may spacify a character conversion table to be loaded whenever this
entry answers, before running the login script. If this field is blank,
the conversion table stays unchanged.
The edit menu also shows the latest date and time when you called this
entry and the total number of calls there, but doesn't let you change them.
They are updated automatically when you connect.
CONFIGURATION
By pressing C-A O you will be thrown into the setup menu. Most
settings there can be changed by everyone, but some are restricted
to root only. Those priviliged settings are marked with a star (*) here.
Filenames and paths
This menu defines your default directories.
A - download
where the downloaded files go to.
B - upload
where the uploaded files are read from.
C - script
Where you keep your login scripts.
D - Script program
Which program to use as the script interpreter. Defaults to the
program "runscript", but if you want to use something else (eg,
/bin/sh or "expect") it is possible. Stdin and stdout are connected
to the modem, stderr to the screen.
If the path is relative (ie, does not start with a slash) then it's
relative to your home directory, except for the script interpreter.
E - Kermit program
Where to find the executable for kermit, and it's options. Some simple
macro's can be used on the command line: '%l' is expanded to the
complete filename of the dial out-device, and '%b' is expanded to
the current baudrate.
File Transfer Protocols
Protocols defined here will show up when C-A s/r is pressed. "Name" in the
beginning of the line is the name that will show up in the menu. "Program"
is the path to the protocol. "Name" after that defines if the program needs
an argument, eg. a file to be transmitted. U/D defines if this entry should
show up in the upload or the download menu. Fullscr defines if the program
should run full screen, or that minicom will only show it's stderr in a
window. IO-Red defines if minicom should attach the program's standard in
and output to the modem port or not. "Multi" tells the filename selection
window whether or not the protocol can send multiple files with one
command. It has no effect on download protocols, and it is also ignored
with upload protocols if you don't use the filename selection window. The
old sz and rz are not full screen, and have IO-Red set. However, there are
curses based versions of at least rz that do not want their stdin and
stdout redirected, and run full screen. All file transfer protocols are
run with the UID of the user, and not with UID=root. '%l' and '%b' can be
used on the command line as with kermit. Within this menu you can also
define if you want to use the filename selection window when prompted for
files to upload, and if you like to be prompted for the download directory
every time the automatic download is started. If you leave the download
directory prompt disabled, the download directory defined in the file and
directory menu is used.
Serial port setup
*A - Serial device
/dev/tty1 for most people.
/dev/cua<n> or /dev/modem under linux.
If you have modems connected to two or more serial ports, you may specify
all of them here in a list separated by space, comma or semicolon. When
Minicom starts, it checks the list until it finds an available modem and
uses that one. (However, you can't specify different init strings to
them ..at least not yet.)
*B - Lock file location
On most systems This should be /usr/spool/uucp. Linux systems use
/var/lock. If this directory does not exist,
minicom will not attempt to use lockfiles.
*C - Callin program
If you have a uugetty or something on your serial port, it could be
that you want a program to be run to switch the modem cq. port into
dialin/dialout mode. This is the program to get into dialin mode.
*D - Callout program
And this to get into dialout mode.
E - Bps/Par/Bits
Default parameters at startup.
If one of the entries is left blank, it will not be used. So if you
don't care about locking, and don't have a getty running on your
modemline, entries B - D should be left blank. Be warned! The callin
and callout programs are run with the effective user id of "root", eg
0!
Modem and Dialing
Here, the parameters for your modem are defined. I will not explain
this further because the defaults are for generic Hayes modems, and
should work always. This file is not a Hayes tutorial :-) The only
things worth noticing are that control characters can be sent by
prefixing them with a '^', in which '^^' means '^' itself, and the '\\'
character must also be doubled as '\\\\', because backslash is used
specially in the macro definitions. Some options however, don't have
much to do with the modem but more with the behaviour of minicom itself:
M - Dial time
The number of seconds before minicom times out if no connection is
established.
N - Delay before redial
Minicom will redial if no connection was made, but it first waits some
time.
O - Number of tries
Maximum number of times that minicom attempts to dial.
P - Auto speed detect
If this is on, minicom tries to match the dialed party's speed.
With most modern modems this is NOT desirable, since the modem buffers
the data and converts the speed.
Q - Drop DTR to hangup
If you set this to 0, minicom hangs up by sending a Hayes-type hangup
sequence. If you specify a non-zero value, the hangup will be done by
dropping the DTR line. The value tells in seconds how long DTR will be
kept down.
R - Modem has DCD line
If your modem, and your O/S both support the DCD line (that goes 'high'
when a connection is made) minicom will use it.
Note that a special exception is made for this menu: every user
can change all parameters here, but they will not be saved.
Screen and keyboard
A - Command key is
the 'Hot Key' that brings you into command mode. If this is set
to 'ALT' or 'meta key', you can directly call commands
by alt-key instead of HotKey-key.
B - Backspace key sends
There still are some systems that want a VT100 to send DEL instead of
BS. With this option you can enable that stupidity. (Eh, it's even on
by default...)
C - Status line is
Enabled or disabled. Some slow terminals (for example, X-terminals)
cause the status line to jump "up and down" when scrolling, so you can
turn it off if desired. It will still be shown in command-mode.
D - Alarm sound
If turned on, minicom will sound an alarm (on the console only) after
a succesfull connection and when up/downloading is complete.
E - Foreground Color (menu)
indicates
the foreground color to use for all the configuration windows in minicom.
F - Background Color (menu)
indicates the background color to use for
all the configuration windows in minicom. Note that minicom will not allow
you to set forground and background colors to the same value.
G - Foreground Color (term)
indicates the foreground color to use in the terminal window.
H - Background Color (term)
indicates the background color to use in
the terminal window. Note that minicom will not allow you to set forground
and background colors to the same value.
I - Foreground Color (stat)
indicates the foreground color to use in for the status bar.
J - Background Color (stat)
indicates the color to use in for the
status bar. Note that minicom will allow you to set the status bar's
forground and background colors to the same value. This will effectively
make the status bar invisible but if these are your intensions, please
see the option
K - History buffer size
The number of lines to keep in the history buffer (for backscrolling).
L - Macros file
is the full path to the file that holds
macros. Macros allow you to define a string to be sent when you press
a certain key. In minicom, you may define F1 through F10 to send
up to 256 characters [this is set at compile time]. The filename you
specify is verified as soon as you hit ENTER. If you do not have permissions
to create the specified file, an error message will so indicate and you
will be forced to re-edit the filename. If you are permitted to create
the file, minicom checks to see if it already exists. If so, it assumes
it's a macro file and reads it in. If it isn't, well, it's your problem :-)
If the file does not exist, the filename is accepted.
M - Edit Macros
opens up a new window
which allows you to edit the F1 through F10 macros.
N - Macros enabled
- Yes or No. If macros are disabled, the F1-F10
keys will just send the VT100/VT220 function key escape sequences.
O - Character conversion
The active conversion table filename is shown here. If you can see no
name, no conversion is active. Pressing O, you will see the conversion
table edit menu.
Edit Macros
Here, the macros for F1 through F10 are defined. The bottom of the
window shows a legend of character combinations that have special meaning.
They allow you to enter special control characters with plain text by
prefixing them with a '^', in which '^^' means '^' itself. You can
send a 1 second delay with the '^~' code. This is useful when you are
trying to login after ftp'ing or telnet'ing somewhere.
You can also include your current username and password from the phone
directory in the macros with '\\u' and '\\p', respectively. If you need
the backslash character in the macro, write it doubled as '\\\\'.
To edit a macro, press the number (or letter for F10) and you will be
moved to the end of the macro. When editing the line, you may use the
left & right arrows, Home & End keys, Delete & BackSpace, and ESC and
RETURN. ESC cancels any changes made while ENTER accepts the changes.
Character conversion
Here you can edit the character conversion table. If you are not an
American, you know that in many languages there are characters that are
not included in the ASCII character set, and in the old times they may
have replaced some less important characters in ASCII and now they are
often represented with character codes above 127. AND there are various
different ways to represent them. This is where you may edit conversion
tables for systems that use a character set different from the one on your
computer.
A - Load table
You probably guessed it. This command loads a table from the disk.
You are asked a file name for the table.
Predefined tables .mciso, .mcpc8 and .mcsf7 should be included with the
program. Table .mciso does no conversion, .mcpc8 is to be used for
connections with systems that use the 8-bit pc character set, and .mcsf7
is for compatibility with the systems that uses the good old 7-bit coding
to replace the characters {|}[]\\ with the diacritical characters used in
Finnish and Swedish.
B - Save table
This one saves the active table on the filename you specify.
C - edit char
This is where you can make your own modifications to the existing table.
First you are asked the character value (in decimal) whose conversion you
want to change. Next you'll say which character you want to see on your
screen when that character comes from the outside world. And then you'll
be asked what you want to be sent out when you enter that character from
your keyboard.
D - next screen
E - prev screen
Yeah, you probably noticed that this screen shows you what kind of
conversions are active. The screen just is (usually) too small to show
the whole table at once in an easy-to-understand format. This is how you can
scroll the table left and right.
F - convert capture
Toggles whether or not the character conversion table is used when
writing the capture file.
Save setup as dfl
Save the parameters as the default for the next time the program is
started. Instead of dfl, any other parameter name may appear, depending
on which one was used when the program was started.
Save setup as..
Save the parameters under a special name. Whenever Minicom is started
with this name as an argument, it will use these parameters. This
option is of course priviliged to root.
Exit
Escape from this menu without saving. This can also be done with ESC.
Exit from minicom
Only root will see this menu entry, if he/she started minicom with the '-s'
option. This way, it is possible to change the configuration without
actually running minicom.
STATUS LINE
The status line has several indicators, that speak for themselves.
The mysterious APP or NOR indicator probably needs explanation. The
VT100 cursor keys can be in two modes: applications mode and cursor
mode. This is controlled by an escape sequence. If you find that
the cursor keys do not work in, say, vi when you're logged in using
minicom then you can see with this indicator whether the cursor keys
are in applications or cursor mode. You can toggle the two with the
C-A I key. If the cursor keys then work, it's probably an error in
the remote system's termcap initialization strings (is).
LOCALES
Minicom has now support for local languages. This means you can change most
of the English messages and other strings to another language by setting
the environment variable LANG. On July 1998 the supported languages
are Brazilian Portuguese, Finnish and Japanese. Turkish is under
construction.
SECURITY ISSUES
Since Minicom is run setuid root on some computers, you probably want to
restrict access to it. This is possible by using a configuration file
in the same directory as the default files, called "minicom.users".
The syntax of this file is as following:
<username> <configuration> [configuration...]
To allow user 'miquels' to use the default configuration, enter the
following line into "minicom.users":
If you want users to be able to use more than the default
configurations, just add the names of those configurations behind the
user name. If no configuration is given behind the username, minicom
assumes that the user has access to all configurations.
MISC
If minicom is hung, kill it with SIGTERM . (This means kill -15, or
since sigterm is default, just plain "kill <minicompid>". This will
cause a graceful exit of minicom, doing resets and everything.
You may kill minicom from a script with the command "! killall -9 minicom"
without hanging up the line. Without the -9 parameter, minicom first
hangs up before exiting.
Since a lot of escape sequences begin with ESC (Arrow up is ESC [ A),
Minicom does not know if the escape character it gets is you pressing
the escape key, or part of a sequence.
An old version of Minicom, V1.2, solved this in a rather crude way:
to get the escape key, you had to press it
twice .
As of release 1.3 this has bettered a little: now a 1-second timeout
is builtin, like in vi. For systems that have the select() system call
the timeout is 0.5 seconds. And... surprise: a special Linux-dependant
hack :-) was added. Now, minicom can separate the escape key and
escape-sequences. To see how dirty this was done, look into wkeys.c.
But it works like a charm!
FILES
Minicom keeps it's configuration files in one directory, usually
/var/lib/minicom, /usr/local/etc or /etc. To find out what default
directory minicom has compiled in, issue the command minicom -h.
You'll probably also find the demo files for runscript(1) there.
minicom.users
minirc.*
$HOME/.minirc.*
$HOME/.dialdir
/usr/share/locale/*/LC_MESSAGES/minicom.mo
VERSION
Minicom is now up to version 1.82.
AUTHORS
The original author of minicom is Miquel van
Smoorenburg (miquels@drinkel.ow.org, miquels@cistron.nl).
Jukka Lahtinen (walker@clinet.fi, walker@megabaud.fi) has been responsible
for new versions since 1.78, helped by some other people, including:
filipg@paranoia.com wrote the History buffer searching to 1.79.
Arnaldo Carvalho de Melo (acme@conectiva.com.br) did the internationalization
and the Brasilian Portuguese translations.
Jim Seymour (jseymour@jimsun.LinxNet.com) wrote the multiple modem support
and the filename selection window used since 1.80.
Tomohiro Kubota (kubota@debian.or.jp) wrote the Japanese translations
and the citation facility, and did some fixes.
Gaël Quéri (gqueri@mail.dotcom.fr) wrote the French translations.
Most of this man page is copied, with corrections, from the original minicom
README, but some pieces and the corrections are by Michael K. Johnson
(johnsonm@stolaf.edu).
Jukka Lahtinen (walker@clinet.fi) added some information of the changes
made after version 1.75.