PICOCOM(1)

📦
version 2024.07 · 7 versions
, in alpine 3.24, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 PICOCOM(1) 💖

General Commands Manual — picocom

okay bestie sit DOWN because we're about to talk about the most iconic little terminal program in the game: picocom(1). yes it's part of the General Commands Manual, yes it's manual page number 1, and yes it's about to be your new obsession 🫶

✨ NAME ✨

picocom — minimal dumb-terminal emulation program

🌸 SYNOPSIS 🌸

picocom [ options ] device

🦋 DESCRIPTION 🦋

As its name suggests, picocom(1) is a minimal dumb-terminal emulation program. It is, in principle, very much like minicom(1), only it is "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, ngl) 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. no cap.

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). so it's giving "middleware but make it iconic" 😌

When picocom starts it opens the tty (serial port) given as its non-option argument (or the last non-option argument, if multiple are given). Unless the --noinit 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 --noinit 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 escape character. 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 [COMMANDS] section below. 🎀

🎀 COMMANDS 🎀

Commands are given to picocom by first keying the escape character — which by default is Control-a (see [OPTIONS] below for how to change it) — and then keying one of the function (command) characters shown here. From now on, we will use C-<key> as a short version of Control-<key>, so the default escape character is then C-a. 💅

All function characters have the form C-<key>. If the command-line option --minimal-cmds is given, <key> only is used.

  • escape character — 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.
  • C-x — Exit the program. If the --noreset option is not 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 --noreset is given (and --hangup is not), then the serial port settings are not reset, and the modem control lines remain unaffected. If both --noreset and --hangup are given, then the serial port settings are not reset, but the modem-control lines are cleared.
  • C-q — Quit the program without resetting the serial port to its original settings. Terminating with the Quit command, picocom behaves exactly as if the --noreset option was given. The serial port is not reset to its original settings, and the modem control lines remain unaffected or are cleared, subject to the --hangup option.
  • C-p — Pulse the DTR line. Lower it for 1 sec, and then raise it again. ⏱️
  • C-t — 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.
  • C-g — 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.
  • C-backslash — 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.
  • C-b — Set baudrate. Prompts you to enter a baudrate numerically (in bps) and configures the serial port accordingly.
  • C-u — 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 HIGH_BAUD 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 your system, any of the higher baud rates may be missing.
  • C-d — 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.
  • C-f — Cycle through flow-control settings (RTS/CTS, XON/XOFF, none).
  • C-y — Cycle through parity settings (even, odd, none).
  • C-i — Cycle through databits-number settings (5, 6, 7, 8).
  • C-j — Cycle through stopbits-number settings (1, 2).
  • C-c — Toggle local-echo mode.
  • C-w — 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 --omap, --echo and --emap options are observed). Example: The following sends the characters "ABCD" to the port.
C-a C-w
*** hex: 41 4243:44
*** wrote 4 bytes ***
  • C-s — Send (upload) a file. See [SENDING AND RECEIVING FILES] below.
  • C-r — Receive (download) a file. See [SENDING AND RECEIVING FILES] below.
  • C-v — 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 [DISPLAY OF OPTIONS AND PORT SETTINGS] for details.
  • C-h or C-k — Show help, or show keys. Prints a short description of all available function (command) keys.

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:

C-a, C-u, C-a, C-u

assuming of-course that C-a is the escape character. 💖

✨ OPTIONS ✨

picocom accepts the following command-line options.

  • --baud | -b — Defines the baud-rate to set the serial-port (terminal) to.
  • --flow | -f — Defines the flow-control mode to set the serial-port to. Must be one of: x for xon/xoff (software) mode, h for hardware flow control (RTS/CTS), n for no flow control. (Default: n)
  • --parity | -y — Defines the parity mode to set the serial-port to. Must be one of: o for odd parity mode, e for even parity mode, n for no parity mode. (Default: n)
  • --databits | -d — Defines the number of data bits in every character. Must be one of: 5, 6, 7, 8. (Default: 8)
  • --stopbits | -p — Defines the number of stop bits in every character. Must be one of: 1, or 2. (Default: 1)
  • --tx-delay | -T — Delays for the specified amount of time (in nanoseconds) after each character sent. If you do not use any flow-control, this can help to prevent lost characters due to buffer overruns when sending larger blocks of data, e.g. when pasting text. Allowed range is from 0 (disabling the feature) to 999999999 (nearly 1 second). (Default: 0)
  • --escape | -e — 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. See also the --no-escape option. (Default: a)
  • --no-escape | -n — 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).
  • --echo | -c — 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 --emap option). (Default: Disabled)
  • --noinit | -i — 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 --noreset and --hangup options. (Default: Disabled)
  • --noreset | -r — 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 not be restored to their original values and, unless the --hangup option is also given, the modem-control lines will not be affected. This is useful, for example, for leaving modems connected when exiting picocom. Regardless whether the --noreset option is given, the user can exit picocom using the "Quit" command (instead of "Exit"), which makes picocom behave exactly as if --noreset was given. See also the --hangup option. (Default: Disabled)
