The Qodem Homepage

Qodem is a public domain re-implementation of the DOS-era Qmodem serial communications package, updated for modern systems. Qodem goes beyond similar DOS-era emulators in many ways:

• In addition to serial/modem connections, Qodem can also connect to remote systems over telnet, rlogin, ssh, raw sockets, or through an arbitrary command line.
• Qodem is curses-based, and as such can be run in command-line environments such as the raw Linux console, through an ssh session, or inside a graphical X11-based terminal emulator. Qodem can even be run inside itself.
• Qodem understands its supported emulations much better than many other programs. It has a "vttest score" of 104; under a true xterm it even displays double-width/double-height characters correctly. It can play ANSI Music, supports ANSI fallback for Avatar, translates both PC VGA and DEC multinational characters to Unicode, and can handle the UTF-8 flavors of Linux and xterm emulations.

Users wishing to test out Qodem on live bulletin boards should check out the Telnet BBS Guide list of telnet-able BBS systems. For convenience, this list has been converted into a Qodem phonebook file. Copy it into ~/.qodem (or if on Windows, into My Documents\qodem\prefs) and load it by pressing L in the Qodem phonebook screen.

As of Tuesday, May 26, 2015, Qodem has been dedicated to the public domain. To the extent possible under law, Autumn Lamonte has dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty. For jurisdictions that do not recognize the public domain, Qodem is also available under the terms of the CC0 license.

Qodem is hosted on SourceForge.net. Its development code repository is on GitLab.com.

Qodem's main features are:

• Unicode display: translation of CP437 (PC VGA), CP850, CP858, ISO-8859-1, VT100 DEC Special Graphics characters, VT220 National Replacement Character sets, ATASCII and many more, to Unicode
• Terminal interface: scrollback buffer, capture file, screen dump
• Convenience: dialing directory, keyboard macros, external script support, host mode
• Connection methods: serial port, modem dialer, local shell, command line, telnet, ssh, rlogin, raw socket
• Emulations: ANSI.SYS, Avatar, VT52, VT100, VT102, VT220, Linux, xterm, PETSCII (Commodore), and ATASCII (Atari)
• Transfer protocols: Xmodem, Ymodem, Zmodem, and Kermit

These features are detailed in more depth in the Qodem man page and online help system. The remainder of this section provides a very quick overview of the main interface.

Qodem is driven entirely by the keyboard. Qodem has two main modes of operation: the phonebook and the TERMINAL screen. The phonebook (screenshot) contains the list of sites to access, with each site being customizable for username, password, emulation, toggles, etc.. In TERMINAL mode (screenshot) most keystrokes are passed directly to the "other side" (or the local shell). Nearly all of the time pressing the ESCAPE key or the backtick (a.k.a. "reverse or open apostrophe `") will work to get out of dialogs and the phonebook screen.

Qodem is exited by pressing Alt-X while in TERMINAL mode. (If there is no active connection, Ctrl-C will also bring up the exit dialog.) Pressing 'y' or Enter at the exit prompt will exit Qodem.

Phonebook Mode

In phonebook mode, the following keystrokes will bring up the most important features:

