Struct SerialPort

pub struct SerialPort { /* private fields */ }

An asynchronous serial port for Tokio.

Implementations

impl SerialPort

pub fn open(path: 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

SerialPort::open("/dev/ttyUSB0", 115200)?;

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.

pub fn set_configuration(&mut self, settings: &Settings) -> Result<()>

Configure (or reconfigure) the serial port.

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.

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.

pub async fn read(&self, buf: &mut [u8]) -> Result<usize>

Read bytes from the serial port.

This is identical to AsyncReadExt::read(), except that this function takes a const reference &self. This allows you to use the serial port concurrently from multiple tasks.

Note that there are no guarantees about which task receives what data when multiple tasks are reading from the serial port. You should normally limit yourself to a single reading task and a single writing task.

pub async fn read_vectored(&self, buf: &mut [IoSliceMut<'_>]) -> Result<usize>

Read bytes from the serial port into a slice of buffers.

Note that there are no guarantees about which task receives what data when multiple tasks are reading from the serial port. You should normally limit yourself to a single reading task and a single writing task.

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.

pub async fn write(&self, buf: &[u8]) -> Result<usize>

Write bytes to the serial port.

This is identical to AsyncWriteExt::write(), except that this function takes a const reference &self. This allows you to use the serial port concurrently from multiple tasks.

Note that data written to the same serial port from multiple tasks may end up interleaved at the receiving side. You should normally limit yourself to a single reading task and a single writing task.

pub async fn write_all(&self, buf: &[u8]) -> Result<()>

Write all bytes to the serial port.

This will continue to call Self::write() until the entire buffer has been written, or an I/O error occurs.

This is identical to AsyncWriteExt::write_all(), except that this function takes a const reference &self. This allows you to use the serial port concurrently from multiple tasks.

Note that data written to the same serial port from multiple tasks may end up interleaved at the receiving side. You should normally limit yourself to a single reading task and a single writing task.

pub async fn write_vectored(&self, buf: &[IoSlice<'_>]) -> Result<usize>

Write bytes to the serial port from a slice of buffers.

This is identical to AsyncWriteExt::write_vectored(), except that this function takes a const reference &self. This allows you to use the serial port concurrently from multiple tasks.

Note that data written to the same serial port from multiple tasks may end up interleaved at the receiving side. You should normally limit yourself to a single reading task and a single writing task.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

pub fn get_rs4xx_mode(&self) -> Result<TransceiverMode>

Available on crate feature 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.

pub fn set_rs4xx_mode(&self, mode: impl Into<TransceiverMode>) -> Result<()>

Available on crate feature 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

impl AsyncRead for SerialPort

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl AsyncWrite for SerialPort

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn poll_flush( self: Pin<&mut Self>, _cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Debug for SerialPort

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.