🚨 NOTICE, bestie, read this one twice: picocom clears the modem control lines on exit by setting the HUPCL control bit of the respective port. picocom always sets HUPCL according to the --noreset and --hangup options. If --noreset is given and --hangup is not, then HUPCL for the port is cleared and will remain so after exiting picocom. If --noreset is not given, or if both --noreset and --hangup 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 --noinit option. 💀
  • --hangup, -u — okay so this one only does anything if you also pass --noreset. Together they mean picocom won't reset the serial port back to its original settings when it exits, but it will clear the modem control lines (usually DTR and RTS) so your modem knows you hung up. Without --noreset (whether you typed it yourself or it got implied by exiting with the "Quit" command) --hangup literally does nothing, because without --noreset picocom always clears the modem control lines on exit anyway. 💅
  • --nolock, -l — pass this and picocom won't even try to lock the serial port before opening it. Normally, depending on how it was compiled, picocom either grabs a UUCP-style lock-file (like '/var/lock/LCK..ttyS0') before opening the port, or locks the port device-node with flock(2). If it can't do that, it just exits after throwing an error-message at you. Heads up bestie: it's possible your picocom binary was compiled without locking support at all — in that case --nolock is still accepted, it just has no effect. (Default: Disabled) 🫶
  • --send-cmd, -s — tells picocom which external program (plus any arguments to it) to use for transmitting files. If you pass the empty string ('') as the argument, the send-file command is straight up disabled. See [SENDING AND RECEIVING FILES]. (Default: sz -vv) ✨
  • --receive-cmd, -v — same energy, but for receiving files: the external program (plus any arguments) used to receive them. Empty string ('') argument = receive-file command disabled. See [SENDING AND RECEIVING FILES]. (Default: rz -vv) ✨
  • --imap — sets the input character map, aka the special characters that get replaced when they're read from the serial port. See [INPUT, OUTPUT, AND ECHO MAPPING]. (Default: Empty)
  • --omap — sets the output character map, aka the special characters that get replaced before being written to the serial port. See [INPUT, OUTPUT, AND ECHO MAPPING]. (Default: Empty)
  • --emap — sets the local-echo character map, aka the special characters replaced before being echoed-back to your terminal, if local-echo is enabled. See [INPUT, OUTPUT, AND ECHO MAPPING]. (Default: delbs,crcrlf)
  • --logfile, -g — use this file for logging (recording) serial input, and possibly serial output too. If the file already exists, picocom appends to it. Every character read from the serial port gets written to that file (before input mapping happens, btw). And if local-echo mode is enabled (see the --echo option and the C-c command), then every character written to the serial port (after output mapping) gets logged to the same file as well. (Default: no logging) 🎀
  • --initstring, -t — sends the string you give it after the serial port is opened and configured. It goes out exactly as if you'd typed it at the terminal, so picocom respects the --omap output mapping, the --echo local-echo setting, and the --emap local-echo mapping when sending it. Super useful if your serial device needs some special magic strings before it'll start responding. Use echo(1) or xxd(1) to generate special characters like a CR or binary data. Example:
picocom -t "$(echo -ne 'AAATZ\r\n')" /dev/ttyS0

Note that the init string is not sent if --noinit is given. (Default: empty).

  • --lower-rts — lowers the RTS modem control signal after opening the serial port. Only supported when flow-control mode isn't set to RTS/CTS — ignored otherwise. And only supported on some systems, no cap.

If you give neither --lower-rts nor --raise-rts, the state of the RTS signal after opening and configuring the port is system dependent. On most systems, the signal is raised. 🌸

  • --raise-rts — raises the RTS modem control signal after opening the serial port. Only supported when flow-control mode isn't set to RTS/CTS — ignored otherwise. Only supported on some systems.

Same deal as above: if you give neither --raise-rts nor --lower-rts, the RTS signal state after opening and configuring the port depends on your system. On most systems, the signal is raised. 🌸

  • --lower-dtr — lowers the DTR control signal after opening the serial port. Only supported on some systems.

And again: if you give neither --lower-dtr nor --raise-dtr, the state of the DTR signal after opening and configuring the port is system dependent. On most systems, the signal is raised. 🌸

  • --raise-dtr — raises the DTR control signal after opening the serial port. Only supported on some systems.

