path: root/devdocs/elisp/serial-ports.html

 <h3 class="section">Communicating with Serial Ports</h3>    <p>Emacs can communicate with serial ports. For interactive use, <kbd>M-x serial-term</kbd> opens a terminal window. In a Lisp program, <code>make-serial-process</code> creates a process object. </p> <p>The serial port can be configured at run-time, without having to close and re-open it. The function <code>serial-process-configure</code> lets you change the speed, bytesize, and other parameters. In a terminal window created by <code>serial-term</code>, you can click on the mode line for configuration. </p> <p>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. <code>delete-process</code> on the process object or <code>kill-buffer</code> on the process buffer close the connection, but this does not affect the device connected to the serial port. </p> <p>The function <code>process-type</code> returns the symbol <code>serial</code> for a process object representing a serial port connection. </p> <p>Serial ports are available on GNU/Linux, Unix, and MS Windows systems. </p> <dl> <dt id="serial-term">Command: <strong>serial-term</strong> <em>port speed &amp;optional line-mode</em>
</dt> <dd>
<p>Start a terminal-emulator for a serial port in a new buffer. <var>port</var> is the name of the serial port to connect to. For example, this could be <samp>/dev/ttyS0</samp> on Unix. On MS Windows, this could be <samp>COM1</samp>, or <samp>\\.\COM10</samp> (double the backslashes in Lisp strings). </p> <p><var>speed</var> is the speed of the serial port in bits per second. 9600 is a common value. The buffer is in Term mode; see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Term-Mode.html#Term-Mode">Term Mode</a> in <cite>The GNU Emacs Manual</cite>, for the commands to use in that buffer. You can change the speed and the configuration in the mode line menu. If <var>line-mode</var> is non-<code>nil</code>, <code>term-line-mode</code> is used; otherwise <code>term-raw-mode</code> is used. </p>
</dd>
</dl> <dl> <dt id="make-serial-process">Function: <strong>make-serial-process</strong> <em>&amp;rest args</em>
</dt> <dd>
<p>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 (<var>port</var> and <var>speed</var>) being mandatory: </p> <dl compact> <dt><code>:port <var>port</var></code></dt> <dd>
<p>This is the name of the serial port. On Unix and GNU systems, this is a file name such as <samp>/dev/ttyS0</samp>. On Windows, this could be <samp>COM1</samp>, or <samp>\\.\COM10</samp> for ports higher than <samp>COM9</samp> (double the backslashes in Lisp strings). </p> </dd> <dt><code>:speed <var>speed</var></code></dt> <dd>
<p>The speed of the serial port in bits per second. This function calls <code>serial-process-configure</code> to handle the speed; see the following documentation of that function for more details. </p> </dd> <dt><code>:name <var>name</var></code></dt> <dd>
<p>The name of the process. If <var>name</var> is not given, <var>port</var> will serve as the process name as well. </p> </dd> <dt><code>:buffer <var>buffer</var></code></dt> <dd>
<p>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 <var>buffer</var> is not given, the process buffer’s name is taken from the value of the <code>:name</code> keyword. </p> </dd> <dt><code>:coding <var>coding</var></code></dt> <dd>
<p>If <var>coding</var> is a symbol, it specifies the coding system used for both reading and writing for this process. If <var>coding</var> is a cons <code>(<var>decoding</var> . <var>encoding</var>)</code>, <var>decoding</var> is used for reading, and <var>encoding</var> is used for writing. If not specified, the default is to determine the coding systems from the data itself. </p> </dd> <dt><code>:noquery <var>query-flag</var></code></dt> <dd>
<p>Initialize the process query flag to <var>query-flag</var>. See <a href="query-before-exit">Query Before Exit</a>. The flags defaults to <code>nil</code> if unspecified. </p> </dd> <dt><code>:stop <var>bool</var></code></dt> <dd>
<p>Start process in the stopped state if <var>bool</var> is non-<code>nil</code>. 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</code> and set by <code>stop-process</code>. </p> </dd> <dt><code>:filter <var>filter</var></code></dt> <dd>
<p>Install <var>filter</var> as the process filter. </p> </dd> <dt><code>:sentinel <var>sentinel</var></code></dt> <dd>
<p>Install <var>sentinel</var> as the process sentinel. </p> </dd> <dt><code>:plist <var>plist</var></code></dt> <dd>
<p>Install <var>plist</var> as the initial plist of the process. </p> </dd> <dt><code>:bytesize</code></dt> <dt><code>:parity</code></dt> <dt><code>:stopbits</code></dt> <dt><code>:flowcontrol</code></dt> <dd><p>These are handled by <code>serial-process-configure</code>, which is called by <code>make-serial-process</code>. </p></dd> </dl> <p>The original argument list, possibly modified by later configuration, is available via the function <code>process-contact</code>. </p> <p>Here is an example: </p> <div class="example"> <pre class="example">(make-serial-process :port "/dev/ttyS0" :speed 9600)
</pre>
</div> </dd>
</dl> <dl> <dt id="serial-process-configure">Function: <strong>serial-process-configure</strong> <em>&amp;rest args</em>
</dt> <dd>
     <p>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 <code>process-contact</code>), or set to reasonable default values. The following arguments are defined: </p> <dl compact> <dt><code>:process <var>process</var></code></dt> <dt><code>:name <var>name</var></code></dt> <dt><code>:buffer <var>buffer</var></code></dt> <dt><code>:port <var>port</var></code></dt> <dd>
<p>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. </p> </dd> <dt><code>:speed <var>speed</var></code></dt> <dd>
<p>The speed of the serial port in bits per second, a.k.a. <em>baud rate</em>. 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 <var>speed</var> is <code>nil</code>, 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 ‘<samp>AT</samp>’ commands sent through the connection. The value of <code>nil</code> for <var>speed</var> is valid only for connections that were already opened by a previous call to <code>make-serial-process</code> or <code>serial-term</code>. </p> </dd> <dt><code>:bytesize <var>bytesize</var></code></dt> <dd>
<p>The number of bits per byte, which can be 7 or 8. If <var>bytesize</var> is not given or <code>nil</code>, it defaults to 8. </p> </dd> <dt><code>:parity <var>parity</var></code></dt> <dd>
<p>The value can be <code>nil</code> (don’t use parity), the symbol <code>odd</code> (use odd parity), or the symbol <code>even</code> (use even parity). If <var>parity</var> is not given, it defaults to no parity. </p> </dd> <dt><code>:stopbits <var>stopbits</var></code></dt> <dd>
<p>The number of stopbits used to terminate a transmission of each byte. <var>stopbits</var> can be 1 or 2. If <var>stopbits</var> is not given or <code>nil</code>, it defaults to 1. </p> </dd> <dt><code>:flowcontrol <var>flowcontrol</var></code></dt> <dd><p>The type of flow control to use for this connection, which is either <code>nil</code> (don’t use flow control), the symbol <code>hw</code> (use RTS/CTS hardware flow control), or the symbol <code>sw</code> (use XON/XOFF software flow control). If <var>flowcontrol</var> is not given, it defaults to no flow control. </p></dd> </dl> <p>Internally, <code>make-serial-process</code> calls <code>serial-process-configure</code> for the initial configuration of the serial port. </p>
</dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Serial-Ports.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Serial-Ports.html</a>
  </p>
</div>