elisp: Serial Ports
36.19 Communicating with Serial Ports
=====================================
Emacs can communicate with serial ports. For interactive use, ‘M-x
serial-term’ opens a terminal window. In a Lisp program,
‘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 ‘serial-process-configure’ lets you
change the speed, bytesize, and other parameters. In a terminal window
created by ‘serial-term’, you can click on the mode line for
configuration.
A serial connection is represented by a process object, which can be
used in a similar way 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, however, and you can’t send signals to it, and
the status codes are different from other types of processes.
‘delete-process’ on the process object or ‘kill-buffer’ on the process
buffer close the connection, but this does not affect the device
connected to the serial port.
The function ‘process-type’ returns the symbol ‘serial’ for a process
object representing a serial port connection.
Serial ports are available on GNU/Linux, Unix, and MS Windows
systems.
-- Command: serial-term port speed
Start a terminal-emulator for a serial port in a new buffer. PORT
is the name of the serial port to connect to. For example, this
could be ‘/dev/ttyS0’ on Unix. On MS Windows, this could be
‘COM1’, or ‘\\.\COM10’ (double the backslashes in Lisp strings).
SPEED is the speed of the serial port in bits per second. 9600 is
a common value. The buffer is in Term mode; see 
(emacs)Term
Mode, for the commands to use in that buffer. You can change the
speed and the configuration in the mode line menu.
-- Function: make-serial-process &rest args
This function creates a process and a buffer. Arguments are
specified as keyword/argument pairs. Here’s the list of the
meaningful keywords, with the first two (PORT and SPEED) being
mandatory:
‘:port PORT’
This is the name of the serial port. On Unix and GNU systems,
this is a file name such as ‘/dev/ttyS0’. On Windows, this
could be ‘COM1’, or ‘\\.\COM10’ for ports higher than ‘COM9’
(double the backslashes in Lisp strings).
‘:speed SPEED’
The speed of the serial port in bits per second. This
function calls ‘serial-process-configure’ to handle the speed;
see the following documentation of that function for more
details.
‘:name NAME’
The name of the process. If NAME is not given, PORT will
serve as the process name as well.
‘:buffer BUFFER’
The buffer to associate with the process. The value can be
either a buffer or a string that names a buffer. Process
output goes at the end of that buffer, unless you specify an
output stream or filter function to handle the output. If
BUFFER is not given, the process buffer’s name is taken from
the value of the ‘:name’ keyword.
‘:coding CODING’
If CODING is a symbol, it specifies the coding system used for
both reading and writing for this process. If CODING is a
cons ‘(DECODING . ENCODING)’, DECODING is used for reading,
and ENCODING is used for writing. If not specified, the
default is to determine the coding systems from the data
itself.
‘:noquery QUERY-FLAG’
Initialize the process query flag to QUERY-FLAG. Query
Before Exit. The flags defaults to ‘nil’ if unspecified.
‘:stop BOOL’
Start process in the stopped state if BOOL is non-‘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 ‘continue-process’ and set by ‘stop-process’.
‘:filter FILTER’
Install FILTER as the process filter.
‘:sentinel SENTINEL’
Install SENTINEL as the process sentinel.
‘:plist PLIST’
Install PLIST as the initial plist of the process.
‘:bytesize’
‘:parity’
‘:stopbits’
‘:flowcontrol’
These are handled by ‘serial-process-configure’, which is
called by ‘make-serial-process’.
The original argument list, possibly modified by later
configuration, is available via the function ‘process-contact’.
Here is an example:
(make-serial-process :port "/dev/ttyS0" :speed 9600)
-- Function: serial-process-configure &rest args
This function configures a serial port connection. 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 ‘process-contact’), or set to
reasonable default values. The following arguments are defined:
‘:process PROCESS’
‘:name NAME’
‘:buffer BUFFER’
‘: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.
‘:speed SPEED’
The speed of the serial port in bits per second, a.k.a. “baud
rate”. The value can be any number, but most serial ports
work only at a few defined values between 1200 and 115200,
with 9600 being the most common value. If SPEED is ‘nil’, the
function ignores all other arguments and does not configure
the port. This may be useful for special serial ports such as
Bluetooth-to-serial converters, which can only be configured
through ‘AT’ commands sent through the connection. The value
of ‘nil’ for SPEED is valid only for connections that were
already opened by a previous call to ‘make-serial-process’ or
‘serial-term’.
‘:bytesize BYTESIZE’
The number of bits per byte, which can be 7 or 8. If BYTESIZE
is not given or ‘nil’, it defaults to 8.
‘:parity PARITY’
The value can be ‘nil’ (don’t use parity), the symbol ‘odd’
(use odd parity), or the symbol ‘even’ (use even parity). If
PARITY is not given, it defaults to no parity.
‘:stopbits STOPBITS’
The number of stopbits used to terminate a transmission of
each byte. STOPBITS can be 1 or 2. If STOPBITS is not given
or ‘nil’, it defaults to 1.
‘:flowcontrol FLOWCONTROL’
The type of flow control to use for this connection, which is
either ‘nil’ (don’t use flow control), the symbol ‘hw’ (use
RTS/CTS hardware flow control), or the symbol ‘sw’ (use
XON/XOFF software flow control). If FLOWCONTROL is not given,
it defaults to no flow control.
Internally, ‘make-serial-process’ calls ‘serial-process-configure’
for the initial configuration of the serial port.
Info Catalog
elisp: Misc Network
elisp: Processes
elisp: Byte Packing