Daniel Engeler <engeler at gmail.com>

elisp.texi, internals.texi, processes.texi: Add documentation about
serial port access.

4 files changed, 259 insertions, 43 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b9e5ebb0fc1..808a1fd82e0 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2008-06-13  Daniel Engeler  <engeler@gmail.com>
+
+        * elisp.texi, internals.texi, processes.texi: Add documentation
+        about serial port access.
+
 2008-06-05  Miles Bader  <miles@gnu.org>
 
         * display.texi (Displaying Faces): Update to reflect function
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index b73dc13b71a..248ba2476f7 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1195,6 +1195,7 @@ Processes
 * Low-Level Network::       Lower-level but more general function
                               to create connections and servers.
 * Misc Network::            Additional relevant functions for network connections.
+* Serial Ports::            Communicating with serial ports.
 * Byte Packing::            Using bindat to pack and unpack binary data.
 
 Receiving Output from Processes
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 79c961ba4b5..c977b2e549f 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1433,7 +1433,8 @@ A string, the name of the process.
 
 @item command
 A list containing the command arguments that were used to start this
-process.
+process.  For a network or serial process, it is @code{nil} if the
+process is running or @code{t} if the process is stopped.
 
 @item filter
 A function used to accept output from the process instead of a buffer,
@@ -1449,8 +1450,9 @@ The associated buffer of the process.
 An integer, the operating system's process @acronym{ID}.
 
 @item childp
+
 A flag, non-@code{nil} if this is really a child process.
-It is @code{nil} for a network connection.
+It is @code{nil} for a network or serial connection.
 
 @item mark
 A marker indicating the position of the end of the last output from this
@@ -1515,6 +1517,11 @@ Size of carryover in encoding.
 @item inherit_coding_system_flag
 Flag to set @code{coding-system} of the process buffer from the
 coding system used to decode process output.
+
+@item type
+Symbol indicating the type of process: @code{real}, @code{network},
+@code{serial}
+
 @end table
 
 @ignore
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index b26c69741b0..b3455dc9414 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -53,6 +53,7 @@ This function returns @code{t} if @var{object} is a process,
 * Low-Level Network::        Lower-level but more general function
                                to create connections and servers.
 * Misc Network::             Additional relevant functions for network connections.
+* Serial Ports::             Communicating with serial ports.
 * Byte Packing::             Using bindat to pack and unpack binary data.
 @end menu
 
@@ -676,6 +677,49 @@ were given to the program.
 @end smallexample
 @end defun
 
+@defun process-contact process &optional key
+
+This function returns information about how a network or serial
+process was set up.  For a network process, when @var{key} is
+@code{nil}, it returns @code{(@var{hostname} @var{service})} which
+specifies what you connected to.  For a serial process, when @var{key}
+is @code{nil}, it returns @code{(@var{port} @var{speed})}.  For an
+ordinary child process, this function always returns @code{t}.
+
+If @var{key} is @code{t}, the value is the complete status information
+for the connection, server, or serial port; that is, the list of
+keywords and values specified in @code{make-network-process} or
+@code{make-serial-process}, except that some of the values represent
+the current status instead of what you specified.
+
+For a network process:
+
+@table @code
+@item :buffer
+The associated value is the process buffer.
+@item :filter
+The associated value is the process filter function.
+@item :sentinel
+The associated value is the process sentinel function.
+@item :remote
+In a connection, the address in internal format of the remote peer.
+@item :local
+The local address, in internal format.
+@item :service
+In a server, if you specified @code{t} for @var{service},
+this value is the actual port number.
+@end table
+
+@code{:local} and @code{:remote} are included even if they were not
+specified explicitly in @code{make-network-process}.
+
+For a serial process, see @code{make-serial-process} and
+@code{serial-process-configure} for a list of keys.
+
+If @var{key} is a keyword, the function returns the value corresponding
+to that keyword.
+@end defun
+
 @defun process-id process
 This function returns the @acronym{PID} of @var{process}.  This is an
 integer that distinguishes the process @var{process} from all other
@@ -742,6 +786,12 @@ For a network connection, @code{process-status} returns one of the symbols
 closed the connection, or Emacs did @code{delete-process}.
 @end defun
 