• ESCAPE or ` - Switch to TERMINAL mode.
• PgUp, PgDn, Up Arrow, Down Arrow, Home, End - navigate up and down the phonebook list.
• I or INSERT - Insert a new entry. The entry dialog will appear. Screenshot. Most options are self-explanatory, however the connection methods may not be immediately obvious:
  • MODEM - dials into a remote system using the modem defined in the TERMINAL mode Alt-O modem screen.
  • LOCAL - spawns a local shell. The default is /bin/bash --login .
  • RLOGIN - connects to a remote system using the installed rlogin. If the username is supplied, it is passed to rlogin via the '-l' option.
  • SSH - connects to a remote system using the installed ssh. If the username is supplied, it is passed to ssh via the '-l' option. The port can also be specified.
  • TELNET - connects to a remote system using the installed telnet. The port can also be specified.
  • SOCKET - connects to a remote system over raw TCP. The port must be specified.
  • CMDLINE - spawns the command line via /bin/sh -c . This is the Swiss Army knife connection method. For example, one can use CMDLINE to punch through an IISPROXY firewall by having an ssh server listening on port 443 somewhere out there, installing cntlm and setting it up with a SOCKS5 listening port, and using a Qodem phonebook entry with CMDLINE method and address 'tsocks ssh -e none -p 443 my.remote.host' .
  For the items where you pick from a list of values (Method, Emulation, etc.), press F2 or Space to bring up the pick dialog and then use arrow keys to select the option. Screenshot.
• Enter - Connect to the selected entry if nothing is tagged. If some entries are tagged, begin connecting to the next tagged entry, cycling through the list if it is busy.
• O - Change the visible columns in the widescreen view.
• SPACE - Tag or untag an entry. Screenshot. Tagged entries can be dialed/connected in sequence with Enter, deleted as a group with Ctrl-D, or revised in sequence as a group with Ctrl-R.
• D or DELETE - Delete selected entry. A dialog will come up asking to delete either the attached note or the entire entry.
• N - Edit attached note in an editor. Every phonebook entry has an optional freeform text file associated with it.
• Ctrl-U - Revert the phonebook to the saved copy. This can undo very recent edits to the phonebook. Exiting to TERMINAL mode saves an automatic backup.

These are just the most common commands, many others are available including find and sort functions, loading other phonebook files, manually dialing the modem, and others.

TERMINAL Mode

In TERMINAL mode, the following keystrokes will bring up some of the important features:

• Alt-Z - Bring up the menu of commands. Screenshot. Selecting a command with Alt-keystroke will bring up that command immediately.
• Alt-X - Exit Qodem.
• Alt-D - Bring up the phonebook. ESC or ` to return to TERMINAL mode.
• Alt-/ - Enter scrollback mode. PgUp, PgDn, up arrow, down arrow, Home, and End all work to navigate the scrollback. 'S' will save the scrollback to a file, 'C' will clear the scrollback.
• Alt-H - Hangup or disconnect from the remote side.
• Alt-C - Clear screen.
• Alt-T - Save the current screen contents to file.
• PgUp - Initiate file upload. Qodem support raw ASCII transfers, several varieties of Xmodem and Ymodem, and Zmodem and Kermit. All of them should work OK on TCP/IP and error-correcting serial links. However, Kermit will fail on unreliable links like bare 3-wire RS232 or modems without error correction. Kermit will be fixed for unreliable links for the 0.4.0 release. Combinations of Alt- and Ctrl- for both PgUp and PgDn might also work depending on the host terminfo.
• PgDn - Initiate file download. Both Zmodem and Kermit also have autostart download support.
• Alt-P - Enable/disable capture file. Capture can be saved in three different formats depending on the capture_type value in qodemrc: 'raw' saves every byte including emulation escape sequences, 'normal' saves printable characters only after emulation processing (like a black-and-white capture), and 'html' saves both characters and colors in HTML format.
• Alt-N - Bring up the configuration file qodemrc in an editor.
• Alt-J - Bring up the function key editor (keyboard macros). Screenshot. A keyboard macro is a substitution string that is sent to the remote side when a particular function key is pressed. Like Qmodem, Qodem organizes macros by the emulation, so for example you can have F10 send one thing under ANSI emulation and a different thing under VT220 emulation. However, unlike Qmodem, Qodem also has a "default" macro set, editable by pressing 'L' and then selecting default.key. The basic rules of pressing a function key are:
  1. The current emulation's macro set is checked to see if a keyboard macro is defined. If so, it is sent to the remote side after performing these substitutions:
     • $PASSWORD is replaced by the password for the current connection if it is defined in the phonebook.
     • $USERNAME is replaced by the username for the current connection if it is defined in the phonebook.
     • ^M is replaced by carriage return.
     • After all substitutions, if the macro contains only whitespace it is ignored and the next step is taken to find the right string to send to the remote side.
  2. If the current emulation has no macro defined, the "default" macro set is checked. If the macro is defined there, it is processed like the step above.
  3. If neither the current emulation or the default macro set define the key, the terminfo database is used to find an escape sequence for this key.
  4. If no escape sequence was found through terminfo, a reasonable hardcoded default escape sequence is sent to the remote side.
