pub struct SerialPort { /* private fields */ }
Expand description
A serial port.
Implementations§
Source§impl SerialPort
impl SerialPort
Sourcepub fn open(name: impl AsRef<Path>, settings: impl IntoSettings) -> Result<Self>
pub fn open(name: impl AsRef<Path>, settings: impl IntoSettings) -> Result<Self>
Open and configure a serial port by path or name.
On Unix systems, the name
parameter must be a path to a TTY device.
On Windows, it must be the name of a COM device, such as COM1, COM2, etc.
The second argument is used to configure the serial port.
For simple cases, you pass a u32
for the baud rate.
See IntoSettings
for more information.
The library automatically uses the win32 device namespace on Windows, so COM ports above COM9 are supported out of the box.
§Example 1: Open a serial port with a specific baud rate and default settings.
SerialPort::open("/dev/ttyUSB0", 115200)?;
§Example 2: Open a serial port with full control over the settings.
SerialPort::open("/dev/ttyUSB0", |mut settings: Settings| {
settings.set_raw();
settings.set_baud_rate(115200)?;
settings.set_char_size(CharSize::Bits7);
settings.set_stop_bits(StopBits::Two);
settings.set_parity(Parity::Odd);
settings.set_flow_control(FlowControl::RtsCts);
Ok(settings)
})?;
Sourcepub fn pair() -> Result<(Self, Self)>
Available on crate feature unix
only.
pub fn pair() -> Result<(Self, Self)>
unix
only.Open a connected pair of pseudo-terminals.
Sourcepub fn available_ports() -> Result<Vec<PathBuf>>
pub fn available_ports() -> Result<Vec<PathBuf>>
Get a list of available serial ports.
Not currently supported on all platforms. On unsupported platforms, this function always returns an error.
Sourcepub fn set_configuration(&mut self, settings: &Settings) -> Result<()>
pub fn set_configuration(&mut self, settings: &Settings) -> Result<()>
Configure (or reconfigure) the serial port.
Sourcepub fn get_configuration(&self) -> Result<Settings>
pub fn get_configuration(&self) -> Result<Settings>
Get the current configuration of the serial port.
This function can fail if the underlying syscall fails,
or if the serial port configuration can’t be reported using Settings
.
Sourcepub fn try_clone(&self) -> Result<Self>
pub fn try_clone(&self) -> Result<Self>
Try to clone the serial port handle.
The cloned object refers to the same serial port.
Mixing reads and writes on different handles to the same serial port from different threads may lead to unexpect results. The data may end up interleaved in unpredictable ways.
Sourcepub fn read(&self, buf: &mut [u8]) -> Result<usize>
pub fn read(&self, buf: &mut [u8]) -> Result<usize>
Read bytes from the serial port.
This is identical to std::io::Read::read()
, except that this function takes a const reference &self
.
This allows you to use the serial port concurrently from multiple threads.
Note that there are no guarantees on which thread receives what data when multiple threads are reading from the serial port. You should normally limit yourself to a single reading thread and a single writing thread.
Sourcepub fn read_vectored(&self, buf: &mut [IoSliceMut<'_>]) -> Result<usize>
pub fn read_vectored(&self, buf: &mut [IoSliceMut<'_>]) -> Result<usize>
Read bytes from the serial port into a slice of buffers.
This is identical to std::io::Read::read_vectored()
, except that this function takes a const reference &self
.
This allows you to use the serial port concurrently from multiple threads.
Note that there are no guarantees on which thread receives what data when multiple threads are reading from the serial port. You should normally limit yourself to a single reading thread and a single writing thread.
Sourcepub fn is_read_vectored(&self) -> bool
pub fn is_read_vectored(&self) -> bool
Check if the implementation supports vectored reads.
If this returns false, then Self::read_vectored()
will only use the first buffer of the given slice.
All platforms except for Windows support vectored reads.
Sourcepub fn read_exact(&self, buf: &mut [u8]) -> Result<()>
pub fn read_exact(&self, buf: &mut [u8]) -> Result<()>
Read the exact number of bytes required to fill the buffer from the serial port.
This will repeatedly call read()
until the entire buffer is filled.
Errors of the type std::io::ErrorKind::Interrupted
are silently ignored.
Any other errors (including timeouts) will be returned immediately.
If this function returns an error, it may already have read some data from the serial port into the provided buffer.
This function is identical to std::io::Read::read_exact()
, except that this function takes a const reference &self
.
This allows you to use the serial port concurrently from multiple threads.
Note that there are no guarantees on which thread receives what data when multiple threads are reading from the serial port. You should normally limit yourself to a single reading thread and a single writing thread.
Sourcepub fn write(&self, buf: &[u8]) -> Result<usize>
pub fn write(&self, buf: &[u8]) -> Result<usize>
Write bytes to the serial port.
This is identical to std::io::Write::write()
, except that this function takes a const reference &self
.
This allows you to use the serial port concurrently from multiple threads.
Note that data written to the same serial port from multiple threads may end up interleaved at the receiving side. You should normally limit yourself to a single reading thread and a single writing thread.
Sourcepub fn write_all(&self, buf: &[u8]) -> Result<()>
pub fn write_all(&self, buf: &[u8]) -> Result<()>
Write all bytes to the serial port.
This will repeatedly call Self::write()
until the entire buffer has been written.
Errors of the type std::io::ErrorKind::Interrupted
are silently ignored.
Any other errors (including timeouts) will be returned immediately.
If this function returns an error, it may already have transmitted some data from the buffer over the serial port.
This is identical to std::io::Write::write_all()
, except that this function takes a const reference &self
.
This allows you to use the serial port concurrently from multiple threads.
Note that data written to the same serial port from multiple threads may end up interleaved at the receiving side. You should normally limit yourself to a single reading thread and a single writing thread.
Sourcepub fn write_vectored(&self, buf: &[IoSlice<'_>]) -> Result<usize>
pub fn write_vectored(&self, buf: &[IoSlice<'_>]) -> Result<usize>
Write bytes to the serial port from a slice of buffers.
This is identical to std::io::Write::write_vectored()
, except that this function takes a const reference &self
.
This allows you to use the serial port concurrently from multiple threads.
Note that data written to the same serial port from multiple threads may end up interleaved at the receiving side. You should normally limit yourself to a single reading thread and a single writing thread.
Sourcepub fn is_write_vectored(&self) -> bool
pub fn is_write_vectored(&self) -> bool
Check if the implementation supports vectored writes.
If this returns false, then Self::write_vectored()
will only use the first buffer of the given slice.
All platforms except for Windows support vectored writes.
Sourcepub fn flush(&self) -> Result<()>
pub fn flush(&self) -> Result<()>
Flush all data queued to be written.
This will block until the OS buffer has been fully transmitted.
This is identical to std::io::Write::flush()
, except that this function takes a const reference &self
.
Sourcepub fn set_read_timeout(&mut self, timeout: Duration) -> Result<()>
pub fn set_read_timeout(&mut self, timeout: Duration) -> Result<()>
Set the read timeout for the serial port.
The timeout set by this function is an upper bound on individual calls to read()
.
Other platform specific time-outs may trigger before this timeout does.
Additionally, some functions (like Self::read_exact
) perform multiple calls to read()
.
Sourcepub fn get_read_timeout(&self) -> Result<Duration>
pub fn get_read_timeout(&self) -> Result<Duration>
Get the read timeout of the serial port.
The timeout set by this function is an upper bound on individual calls to read()
.
Other platform specific time-outs may trigger before this timeout does.
Additionally, some functions (like Self::read_exact
) perform multiple calls to read()
.
Sourcepub fn set_write_timeout(&mut self, timeout: Duration) -> Result<()>
pub fn set_write_timeout(&mut self, timeout: Duration) -> Result<()>
Set the write timeout for the serial port.
The timeout set by this function is an upper bound on individual calls to write()
.
Other platform specific time-outs may trigger before this timeout does.
Additionally, some functions (like Self::write_all
) perform multiple calls to write()
.
Sourcepub fn get_write_timeout(&self) -> Result<Duration>
pub fn get_write_timeout(&self) -> Result<Duration>
Get the write timeout of the serial port.
The timeout set by this function is an upper bound on individual calls to write()
.
Other platform specific time-outs may trigger before this timeout does.
Additionally, some functions (like Self::write_all
) perform multiple calls to write()
.
Sourcepub fn get_windows_timeouts(&self) -> Result<CommTimeouts>
Available on crate feature windows
only.
pub fn get_windows_timeouts(&self) -> Result<CommTimeouts>
windows
only.Get the platform specific timeouts of a serial port on Windows.
This allows for full control over the platform specifics timeouts, but it is only available on Windows.
Also note that changing the read timeouts can easily lead to the serial port timing out on every read unless you are very careful. Please read the whole article about serial port timeouts on MSDN before using this, including all remarks: https://learn.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-commtimeouts
You are strongly suggested to use Self::get_read_timeout()
and Self::get_write_timeout()
instead.
Sourcepub fn set_windows_timeouts(&self, timeouts: &CommTimeouts) -> Result<()>
Available on crate feature windows
only.
pub fn set_windows_timeouts(&self, timeouts: &CommTimeouts) -> Result<()>
windows
only.Set the platform specific timeouts of a serial port on Windows.
This allows for full control over the platform specifics timeouts, but it is only available on Windows.
Also note that changing the read timeouts can easily lead to the serial port timing out on every read unless you are very careful. Please read the whole article about serial port timeouts on MSDN before using this, including all remarks: https://learn.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-commtimeouts
You are strongly suggested to use Self::set_read_timeout()
and Self::set_write_timeout()
instead.
Sourcepub fn discard_buffers(&self) -> Result<()>
pub fn discard_buffers(&self) -> Result<()>
Discard the kernel input and output buffers for the serial port.
When you write to a serial port, the data may be put in a buffer by the OS to be transmitted by the actual device later. Similarly, data received on the device can be put in a buffer by the OS untill you read it. This function clears both buffers: any untransmitted data and received but unread data is discarded by the OS.
Sourcepub fn discard_input_buffer(&self) -> Result<()>
pub fn discard_input_buffer(&self) -> Result<()>
Discard the kernel input buffers for the serial port.
Data received on the device can be put in a buffer by the OS untill you read it. This function clears that buffer: received but unread data is discarded by the OS.
This is particularly useful when communicating with a device that only responds to commands that you send to it. If you discard the input buffer before sending the command, you discard any noise that may have been received after the last command.
Sourcepub fn discard_output_buffer(&self) -> Result<()>
pub fn discard_output_buffer(&self) -> Result<()>
Discard the kernel output buffers for the serial port.
When you write to a serial port, the data is generally put in a buffer by the OS to be transmitted by the actual device later. This function clears that buffer: any untransmitted data is discarded by the OS.
Sourcepub fn set_rts(&self, state: bool) -> Result<()>
pub fn set_rts(&self, state: bool) -> Result<()>
Set the state of the Ready To Send line.
If hardware flow control is enabled on the serial port, it is platform specific what will happen. The function may fail with an error, or it may silently be ignored. It may even succeed and interfere with the flow control.
Sourcepub fn read_cts(&self) -> Result<bool>
pub fn read_cts(&self) -> Result<bool>
Read the state of the Clear To Send line.
If hardware flow control is enabled on the serial port, it is platform specific what will happen. The function may fail with an error, it may return a bogus value, or it may return the actual state of the CTS line.
Sourcepub fn set_dtr(&self, state: bool) -> Result<()>
pub fn set_dtr(&self, state: bool) -> Result<()>
Set the state of the Data Terminal Ready line.
If hardware flow control is enabled on the serial port, it is platform specific what will happen. The function may fail with an error, or it may silently be ignored.
Sourcepub fn read_dsr(&self) -> Result<bool>
pub fn read_dsr(&self) -> Result<bool>
Read the state of the Data Set Ready line.
If hardware flow control is enabled on the serial port, it is platform specific what will happen. The function may fail with an error, it may return a bogus value, or it may return the actual state of the DSR line.
Sourcepub fn read_ri(&self) -> Result<bool>
pub fn read_ri(&self) -> Result<bool>
Read the state of the Ring Indicator line.
This line is also sometimes also called the RNG or RING line.
Sourcepub fn read_cd(&self) -> Result<bool>
pub fn read_cd(&self) -> Result<bool>
Read the state of the Carrier Detect (CD) line.
This line is also called the Data Carrier Detect (DCD) line or the Receive Line Signal Detect (RLSD) line.
Sourcepub fn set_break(&self, enable: bool) -> Result<()>
pub fn set_break(&self, enable: bool) -> Result<()>
Set or clear the break state of the serial port.
The serial port will hold the data line in a logical low state while the break state is enabled. This can be detected as a break condition on the other side of the line.
Sourcepub fn get_rs4xx_mode(&self) -> Result<TransceiverMode>
Available on crate feature rs4xx
and Linux only.
pub fn get_rs4xx_mode(&self) -> Result<TransceiverMode>
rs4xx
and Linux only.Get the RS-4xx mode of the serial port transceiver.
This is currently only supported on Linux.
Not all serial ports can be configured in a different mode by software.
Some serial ports are always in RS-485 or RS-422 mode,
and some may have hardware switches or jumpers to configure the transceiver.
In those cases, this function will usually report an error or rs4xx::TransceiverMode::Default
,
even though the serial port is configured is RS-485 or RS-422 mode.
Note that driver support for this feature is very limited and sometimes inconsistent.
Please read all the warnings in the rs4xx
module carefully.
Sourcepub fn set_rs4xx_mode(&self, mode: impl Into<TransceiverMode>) -> Result<()>
Available on crate feature rs4xx
and Linux only.
pub fn set_rs4xx_mode(&self, mode: impl Into<TransceiverMode>) -> Result<()>
rs4xx
and Linux only.Set the RS-4xx mode of the serial port transceiver.
This is currently only supported on Linux.
Not all serial ports can be configured in a different mode by software. Some serial ports are always in RS-485 or RS-422 mode, and some may have hardware switches or jumpers to configure the transceiver. In that case, this function will usually return an error, but the port can still be in RS-485 or RS-422 mode.
Note that driver support for this feature is very limited and sometimes inconsistent.
Please read all the warnings in the rs4xx
module carefully.
Trait Implementations§
Source§impl AsFd for SerialPort
impl AsFd for SerialPort
Source§fn as_fd(&self) -> BorrowedFd<'_>
fn as_fd(&self) -> BorrowedFd<'_>
Source§impl AsRawFd for SerialPort
impl AsRawFd for SerialPort
Source§impl Debug for SerialPort
impl Debug for SerialPort
Source§impl From<OwnedFd> for SerialPort
impl From<OwnedFd> for SerialPort
Source§impl From<SerialPort> for OwnedFd
impl From<SerialPort> for OwnedFd
Source§fn from(value: SerialPort) -> Self
fn from(value: SerialPort) -> Self
Source§impl FromRawFd for SerialPort
impl FromRawFd for SerialPort
Source§unsafe fn from_raw_fd(fd: RawFd) -> Self
unsafe fn from_raw_fd(fd: RawFd) -> Self
Self
from the given raw file
descriptor. Read moreSource§impl IntoRawFd for SerialPort
impl IntoRawFd for SerialPort
Source§fn into_raw_fd(self) -> RawFd
fn into_raw_fd(self) -> RawFd
Source§impl Read for &SerialPort
impl Read for &SerialPort
Source§fn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
Source§fn read_vectored(&mut self, buf: &mut [IoSliceMut<'_>]) -> Result<usize>
fn read_vectored(&mut self, buf: &mut [IoSliceMut<'_>]) -> Result<usize>
read
, except that it reads into a slice of buffers. Read moreSource§fn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)1.0.0 · Source§fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
buf
. Read more1.0.0 · Source§fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · Source§fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moreSource§fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)Source§fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · Source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Read
. Read moreSource§impl Read for SerialPort
impl Read for SerialPort
Source§fn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
Source§fn read_vectored(&mut self, buf: &mut [IoSliceMut<'_>]) -> Result<usize>
fn read_vectored(&mut self, buf: &mut [IoSliceMut<'_>]) -> Result<usize>
read
, except that it reads into a slice of buffers. Read moreSource§fn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)1.0.0 · Source§fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>
buf
. Read more1.0.0 · Source§fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · Source§fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moreSource§fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)Source§fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · Source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Read
. Read moreSource§impl Write for &SerialPort
impl Write for &SerialPort
Source§fn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
Source§fn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
Source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · Source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)Source§impl Write for SerialPort
impl Write for SerialPort
Source§fn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
Source§fn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
Source§fn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · Source§fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Source§fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)