If you give neither --raise-dtr nor --lower-dtr, the DTR signal state after opening and configuring the port is system dependent. On most systems, the signal is raised. 🌸

  • --exit-after, -x — picocom bounces out if it stays idle for however long you specify (in milliseconds). And "idle" here means: nothing read (received) from the serial port, AND nothing to write (send) to the serial port, AND nothing read from standard input. All three, at once. If you set --exit-after to zero, picocom exits right after opening and configuring the serial port, after sending the init string (if there is one — see --initstring), and immediately when it becomes idle. When it exits because it went idle, picocom drains the O/S serial port output buffer (i.e. it waits for data already written to the port to actually be transmitted) and observes the --noreset and --hangup options as usual. (Default: not set)
⚠️ NOTICE: If --exit-after is set, reading zero bytes from standard input (which usually means whatever was connected there got closed) will not make picocom exit. Instead it just keeps running, not reading from stdin, and only exits when it's been idle for the specified time — or when something kills it with a signal. If --exit-after is not set, then reading zero bytes from stdin does cause picocom to exit, after the contents of its output queue have been transmitted.
  • --exit, -X — picocom exits immediately after opening and configuring the serial port. It reads nothing from standard input and nothing from the serial port. On exit, --noreset and --hangup are observed as usual. With --exit and --noreset (and maybe --hangup) picocom becomes a very crude replacement for stty(1), fr fr. If you also give an init string (see --initstring), picocom exits immediately after sending (writing) that 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). And again — nothing is read from standard input, or from the serial port. Also, --exit overrides the --exit-after option. (Default: Disabled) 🔥
  • --minimal-cmds, -M — uses <key> instead of C-<key> as the function character, so like, C-a and h both print the help text. Minicom users may feel right at home this way, but it also makes it way easier to accidently change a setting. (Default: Disabled) 🙈
  • --quiet, -q — forces picocom to be quiet. Suppresses the output of the initial status and options information, plus any other info or messages you didn't explicitly ask for. Responses to user commands, and any error or warning messages, still get printed. 💜
  • --help, -h — prints a short help message describing the command-line options. Version, compile-time options, and enabled features of picocom are shown too. 👑

🌈 CHANGING DEFAULT OPTIONS 🌈

So picocom does not support config files, bestie. Not a thing. If you wanna change default options, use a custom script or aliases, like:

alias picocom='picocom -b 115200 /dev/ttyS0'

Another option is command substitution, if your shell supports it. Here's an example for bash:

picocom $(<my_config_file)

Where 'my_config_file' contains one command-line option per line. 🎀

💅 DISPLAY OF OPTIONS AND PORT SETTINGS 💅

The "show program options" command (C-v), plus all the commands that change program options (C-b, C-u, C-d, C-f, etc) print messages showing the current values (or the new values, if they got changed) for the respective options. And if picocom figures out that an actual serial-port setting differs from the current value of the respective option (for literally any reason), then it shows the value of the option followed by the value of the actual serial-port setting in parenthesis. Example:

*** baud: 115200 (9600)

This means a baud rate of 115200bps has been selected (from the command line, or via commands that change the baudrate) but the serial-port is actually running at 9600bps — maybe the driver doesn't support the higher setting and silently swapped it for a safe default, or maybe the setting got changed from outside picocom. If the option and the corresponding serial-port setting match, only a single value is shown. Example:

*** baud: 9600

This behavior was introduced in picocom 2.0. Older releases displayed only the option values, not the actual serial-port settings corresponding to them. ⭐

On startup, after the serial port is opened and configured (and assuming neither the --noinit nor the --quiet command line options were given), the port settings get silently checked. If any mismatch shows up between the requested and the actual port settings, a warning message is displayed. You can then use the C-v command to figure out the exact mismatch or mismatches. 🦋

📦 SENDING AND RECEIVING FILES 📦

Okay bestie so picocom can absolutely send and receive files over the serial port, and it does this by handing the job off to external programs that actually implement the protocols. It's giving delegation, it's giving teamwork. On Linux the typical programs for this whole situation are:

  • rx(1) — receive using the X-MODEM protocol
  • rb(1) — receive using the Y-MODEM protocol
  • rz(1) — receive using the Z-MODEM protocol
  • sx(1) — send using the X-MODEM protocol
  • sb(1) — send using the Y-MODEM protocol
  • sz(1) — send using the Z-MODEM protocol
  • ascii-xfr(1) — receive or transmit ASCII files

The name of the program you wanna use for transmitting files — plus the command-line options you wanna pass it — all goes in the --send-cmd option. And the receive side of things? That program and its arguments go in the --receive-cmd option. Like, they're twins. 💖

So if you wanna start a picocom session that uses sz(1) to transmit files and rz(1) to receive files, you'd say something like this:

picocom --send-cmd "sz -vv" --receive-cmd "rz -vv" ...