• Alt-9 - Open or close the serial port. Must not already be connected to another system. For modem connections, this may cause an immediate hangup. Use the Alt-O modem settings menu to select the serial port device.
• Alt-Y - Change current serial port settings. New setting will apply immediately, the port does not have to be closed and re-opened.
• Alt-O - Change modem settings (init string, hangup string, etc).
• Alt-\ - Send a specific 8-bit byte or UTF-8 encoded Unicode character to the remote side.
• Alt-R - Shell to the OS.
• Alt-G - Change the current terminal emulation. Most are self-explanatory. The L_UTF8 and X_UTF8 emulations are LINUX and XTERM with UTF-8 encoding, respectively. The DEBUG emulation makes all received characters look like a programmer's hex dump (screenshot).
• Alt-; - Change the current codepage. This only has effect on TTY, ANSI, Avatar, LINUX, and XTERM emulations; the other emulations define their glyphs in their specification. Currently supported codepages are CP437 (VGA), ISO-8859-1, CP720 (Arabic), CP737 (Greek), CP775 (Baltic Rim), CP850 (Western European), CP852 (Central European), CP857 (Turkish), CP858 (Western European with euro), CP860 (Portuguese), CP862 (Hebrew), CP863 (Quebec French), CP866 (Cyrillic), CP1250 (Central/Eastern European), CP1251 (Cyrillic), CP1252 (Western European), KOI8_R (Russian), and KOI8_U (Ukrainian).
• Alt-F - Start a script. Qodem does not have its own scripting language. Instead, any program that reads stdin and writes to stdout can be run as a script that communicates directly with the remote side. Qodem strips out emulation and passes only the printable characters to the script. The program's stderr is displayed in the bottom few lines as messages to the user. Screenshot.

These are just the most common commands, many others are available including byte translation, split screen, doorway mode, special character handling for CR/NUL/DEL, and various toggles.

Status Line

Throughout Qodem, the bottom line of the screen is used to report status and provide hints about what keystrokes are available. In TERMINAL mode the status line can be turned off with Alt-- (Alt-minus), or toggled between two different forms with Alt-7.

Qodem has benefited from the work of several other people. We wish to thank a few people specifically:

• John Friel III for writing Qmodem which was the inspiration for this project.
• Paul Williams, for his excellent work documenting the DEC VT terminals at http://www.vt100.net/emu/dec_ansi_parser.
• Thomas E. Dickey, for his work on the xterm emulator and the ncurses library. xterm's reputation as one of the best terminal emulators available anywhere is well-deserved.
• Bjorn Larsson, William McBrine, and the many developers involved in PDCurses who dedicated their work to the public domain.
• Miquel van Smoorenburg and the developers involved in minicom who licensed their work under the GNU Public License.
• Thomas BERNARD and the developers involved in miniupnpc who licensed their work under a BSD-like license.
• Jeff Gustafson for creating the Fedora RPM build script.
• Martin Godisch for help in packaging for deb.
• Jason Scott for creating BBS: The Documentary.
• Peter Gutmann for developing cryptlib and licensing it under an open source compatible license.
• Nathanael Culver for obtaining Qmodem 2.3, 4.2f, and QmodemPro 1.50.
• Tim Hentenaar for the original version of the ATASCII code.

Notes Regarding Qmodem

For reference, the last shareware version of Qmodem (Qmodem 4.6 Test Drive) is available here. The Qmodem user's guide may provide a good starting point for understanding Qodem. It is available here in several formats:

• HTML - one long page
• Unicode text (to view in Firefox, select View → Character Encoding → Unicode (UTF-8))
• The original CP437-encoded text

Please note that Qodem is NOT Qmodem™. Qmodem™ is a trademarked commercial program, originally written by John Friel III, last released by Mustang Software, Inc., a quality program that can handle all kinds of serial communications needs. Newer versions of QmodemPro™ for Windows (above 2.0) can connect to hosts via telnet. Qodem has many behavior deviations from Qmodem.

More information about both Qodem and Qmodem is available on the About page.

Qodem Project

SourceForge Qodem Project Page
GitLab Qodem Project Page
Submit A New Bug Report
Latest README
Qodem man page
Work Log

Terminal Emulation Resources

vt100.net
Terminal Information Archive
xterm

BBS Resources

Telnet BBS Guide
The BBS Documentary
textfiles.com

HS/Link

The Qodem Project is planning to port the public release code of the HS/Link bi-directional file transfer protocol to POSIX environments. No timetable is set, but the files themselves are available here. We are working under the assumption that the original author did in fact release the code as "public domain" with his statement here (originally here).

Qodem users, other terminal emulator developers, and bulletin board system (BBS) users/developers may find these projects useful:
xterm
Kermit
ncurses
PDCurses
PDCurses win32a fork
cryptlib
miniupnpc
SyncTERM
Synchronet
Mystic BBS
Jexer Text User Interface library. A Java-based text windowing system that loosely resembles Turbo Vision.
Jermit - Java Serial File Transfer Protocols. A Java-based re-implementation of Xmodem, Ymodem, Zmodem, and Kermit.