home *** CD-ROM | disk | FTP | other *** search
/ PCNET 2006 September - Disc 1 / PCNET_CD_2006_09.iso / linux / puppy-barebones-2.01r2.iso / pup_201.sfs / usr / share / doc / picocom.txt < prev    next >
Encoding:
Text File  |  2003-10-24  |  8.4 KB  |  225 lines
  1.  
  2. picocom
  3.  
  4. by Nick Patavalis (npat@efault.net)
  5.  
  6. As its name suggests, [picocom] is a minimal dumb-terminal emulation
  7. program. It is, in principle, very much like minicom, only it's "pico"
  8. instead of "mini"! It was designed to serve as a simple, manual, modem
  9. configuration, testing, and debugging tool. It has also served (quite
  10. well) as a low-tech "terminal-window" to allow operator intervention
  11. in PPP connection scripts (something like the ms-windows "open
  12. terminal window before / after dialing" feature). It could also prove
  13. useful in many other similar tasks. It is ideal for embedded systems
  14. since its memory footprint is minimal (less than 20K, when
  15. stripped). Apart from being a handy little tool, [picocom] source
  16. distribution includes a simple, easy to use, and thoroughly documented
  17. terminal-management library, which could serve other projects as
  18. well. This library hides the termios(3) calls, and provides a less
  19. complex and safer (though certainly less feature-rich)
  20. interface. [picocom] runs on Linux, and with minor modifications it
  21. could run on any Unix system with the termios(3) library.
  22.  
  23. ** Description of operation
  24.  
  25. When [picocom] starts it opens the terminal (serial device) given as
  26. its non-option argument. Unless the "--noinit" option is given, it
  27. configures the device to the settings specified by the
  28. option-arguments (or to some default settings), and sets it to "raw"
  29. mode. If "--noinit" is given, the initialization and configuration is
  30. skipped; the device is just opened. Following this, [picocom] sets the
  31. standard-input and standard-output to raw mode. Having done so, it
  32. goes in a loop where it listens for input from stdin, or from the
  33. serial port. Input from the serial port is copied to the standard
  34. output while input from the standard input is copied to the serial
  35. port. [picocom] also scans its input stream for a user-specified
  36. control character, called the "escape character" (being by default
  37. "C-a"). If the escape character is seen, then instead of sending it to
  38. the serial-device, the program enters "command mode" and waits for the
  39. next character (which is called the "function character"). Depending
  40. on the value of the function character, [picocom] performs one of the
  41. following operations:
  42.  
  43.   [esc] : Do nothing, remain in command mode
  44.  
  45.     C-x : Exit the program: if the "--noreset" option was not
  46.           given then the serial port is reset to its original settings
  47.           before exiting; if it was given the serial port is not
  48.           reset.
  49.  
  50.     C-q : Quit the program *without* reseting the serial port,
  51.           regardless of the "--noreset" option.
  52.  
  53.     C-p : Pulse the DTR line. Lower it for 1 sec, and then raise it
  54.           again.
  55.  
  56.     C-t : Toggle the DTR line. If DTR is up, then lower it. If it is
  57.           down, then raise it.
  58.  
  59.     B-u : Baud up. Increase the baud-rate.
  60.  
  61.     B-d : Baud down. Decrease the baud-rate.
  62.  
  63.     C-f : Cycle through flow-control settings.
  64.  
  65.     C-y : Cycle through parity settings.
  66.  
  67.     C-b : Cycle through databits-number settings.
  68.  
  69.     C-v : Show program options (like baud rate, data bits, etc). Only
  70.           the options that can be modified online (through commands)
  71.           are shown, not those that can only be set at the
  72.           command-line.
  73.  
  74.     C-s : Send (upload) a file (see "Sending and Receiving Files"
  75.           below)
  76.  
  77.     C-r : Receive (download) a file (see "Sending and Receiving Files"
  78.           below)
  79.  
  80. After performing one of the above operations (except for the one
  81. binded to the [esc] function character) the program leaves the command
  82. mode. Example: To increase the baud-rate by two steps, you have to
  83. type:
  84.  
  85.   C-a, C-u, C-a, C-u 
  86.  
  87. assuming of-course that "C-a" is the escape character.
  88.  
  89. ** Sending and receiving files
  90.  
  91. [picocom] can send and receive files over the serial port using
  92. external programs that implement the respective protocols. In Linux
  93. typical programs for this purpose are:
  94.  
  95.   rx(1) -- receive using the X-MODEM protocol
  96.   rb(1) -- receive using the Y-MODEM protocol
  97.   rz(1) -- receive using the Z-MODEM protocol
  98.  
  99.   sx(1) -- send using the X-MODEM protocol
  100.   sb(1) -- send using the Y-MODEM protocol
  101.   sz(1) -- send using the Z-MODEM protocol
  102.  
  103.   ascii-xfr(1) -- receive or transmit ASCII files
  104.  
  105. The name of, and the command-line options to, the program to be used
  106. for transmitting files is given by the "--send-cmd" option. Similarly
  107. the program to receive files, and its argumets, are given by the
  108. "--receive-cmd" option. For example, in order to start a [picocom]
  109. session that uses "sz" to transmit files, and "rz" to receive, you
  110. have to say something like this:
  111.  
  112.   picocom --send-cmd "sz -vv" --receive-cmd "rz -vv"
  113.  
  114. Durring the [picocom] session, if you key the "send" or "receive"
  115. commands (e.g. by pressing C-a, C-s, or C-a, C-r) you will be prompted
  116. for a filename. At this prompt you can enter one or more file-names,
  117. and any additional arguments to the transmission or reception
  118. program. After that, picocom will start the the external program as
  119. specified by the "--send-cmd", or "--receive-cmd" option, and with any
  120. filenames and additional arguments you may have supplied. The standard
  121. input and output of the external program will be connected to the
  122. serial port. The standard error of the external program will be
  123. connected to the terminal which---while the program is running---will
  124. revert to canonical mode. Pressing 'C-c' while the external program is
  125. running will prematurely terminate it, and return control to
  126. [picocom]. Pressing 'C-c' at any other time, has no special effect;
  127. the character is normally passed to the serial port.
  128.  
  129. ** Invocation
  130.  
  131. The following invocation produces a short help message with picocom's
  132. command-line syntax:
  133.  
  134.   # picocom --help
  135.  
  136.   picocom vX.Y
  137.   Usage is: picocom [options] <tty device>
  138.   Options are:
  139.     --<b>aud <baudrate> 
  140.     --<f>low s (=soft) | h (=hard) | n (=none)
  141.     --<p>arity o (=odd) | e (=even) | n (=none)
  142.     --<d>atabits 5 | 6 | 7 | 8
  143.     --<e>scape <char>
  144.     --no<i>nit
  145.     --no<r>eset
  146.     --<s>end-cmd <command>
  147.     --recei<v>e-cmd <command
  148.     --<h>elp
  149.   <?> indicates equivalent short option. Short options 
  150.   are prefixed by "-" instead of "--".
  151.  
  152. Options are:
  153.  
  154. '--baud' or '-b'
  155.   Defines the baud-rate to set the serial-port (terminal) to.
  156.  
  157. '--flow' or '-f'
  158.   Defines the flow-control mode to set the serial-port to. Must be 
  159.   one of:
  160.     'x' for xon/xoff (software) mode
  161.     'h' for hardware flow control (RTS/CTS)
  162.     'n' for no flow control
  163.   (Default: 'n')
  164.  
  165. '--parity' or '-p'
  166.   Defines the parity mode to set the serial-port to. Must be one of:
  167.     'o' for odd parity mode.
  168.     'e' for even parity mode.
  169.     'n' for no parity, mode.
  170.   (Default: 'n')
  171.  
  172. '--databits' or '-d'
  173.   Defines the number of data bits in every character. Must be one of: 
  174.     5, 6, 7, 8
  175.   (Default: 8)
  176.  
  177. '--escape' or '-e'
  178.   Defines the character that will make picocom enter command-mode
  179.   (see description above). If 'x' is given, then C-x will
  180.   make picocom enter command mode.
  181.   (Default: 'a')
  182.  
  183. '--noinit' or '-i'
  184.   If given, [picocom] will not initialize, reset, or otherwise
  185.   meddle with the serial port at start-up. It will just open it. This
  186.   is useful, for example, for connecting [picocom] to
  187.   already-connected modems, or already configured ports without
  188.   terminating the connection, or altering the settings. If required
  189.   serial port parameters can then be adjusted at run-time by commands.
  190.  
  191. '--noreset' or '-r'
  192.   If given, [picocom] will not *reset* the serial port when
  193.   exiting. It will just close the filedes and do nothing more. This is
  194.   useful, for example, for leaving modems connected when exiting
  195.   [picocom]. Regardless whether the "--noreset" option is given the
  196.   user can exit [picocom] using the "Quit" command (instead of
  197.   "Exit"), which never resets the serial port. If "--noreset" is given
  198.   then "Quit" and "Exit" behave essentially the same.
  199.  
  200. '--send-cmd' or '-s'
  201.   Specifies the external program (and any arguments to it) that will
  202.   be used for transmitting files.
  203.   Default: "sz -vv"
  204.  
  205. '--receive-cmd' or '-v' 
  206.   Specifies the external program (and any arguments to it) that will
  207.   be used for receiving files.
  208.   Default: "rz -vv"
  209.  
  210. '--help' or '-h':
  211.   Print a short help message describing the command-line options.
  212.  
  213. ** Obtain [picocom]
  214.  
  215. "picocom" can be downloaded from:
  216.  
  217.   http://efault.net/npat/hacks/picocom/
  218.  
  219. ** Comments, request, and fixes:
  220.  
  221. Please feel free to send comments, requests for new features (no
  222. promisses, though!), bug-fixes and rants, to the author's email
  223. address show at the top of this file.
  224.  
  225.