Now here's the little plot twist: if the argument to the -send-cmd option, or the argument to the --receive-cmd option, is the empty string, then that respective command is disabled. Want both the "send" and the "receive" commands off? Invoke picocom like this:

picocom --send-cmd '' --receive-cmd '' ...

And fun fact — a picocom session with both the send- and the receive-file commands disabled does not fork(2) and does not run any external programs. Minimalist queen behavior. 👑

During the picocom session, if you key the "send" or "receive" commands (so, like, pressing C-a, C-s, or C-a, C-r), you'll get 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 — but only if you compiled picocom with support for the linenoise library. iykyk. ✨

Pressing C-c at this prompt cancels the file transfer command and returns you to normal picocom operation. After you enter a filename (and / or additional transmission or reception program arguments), and assuming you did not cancel by pressing C-c, picocom will start the external program as specified by the --send-cmd, or --receive-cmd option, and with any filenames and additional arguments you may have supplied.

Then: the standard input and output of the external program get connected to the serial port. The standard error of the external program gets 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 (assuming that the program itself does not ignore SIGINT), and return control to picocom.

Pressing C-c at any other time has no special effect; the character is normally passed to the serial port. Not every C-c is a dramatic moment, bestie. 💀

🎀 INPUT, OUTPUT, AND ECHO MAPPING 🎀

Using the --imap, --omap, and --emap options you can make picocom map (translate, replace) certain special characters:

  • after being read from the serial port — that's --imap 💜
  • before being written to the serial port — that's --omap 💜
  • before being locally echoed to the terminal (standard output), if local echo is enabled — that's --emap 💜

Each of these mapping options takes a single argument, which is a comma-separated list of one or more of these identifiers:

  • crlf (map CR to LF)
  • crcrlf (map CR to CR + LF)
  • igncr (ignore CR)
  • lfcr (map LF to CR)
  • lfcrlf (map LF to CR + LF)
  • ignlf (ignore LF)
  • bsdel (map BS to DEL)
  • delbs (map DEL to BS)
  • spchex (map special chars (< 0x20 || 0x7f), excl. CR, LF, and TAB to hex)
  • tabhex (map TAB to hex)
  • crhex (map CR to hex)
  • lfhex (map LF to hex)
  • 8bithex (map chars with 8th-bit set to hex)
  • nrmhex (map normal ascii chars (0x20 <= c < 0x7f) to hex)
  • upper (map to uppercase, 'a-z' to 'A-Z')
  • lower (map to lowercase, 'A-Z' to 'a-z')

The "to hex" mappings (???hex) replace the respective characters with their hexadecimal representation (in square brackets), like this:

CR --> [0d]

Important: 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. First come, first served, no line-jumping. 🙈

For example, the command:

picocom --omap crlf,delbs --imap ignlf,bsdel --emap crcrlf ...

will:

  • 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.
  • 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.
  • Replace every CR character with CR and LF when echoing to the terminal (if local-echo is enabled).

🚪 EXITING PICOCOM 🚪

This section summarizes the conditions in which picocom terminates its operation, and what happens in each such condition. Grab a snack, it's a list. 🍓

  • The exit command is seen in the standard input. That is, the escape character is seen (default C-a), followed by the exit command character (default C-x). 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 its original settings, and the modem-control lines are cleared signaling a modem reset, subject to the --noreset and the --hangup options. After that picocom exits with a success status.
  • The quit command is seen in the standard input. That is, the escape character is seen (default C-a), followed by the quit command character (default C-q). The behavior in this case is similar to that of the exit command, with one difference: picocom behaves as if the --noreset option is given (regardless of if it actually is, or not). 👀
  • The --exit 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.
  • The --exit-after 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.
  • Zero bytes are read from the standard input. This usually means that whatever was connected to the standard input of picocom 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 --exit-after option is not 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 --noreset and --hangup options) resets the serial port to its initial settings, clears the modem-control lines, and exits. If the --exit-after 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.
  • 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 --noreset and --hangup options, the serial port is reset to its original settings, the modem control lines are cleared, and picocom exits with a failure status. 😭

🌈 AUTHOR 🌈

Written by Nick Patavalis <npat@efault.net>, currently maintained by Wolfram Sang <wsa@kernel.org>

🦋 AVAILABILITY 🦋

Download the latest release from: <https://gitlab.com/wsakernel/picocom/-/releases>

Copyright (c) 2003-2018 Nick Patavalis and 2022- Wolfram Sang

This file is part of Picocom.

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.

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.

and that's the whole page, bestie ✨ you just read PICOCOM(1), version v2024-07 — go forth, slay those serial ports, and remember: no cap, only C-a. 🫶💅🎀

📦 where this page comes from