+@defun process-type process
+This function returns the symbol @code{network} for a network
+connection or server, @code{serial} for a serial port connection, or
+@code{real} for a real subprocess.
+@end defun
+
 @defun process-exit-status process
 This function returns the exit status of @var{process} or the signal
 number that killed it.  (Use the result of @code{process-status} to
@@ -1593,11 +1643,14 @@ server process, or @code{:type 'datagram} to create a datagram
 connection.  @xref{Low-Level Network}, for details.  You can also use
 the @code{open-network-stream} function described below.
 
-  You can distinguish process objects representing network connections
-and servers from those representing subprocesses with the
-@code{process-status} function.  The possible status values for
-network connections are @code{open}, @code{closed}, @code{connect},
-and @code{failed}.  For a network server, the status is always
+  To distinguish the different types of processes, the
+@code{process-type} function returns the symbol @code{network} for a
+network connection or server, @code{serial} for a serial port
+connection, or @code{real} for a real subprocess.
+
+  The @code{process-status} function returns @code{open},
+@code{closed}, @code{connect}, and @code{failed} for network
+connections.  For a network server, the status is always
 @code{listen}.  None of those values is possible for a real
 subprocess.  @xref{Process Information}.
 
@@ -1631,42 +1684,6 @@ The arguments @var{host} and @var{service} specify where to connect to;
 a defined network service (a string) or a port number (an integer).
 @end defun
 
-@defun process-contact process &optional key
-This function returns information about how a network process was set
-up.  For a connection, when @var{key} is @code{nil}, it returns
-@code{(@var{hostname} @var{service})} which specifies what you
-connected to.
-
-If @var{key} is @code{t}, the value is the complete status information
-for the connection or server; that is, the list of keywords and values
-specified in @code{make-network-process}, except that some of the
-values represent the current status instead of what you specified:
-
-@table @code
-@item :buffer
-The associated value is the process buffer.
-@item :filter
-The associated value is the process filter function.
-@item :sentinel
-The associated value is the process sentinel function.
-@item :remote
-In a connection, the address in internal format of the remote peer.
-@item :local
-The local address, in internal format.
-@item :service
-In a server, if you specified @code{t} for @var{service},
-this value is the actual port number.
-@end table
-
-@code{:local} and @code{:remote} are included even if they were not
-specified explicitly in @code{make-network-process}.
-
-If @var{key} is a keyword, the function returns the value corresponding
-to that keyword.
-
-For an ordinary child process, this function always returns @code{t}.
-@end defun
-
 @node Network Servers
 @section Network Servers
 @cindex network servers
@@ -2099,6 +2116,192 @@ If the vector does not include the port number, @var{p}, or if
 @code{:@var{p}} suffix.
 @end defun
 
+@node Serial Ports
+@section Communicating with Serial Ports
+@cindex @file{/dev/tty}
+@cindex @file{COM1}
+
+  Emacs can communicate with serial ports.  For interactive use,
+@kbd{M-x serial-term} opens a terminal window.  In a Lisp program,
+@code{make-serial-process} creates a process object.
+
+  The serial port can be configured at run-time, without having to
+close and re-open it.  The function @code{serial-process-configure}
+lets you change the speed, bytesize, and other parameters.  In a
+terminal window created by @code{serial-term}, you can click on the
+mode line for configuration.
+
+  A serial connection is represented by a process object which can be
+used similar to a subprocess or network process.  You can send and
+receive data and configure the serial port.  A serial process object
+has no process ID, and you can't send signals to it.
+@code{delete-process} on the process object or @code{kill-buffer} on
+the process buffer close the connection, but this does not affect the
+device connected to the serial port.
+
+  The function @code{process-type} returns the symbol @code{serial}
+for a process object representing a serial port.
+
+  Serial ports are available on GNU/Linux, Unix, and Windows systems.
+
+@defun serial-term port speed
+Start a terminal-emulator for a serial port in a new buffer.
+@var{port} is the path or name of the serial port.  For example, this
+could be @file{/dev/ttyS0} on Unix.  On Windows, this could be
+@file{COM1}, or @file{\\.\COM10} (double the backslashes in strings).
+
+@var{speed} is the speed of the serial port in bits per second.  9600
+is a common value.  The buffer is in Term mode; see @code{term-mode}
+for the commands to use in that buffer.  You can change the speed and
+the configuration in the mode line menu.  @end defun
+
+@defun make-serial-process &rest args
+@code{make-serial-process} creates a process and a buffer.  Arguments
+are specified as keyword/argument pairs.  The following arguments are
+defined:
+
+@table @code
+@item :port port
+@var{port} (mandatory) is the path or name of the serial port.
+For example, this could be @file{/dev/ttyS0} on Unix.  On Windows,
+this could be @file{COM1}, or @file{\\.\COM10} for ports higher than
+@file{COM9} (double the backslashes in strings).
+
+@item :speed speed
+@var{speed} (mandatory) is handled by @code{serial-process-configure},
+which is called by @code{make-serial-process}.
+
+@item :name name
+@var{name} is the name of the process.  If @var{name} is not given, the
+value of @var{port} is used.
+
+@item :buffer buffer
+@var{buffer} is the buffer (or buffer-name) to associate with the
+process.  Process output goes at the end of that buffer, unless you
+specify an output stream or filter function to handle the output.  If
+@var{buffer} is not given, the value of @var{name} is used.
+
+@item :coding coding
+If @var{coding} is a symbol, it specifies the coding system used for
+both reading and writing for this process.  If @var{coding} is a cons
+@code{(decoding . encoding)}, @var{decoding} is used for reading, and
+@var{encoding} is used for writing.
+
+@item :noquery bool
+When exiting Emacs, query the user if @var{bool} is @code{nil} and the
+process is running.  If @var{bool} is not given, query before exiting.
+
+@item :stop bool
+Start process in the @code{stopped} state if @var{bool} is
+non-@code{nil}.  In the stopped state, a serial process does not
+accept incoming data, but you can send outgoing data.  The stopped
+state is cleared by @code{continue-process} and set by
+@code{stop-process}.
+
+@item :filter filter
+Install @var{filter} as the process filter.
+
+@item :sentinel sentinel
+Install @var{sentinel} as the process sentinel.
+
+@item :plist plist
+Install @var{plist} as the initial plist of the process.
+
+@item :speed
+@itemx :bytesize
+@itemx :parity
+@itemx :stopbits
+@itemx :flowcontrol
+These arguments are handled by @code{serial-process-configure}, which
+is called by @code{make-serial-process}.
+@end table
+
+The original argument list, possibly modified by later configuration,
+is available via the function @code{process-contact}.
+
+Examples:
+
+@example
+(make-serial-process :port "/dev/ttyS0" :speed 9600)
+
+(make-serial-process :port "COM1" :speed 115200 :stopbits 2)
+
+(make-serial-process :port "\\\\.\\COM13" :speed 1200 :bytesize 7 :parity 'odd)
+
+(make-serial-process :port "/dev/tty.BlueConsole-SPP-1" :speed nil)
+@end example
+@end defun
+
+@defun serial-process-configure &rest args
+@cindex baud
+@cindex bytesize
+@cindex parity
+@cindex stopbits
+@cindex flowcontrol
+
+Configure a serial port.  Arguments are specified as keyword/argument
+pairs.  Attributes that are not given are re-initialized from the
+process's current configuration (available via the function
+@code{process-contact}) or set to reasonable default values.  The
+following arguments are defined:
+
+@table @code
+@item :process process
+@itemx :name name
+@itemx :buffer buffer
+@itemx :port port
+Any of these arguments can be given to identify the process that is to
+be configured.  If none of these arguments is given, the current
+buffer's process is used.
+
+@item :speed @var{speed}
+@var{speed} is the speed of the serial port in bits per second, also
+called baud rate.  Any value can be given for @var{speed}, but most
+serial ports work only at a few defined values between 1200 and
+115200, with 9600 being the most common value.  If @var{speed} is
+@code{nil}, the serial port is not configured any further, i.e., all
+other arguments are ignored.  This may be useful for special serial
+ports such as Bluetooth-to-serial converters which can only be
+configured through AT commands.  A value of @code{nil} for @var{speed}
+can be used only when passed through @code{make-serial-process} or
+@code{serial-term}.
+
+@item :bytesize @var{bytesize}
+@var{bytesize} is the number of bits per byte, which can be 7 or 8.
+If @var{bytesize} is not given or @code{nil}, a value of 8 is used.
+
+@item :parity @var{parity}
+@var{parity} can be @code{nil} (don't use parity), the symbol
+@code{odd} (use odd parity), or the symbol @code{even} (use even
+parity).  If @var{parity} is not given, no parity is used.
+
+@item :stopbits @var{stopbits}
+@var{stopbits} is the number of stopbits used to terminate a byte
+transmission.  @var{stopbits} can be 1 or 2.  If @var{stopbits} is not
+given or @code{nil}, 1 stopbit is used.
+
+@item :flowcontrol @var{flowcontrol}
+@var{flowcontrol} determines the type of flowcontrol to be used, which
+is either @code{nil} (don't use flowcontrol), the symbol @code{hw}
+(use RTS/CTS hardware flowcontrol), or the symbol @code{sw} (use
+XON/XOFF software flowcontrol).  If @var{flowcontrol} is not given, no
+flowcontrol is used.
+@end table
+
+@code{serial-process-configure} is called by @code{make-serial-process} for the
+initial configuration of the serial port.
+
+Examples:
+
+@example
+(serial-process-configure :process "/dev/ttyS0" :speed 1200)
+
+(serial-process-configure :buffer "COM1" :stopbits 1 :parity 'odd :flowcontrol 'hw)
+
+(serial-process-configure :port "\\\\.\\COM13" :bytesize 7)
+@end example
+@end defun
+
 @node Byte Packing
 @section Packing and Unpacking Byte Arrays
 @cindex byte packing and unpacking