1PICOCOM(1) User Commands PICOCOM(1)
2
6 picocom - minimal dumb-terminal emulation program
7
9 picocom [ options ] device
10
12 As its name suggests, picocom(1) is a minimal dumb-terminal emulation
13 program. It is, in principle, very much like minicom(1), only it's
14 "pico" instead of "mini"! It was designed to serve as a simple, manual,
15 modem configuration, testing, and debugging tool. It has also served
16 (quite well) as a low-tech serial communications program to allow
17 access to all types of devices that provide serial consoles. It could
18 also prove useful in many other similar tasks.
19 In effect, picocom is not an "emulator" per-se. It is a simple program
21 that opens, configures, manages a serial port (tty device) and its
22 settings, and connects to it the terminal emulator you are, most
23 likely, already using (the terminal window application, xterm, rxvt,
24 system console, etc).
25 When picocom starts it opens the tty (serial port) given as its
27 non-option argument. Unless the --noinit option is given, it
28 configures the port to the settings specified by the option-arguments
29 (or to some default settings), and sets it to "raw" mode. If --noinit
30 is given, the initialization and configuration is skipped; the port is
31 just opened. Following this, if standard input is a tty, picocom sets
32 the tty to raw mode. Then it goes in a loop where it listens for input
33 from stdin, or from the serial port. Input from the serial port is
34 copied to the standard output while input from the standard input is
35 copied to the serial port. Picocom also scans its input stream for a
36 user-specified control character, called the escape character (being by
37 default C-a). If the escape character is seen, then instead of sending
38 it to the serial-device, the program enters "command mode" and waits
39 for the next character (which is called the "function character").
40 Depending on the value of the function character, picocom performs one
41 of the operations described in the COMMANDS section below.
42
44 Commands are given to picocom by first keying the espace character
45 which by default is C-a (see OPTIONS below for how to change it), and
46 then keying one of the function (command) characters shown here.
47 escape character
49 Send the escape character to the serial port and return to
50 "transparent" mode. This means that if the escape character
51 (C-a, by default) is typed twice, the program sends the escape
52 character to the serial port, and remains in transparent mode.
53 C-x Exit the program. If the --noreset option is not given, then
55 the serial port is reset to its original settings before
56 exiting, and the modem control lines (typically DTR and RTS) are
57 cleared (lowered) signaling a modem hangup. If --noreset is
58 given (and --hangup is not), then the serial port settings are
59 not reset, and the modem control lines remain unaffected. If
60 both --noreset and --hangup are given, then the serial port
61 settings are not reset, but the modem-control lines are cleared.
62 C-q Quit the program without resetting the serial port to its
64 original settings. Terminating with the Quit command, picocom
65 behaves exactly as if the --noreset option was given. The
66 serial port is not reset to its original settings, and the modem
67 control lines remain unaffected or are cleared, subject to the
68 --hangup option.
69 C-p Pulse the DTR line. Lower it for 1 sec, and then raise it
71 again.
72 C-t Toggle the DTR line. If DTR is up, then lower it. If it is
74 down, then raise it. May not be supported on some systems.
75 C-g Toggle the RTS line. If RTS is up, then lower it. If it is
77 down, then raise it. Not supported if the flow control mode is
78 RTS/CTS. May not be supported on some systems.
79 C-backslash
81 Generate a break sequence on the serial line. A break sequence
82 is usually generated by marking (driving to logical one) the
83 serial Tx line for an amount of time coresponding to several
84 character durations.
85 C-b Set baudrate. Prompts you to enter a baudrate numerically (in
87 bps) and configures the serial port accordingly.
88 C-u Baud up. Increase the baud-rate. The list of baud-rates
90 stepped-through by this command is: 50, 75, 110, 134, 150, 200,
91 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200.
92 If HIGH_BAUD support is compiled-in, then the following
93 baud-rates are also added to the list: 230400, 460800, 500000,
94 576000, 921600, 1000000, 1152000, 1500000, 2000000, 2500000,
95 3000000, 3500000, 4000000. Depending on you system, any of the
96 higher baud rates may be missing.
97 C-d Baud down. Decrease the baud-rate. The list of baud-rates
99 stepped-through by this command is the same as for the "baud-up"
100 command.
101 C-f Cycle through flow-control settings (RTS/CTS, XON/XOFF, none).
103 C-y Cycle through parity settings (even, odd, none).
105 C-i Cycle through databits-number settings (5, 6, 7, 8).
107 C-j Cycle through stopbits-number settings (1, 2).
109 C-c Toggle local-echo mode.
111 C-w Write hex. Picococm prompts the user for a string of
113 hexadecimal values. Values can be entered with or without
114 delimeters (separators). The hexadecimal values are translated
115 to binary and sent to the port, exactly as if input at the
116 terminal (i.e. the --omap, --echo and --emap options are
117 observed). Example: The following sends the characters "ABCD"
118 to the port.
119 C-a C-w
121 *** hex: 41 4243:44
122 *** wrote 4 bytes ***
123 C-s Send (upload) a file. See SENDING AND RECEIVING FILES below.
125 C-r Receive (download) a file. See SENDING AND RECEIVING FILES
127 below.
128 C-v Show program options (like baud rate, data bits, etc) as well as
130 the actual serial port settings. Only the options and port
131 settings that can be modified online (through commands) are
132 shown, not those that can only be set at the command-line. See
133 DISPLAY OF OPTIONS AND PORT SETTINGS for details.
134 C-h or C-k
136 Show help, or show keys. Prints a short description of all
137 available function (command) keys.
138 After performing one of the above operations, the program leaves the
140 command mode and enters transparent mode. Example: To increase the
141 baud-rate by two steps, you have to type:
142 C-a, C-u, C-a, C-u
144 assuming of-course that C-a is the escape character.
146
148 Picocom accepts the following command-line options.
149 --baud | -b
151 Defines the baud-rate to set the serial-port (terminal) to.
152 --flow | -f
154 Defines the flow-control mode to set the serial-port to. Must
155 be one of: x for xon/xoff (software) mode, h for hardware flow
156 control (RTS/CTS), n for no flow control. (Default: n)
157 --parity | -y
159 Defines the parity mode to set the serial-port to. Must be one
160 of: o for odd parity mode, e for even parity mode, n for no
161 parity mode. (Default: n)
162 --databits | -d
164 Defines the number of data bits in every character. Must be one
165 of: 5, 6, 7, 8. (Default: 8)
166 --stopbits | -p
168 Defines the number of stop bits in every character. Must be one
169 of: 1, or 2. (Default: 1)
170 --escape | -e
172 Defines the character that will make picocom enter command-mode
173 (see description above). If x is given, then C-x will make
174 picocom enter command mode. See also the --no-escape option.
175 (Default: a)
176 --no-escape | -n
178 Disables the escape character. Picocom will never enter
179 command-mode if this option is given. To exit picocom, in this
180 case, you must either close its standard input, or send it the
181 TERM or INT signal. (Default: Disabled).
182 --echo | -c
184 Enable local echo. Every character being read from the terminal
185 (standard input) is echoed to the terminal (standard output)
186 subject to the echo-mapping configuration (see --emap option).
187 (Default: Disabled)
188 --noinit | -i
190 If given, picocom will not initialize, configure, or otherwise
191 mess with the serial port at start-up. It will just open it.
192 This is useful, for example, for connecting picocom to
193 already-connected modems, or already configured ports without
194 terminating the connection, or altering their settings. If
195 required, serial port parameters can then be adjusted at
196 run-time by commands. See also the --noreset and --hangup
197 options. (Default: Disabled)
198 --noreset | -r
200 If given, picocom will not reset the serial port when exiting.
201 It will just close the respective file descriptor and do nothing
202 more. The serial port settings will not be restored to their
203 original values and, unless the --hangup option is also given,
204 the modem-control lines will not be affected. This is useful,
205 for example, for leaving modems connected when exiting picocom.
206 Regardless whether the --noreset option is given, the user can
207 exit picocom using the "Quit" command (instead of "Exit"), which
208 makes picocom behave exactly as if --noreset was given. See
209 also the --hangup option. (Default: Disabled)
210 NOTICE: Picocom clears the modem control lines on exit by
212 setting the HUPCL control bit of the respective port. Picocom
213 always sets HUPCL according to the --noreset and --hangup
214 options. If --noreset is given and --hangup is not, then HUPCL
215 for the port is cleared and will remain so after exiting
216 picocom. If --noreset is not given, or if both --noreset and
217 --hangup are given, then HUPCL is set for the port and will
218 remain so after exiting picocom. This is true, regardless of
219 the way picocom terminates (command, read zero-bytes from
220 standard input, killed by signal, fatal error, etc), and
221 regardless of the --noinit option.
222 --hangup | -u
224 If given together with --noreset, picocom will not reset the
225 serial port to it's original settings on exit, but it will clear
226 the modem control lines (typically DTR and RTS) to signal a
227 modem hangup. Without the --noreset option (explicitly given,
228 or implied by extiting with the "Quit" command) --hangup has no
229 effect (without --noreset picocom always clears the modem
230 control lines on exit, anyway).
231 --nolock | -l
233 If given, picocom will not attempt to lock the serial port
234 before opening it. Normally, depending on how it's compiled,
235 picocom attempts to get a UUCP-style lock-file (e.g.
236 '/var/lock/LCK..ttyS0') before opening the port, or attempts to
237 lock the port device-node using flock(2). Failing to do so,
238 results in the program exiting after emitting an error-message.
239 It is possible that your picocom binary is compiled without
240 support for locking. In this case the --nolock option is
241 accepted, but has no effect. (Default: Disabled)
242 --send-cmd | -s
244 Specifies the external program (and any arguments to it) that
245 will be used for transmitting files. If the argument to
246 --send-cmd is the empty string (''), the send-file command is
247 disabled. See SENDING AND RECEIVING FILES. (Default: sz -vv)
248 --receive-cmd | -v
250 Specifies the external program (and any arguments to it) that
251 will be used for receiving files. If the argument to
252 --receive-cmd is the empty string (''), the receive-file command
253 is disabled. See SENDING AND RECEIVING FILES. (Default: rz
254 -vv)
255 --imap Specifies the input character map (i.e. special characters to
257 be replaced when read from the serial port). See INPUT, OUTPUT,
258 AND ECHO MAPPING. (Defaul: Empty)
259 --omap Specifies the output character map (i.e. special characters to
261 be replaced before being written to serial port). See INPUT,
262 OUTPUT, AND ECHO MAPPING. (Defaul: Empty)
263 --emap Specifies the local-echo character map (i.e. special characters
265 to be replaced before being echoed-back to the terminal, if
266 local-echo is enabled). See INPUT, OUTPUT, AND ECHO MAPPING.
267 (Defaul: delbs,crcrlf)
268 --logfile | -g
270 Use specified file for logging (recording) serial input, and
271 possibly serial output. If the file exists, it is appended to.
272 Every character read from the serial port is written to the
273 specified file (before input mapping is performed). If
274 local-echo mode is is enabled (see --echo option and C-c
275 command), then every character written to the serial port (after
276 output mapping is performed) is also logged to the same file.
277 (Default: no logging)
278 --initstring | -t
280 Send the provided string after opening and configuring the
281 serial port. The init string is sent exactly as if it was input
282 at the terminal. Sending the init string, picocom observes the
283 --omap output mapping, the --echo local-echo setting, and the
284 --emap local-echo mapping. This feature is useful, for example,
285 if the serial device needs some special magic strings to start
286 responding. Use echo(1) or xxd(1) to generate special
287 characters like a CR or binary data. Example:
288 picocom -t "$(echo -ne 'AAATZ\r\n')" /dev/ttyS0
290 Note, that the init string is not sent if --noinit is given.
292 (Default: empty).
293 --lower-rts
295 Lower the RTS modem control signal after opening the serial
296 port. Only supported when flow-control mode is not set to
297 RTS/CTS, ignored otherwise. Only supported on some systems.
298 If neither --lower-rts nor --raise-rts are given, the state of
300 the RTS signal, after opening and configuring the port, is
301 system dependent. On most systems the signal is raised.
302 --raise-rts
304 Raise the RTS modem control signal after opening the serial
305 port. Only supported when flow-control mode is not set to
306 RTS/CTS, ignored otherwise. Only supported on some systems.
307 If neither --raise-rts nor --lower-rts are given, the state of
309 the RTS signal, after opening and configuring the port, is
310 system dependent. On most systems the signal is raised.
311 --lower-dtr
313 Lower the DTR control signal after opening the serial port.
314 Only supported on some systems.
315 If neither --lower-dtr nor --raise-dtr are given, the state of
317 the DTR signal, after opening and configuring the port, is
318 system dependent. On most systems the signal is raised.
319 --raise-dtr
321 Raise the DTR control signal after opening the serial port.
322 Only supported on some systems.
323 If neither --raise-dtr nor --lower-dtr are given, the state of
325 the DTR signal, after opening and configuring the port, is
326 system dependent. On most systems the signal is raised.
327 --exit-aftrer | -x
329 Exit picocom if it remains idle for the specified time (in
330 milliseconds). Picocom is considered idle if: Nothing is read
331 (received) from the serial port, AND there is nothing to write
332 (send) to the serial port, AND nothing is read from the standard
333 input (terminal). If --exit-after is set to zero, then picocom
334 exits after opening and configuring the serial port, after
335 sending the init string (if any, see option --initstring) and
336 imediatelly when it becomes idle. When exiting after being
337 idle, picocom drains the O/S serial port ouput buffer (i.e.
338 waits for data already written to the port to be transmitted)
339 and observes the --noreset and --hangup options as usual.
340 (Default: not set).
341 NOTICE: If --exit-after is set, reading zero bytes from the
343 standard input (which usually means that whatever was connected
344 there has been closed), will not cause picocom to exit.
345 Instead, picocom will keep running, without reading from stdin,
346 and will exit only when it becomes idle for the specified time,
347 or if it is killed by a signal. If --exit-after is not set,
348 then reading zero bytes from the standard input causes picocom
349 to exit, after the contents of its output queue have been
350 transmitted.
351 --exit | -X
353 Exit picocom immediatelly after opening and configuring the
354 serial port. Do not read anything from the standard input or
355 from the serial port. When exiting the --noreset and --hangup
356 options are observed as usual. With --exit and --noreset (and
357 possibly --hangup) picocom can be used as a very crude
358 replacement of stty(1). If an init string is also given (see
359 --initstring option), picocom exits imediatelly after sending
360 (writing) the init string to the serial port and draining the
361 O/S serial port output buffer (i.e. waiting for data written to
362 the port to be transmitted). Again, nothing is read from the
363 standard input, or from the serial port. The --exit option,
364 overrides the --exit-after option. (Default: Disabled)
365 --quiet | -q
367 Forces picocom to be quiet. Suppresses the output of the
368 initial status and options information, as well as any other
369 information or messages not explicitly requested by the user.
370 Responses to user commands and any error or warning messages are
371 still printed.
372 --help | -h
374 Print a short help message describing the command-line options.
375 Picocom's version, compile-time options, and enabled features
376 are also shown.
377
379 The "show program options" command (C-v), as well as the commands that
380 change program options (C-b, C-u, C-d, C-f, etc) print messages showing
381 the current values (or the new values, if they were changed) for the
382 respective options. If picocom determines that an actual serial-port
383 setting differs from the current value of the respective option (for
384 whatever reason), then the value of the option is shown followed by the
385 value of the actual serial-port setting in parenthesis. Example:
386 *** baud: 115200 (9600)
388 This means that a baud rate of 115200bps has been selected (from the
390 command line, or using commands that change the baudrate) but the
391 serial-port is actually operating at 9600bps (the driver may not
392 support the higher setting, and has silently replaced it with a safe
393 default, or the setting may have been changed from outside picocom).
394 If the option and the corresponding serial-port setting are the same,
395 only a single value is shown. Example:
396 *** baud: 9600
398 This behavior was introduced in picocom 2.0. Older releases displayed
400 only the option values, not the actual serial-port settings
401 corresponding to them.
402 On startup, after the serial port is opened and configured (and
404 assuming that neither the --noinit, nor the --quiet command line
405 options have been given), the port settings are silently checked. If
406 any mismatch is detected between the requested and the actual port
407 settings, a warning message is displayed. You may then use the C-v
408 command to determine the exact mismatch or mismatches.
409
411 Picocom can send and receive files over the serial port using external
412 programs that implement the respective protocols. In Linux typical
413 programs for this purpose are:
414 · rx(1) - receive using the X-MODEM protocol
416 · rb(1) - receive using the Y-MODEM protocol
418 · rz(1) - receive using the Z-MODEM protocol
420 · sx(1) - send using the X-MODEM protocol
422 · sb(1) - send using the Y-MODEM protocol
424 · sz(1) - send using the Z-MODEM protocol
426 · ascii-xfr(1) - receive or transmit ASCII files
428 The name of, and the command-line options to, the program to be used
430 for transmitting files are given by the --send-cmd option. Similarly
431 the program to receive files, and its arguments, are given by the
432 --receive-cmd option. For example, in order to start a picocom session
433 that uses sz(1) to transmit files, and rz(1) to receive files, you have
434 to say something like this:
435 picocom --send-cmd "sz -vv" --receive-cmd "rz -vv" ...
437 If the argument to the -send-cmd option, or the argument to the
439 --receive-cmd option is the empty string, then the respective command
440 is disabled. For example, in order to disable both the "send" and the
441 "receive" commands you can invoke picocom like this:
442 picocom --send-cmd '' --receive-cmd '' ...
444 A picocom session with both, the send- and the receive-file commands
446 disabled does not fork(2) and does not run any external programs.
447 During the picocom session, if you key the "send" or "receive" commands
449 (e.g. by pressing C-a, C-s, or C-a, C-r) you will be prompted for a
450 filename. At this prompt you can enter one or more file-names, and any
451 additional arguments to the transmission or reception program.
452 Command-line editing and rudimentary pathname completion are available
453 at this prompt, if you have compiled picocom with support for the
454 linenoise library. Pressing C-c at this prompt will cancel the file
455 transfer command and return to normal picocom operation. After
456 entering a filename (and / or additional transmission or reception
457 program arguments) and assuming you have not canceled the operation by
458 pressing C-c, picocom will start the external program as specified by
459 the --send-cmd, or --receive-cmd option, and with any filenames and
460 additional arguments you may have supplied. The standard input and
461 output of the external program will be connected to the serial port.
462 The standard error of the external program will be connected to the
463 terminal which---while the program is running---will revert to
464 canonical mode. Pressing C-c while the external program is running
465 will prematurely terminate it (assuming that the program itself does
466 not ignore SIGINT), and return control to picocom. Pressing C-c at any
467 other time, has no special effect; the character is normally passed to
468 the serial port.
469
471 Using the --imap, --omap, and --emap options you can make picocom map
472 (translate, replace) certain special characters after being read from
473 the serial port (with --imap), before being written to the serial port
474 (with --omap), and before being locally echoed to the terminal
475 (standard output) if local echo is enabled (with --emap). These
476 mapping options take, each, a single argument which is a
477 comma-separated list of one or more of the following identifiers:
478 · crlf (map CR to LF),
480 · crcrlf (map CR to CR + LF),
482 · igncr (ignore CR),
484 · lfcr (map LF to CR),
486 · lfcrlf (map LF to CR + LF),
488 · ignlf (ignore LF),
490 · bsdel (map BS to DEL),
492 · delbs (map DEL to BS)
494 · spchex (map special chars (< 0x20 || 0x7f), excl. CR, LF, and TAB to
496 hex)
497 · tabhex (map TAB to hex)
499 · crhex (map CR to hex)
501 · lfhex (map LF to hex)
503 · 8bithex (map chars with 8th-bit set to hex)
505 · nrmhex (map normal ascii chars (0x20 <= c < 0x7f) to hex)
507 The "to hex" mappings (???hex) replace the respective characters with
509 their hexadecimal representation (in square brackets), like this:
510 CR --> [0d]
512 If more than one mappings are provided that apply to the same
514 character, then only the first mapping, in the order listed above, is
515 applied.
516 For example the command:
518 picocom --omap crlf,delbs --imap ignlf,bsdel --emap crcrlf ...
520 will:
522 · Replace every CR (carriage return, 0x0d) character with LF (line
524 feed, 0x0a) and every DEL (delete, 0x7f) character with BS
525 (backspace, 0x08) before writing it to the serial port.
526 · Ignore (not write to the terminal) every LF character read from the
528 serial port, and replace every BS character read from the serial port
529 with DEL.
530 · Replace every CR character with CR and LF when echoing to the
532 terminal (if local-echo is enabled).
533
535 This section summarizes the conditions in which picocom terminates its
536 operation and what happens in each such condition:
537 · The exit command is seen in the standard input. That is, the escape
539 character is seen (default C-a), followed by the exit command
540 character (default C-x). In this case: The contents of the output
541 queue (data read from the standard input, but not yet written to the
542 port) as well as the contents of the O/S serial port output buffer
543 (data already written to the port, but not yet transmitted) are
544 discarded (flushed). Then the serial port is reset to it's original
545 settings, and the modem-control lines are cleared signaling a modem
546 reset, subject to the --noreset and the --hangup options. After that
547 picocom exits with a success status.
548 · The quit command is seen in the standard input. That is, the escape
550 character is seen (default C-a), followed by the quit command
551 character (default C-q). The behavior in this case is similar to
552 that of the exit command, with one difference: Picocom behaves as if
553 the --noreset option is given (regardless if it actualy is, or not).
554 · The --exit option is given. See the documentation of this option for
556 a description of what exactly happens in this case. Picocom exits
557 with a success exit status.
558 · The --exit-after option is given. See the documentation of this
560 option for a description of what exactly happens in this case.
561 Picocom exits with a success exit status.
562 · Zero bytes are read from the standard input. This usually means that
564 whatever was connected to picocom's standard input has been closed
565 or, if a file was connected, then picocom has read up to the end of
566 the file. In this case, if the --exit-after option is not given,
567 picocom stops reading from the standard input, and keeps operating
568 normally (i.e. writing to, and reading from, the serial port) until
569 its output queue empties. When this happens, picocom waits for the
570 O/S serial port output buffer to drain and then (subject to the
571 --noreset and --hangup options) resets the serial port to it's
572 initial settings, clears the modem-control lines, and exits. If the
573 --exit-after option is given then, again, picocom stops reading from
574 the standard input and continues operating normally but, in this
575 case, it does so until it becomes idle for the specified amount of
576 time, before exiting. Picocom exits with a success exit status.
577 · Picocom is killed by the TERM or INT signal, or an unrecoverable
579 error occurs. In this case picocom behaves as if it had received the
580 exit command, that is: The contents of the output queue and the
581 contents of the O/S serial port output buffer are discarded
582 (flushed). Then, subject to the --noreset and --hangup options, the
583 serial port is reset to its original settings, the modem control
584 lines are cleared, and picocom exits with a failure status.
585
587 Written by Nick Patavalis <npat@efault.net>
588
590 Download the latest release from: <https://github.com/npat-
591 efault/picocom/releases>
592
594 Copyright (c) 2003-2018 Nick Patavalis
595 This file is part of Picocom.
597 Picocom is free software; you can redistribute it and/or modify it
599 under the terms of the GNU General Public License as published by the
600 Free Software Foundation; either version 2 of the License, or (at your
601 option) any later version.
602 Picocom is distributed in the hope that it will be useful, but WITHOUT
604 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
605 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
606 for more details.
607 You should have received a copy of the GNU General Public License along
609 with this program; if not, write to the Free Software Foundation, Inc.,
610 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
611Picocom 3.1 2018-02-01 PICOCOM(1)