1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305
use std::io::{IoSlice, IoSliceMut};
use std::path::{Path, PathBuf};
use std::time::Duration;
use crate::{sys, IntoSettings, Settings};
/// A serial port.
pub struct SerialPort {
inner: sys::SerialPort,
}
impl SerialPort {
/// 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.
///
/// # Example
/// ```no_run
/// # use serial2::SerialPort;
/// # fn main() -> std::io::Result<()> {
/// SerialPort::open("/dev/ttyUSB0", 115200)?;
/// # Ok(())
/// # }
/// ```
pub fn open(name: impl AsRef<Path>, settings: impl IntoSettings) -> std::io::Result<Self> {
let mut serial_port = Self {
inner: sys::SerialPort::open(name.as_ref())?,
};
let mut port_settings = serial_port.get_configuration()?;
settings.apply_to_settings(&mut port_settings)?;
serial_port.set_configuration(&port_settings)?;
Ok(serial_port)
}
/// Get a list of available serial ports.
///
/// Not currently supported on all platforms.
/// On unsupported platforms, this function always returns an error.
pub fn available_ports() -> std::io::Result<Vec<PathBuf>> {
sys::enumerate()
}
/// Configure (or reconfigure) the serial port.
pub fn set_configuration(&mut self, settings: &Settings) -> std::io::Result<()> {
self.inner.set_configuration(&settings.inner)
}
/// 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 get_configuration(&self) -> std::io::Result<Settings> {
Ok(Settings {
inner: self.inner.get_configuration()?,
})
}
/// 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.
pub fn read(&self, buf: &mut [u8]) -> std::io::Result<usize> {
self.inner.read(buf)
}
/// 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.
pub fn read_vectored(&self, buf: &mut [IoSliceMut<'_>]) -> std::io::Result<usize> {
self.inner.read_vectored(buf)
}
/// 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 fn is_read_vectored(&self) -> bool {
self.inner.is_read_vectored()
}
/// 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.
pub fn write(&self, buf: &[u8]) -> std::io::Result<usize> {
self.inner.write(buf)
}
/// 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.
pub fn write_vectored(&self, buf: &[IoSlice<'_>]) -> std::io::Result<usize> {
self.inner.write_vectored(buf)
}
/// 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 is_write_vectored(&self) -> bool {
self.inner.is_write_vectored()
}
/// 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`.
pub fn flush(&self) -> std::io::Result<()> {
self.inner.flush_output()
}
/// Set the read timeout for the serial port.
///
/// The timeout set by this function is an upper bound on individual calls to [`std::io::Read::read()`].
/// Other platform specific time-outs may trigger before this timeout does.
pub fn set_read_timeout(&mut self, timeout: Duration) -> std::io::Result<()> {
self.inner.set_read_timeout(timeout)
}
/// Get the read timeout of the serial port.
pub fn get_read_timeout(&self) -> std::io::Result<Duration> {
self.inner.get_read_timeout()
}
/// Set the write timeout for the serial port.
///
/// The timeout set by this function is an upper bound on individual calls to [`std::io::Write::write()`].
/// Other platform specific time-outs may trigger before this timeout does.
pub fn set_write_timeout(&mut self, timeout: Duration) -> std::io::Result<()> {
self.inner.set_write_timeout(timeout)
}
/// Get the write timeout of the serial port.
pub fn get_write_timeout(&self) -> std::io::Result<Duration> {
self.inner.get_write_timeout()
}
/// 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_buffers(&self) -> std::io::Result<()> {
self.inner.discard_buffers(true, true)
}
/// 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_input_buffer(&self) -> std::io::Result<()> {
self.inner.discard_buffers(true, false)
}
/// 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 discard_output_buffer(&self) -> std::io::Result<()> {
self.inner.discard_buffers(false, true)
}
/// 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 set_rts(&self, state: bool) -> std::io::Result<()> {
self.inner.set_rts(state)
}
/// 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 read_cts(&self) -> std::io::Result<bool> {
self.inner.read_cts()
}
/// 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 set_dtr(&self, state: bool) -> std::io::Result<()> {
self.inner.set_dtr(state)
}
/// 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_dsr(&self) -> std::io::Result<bool> {
self.inner.read_dsr()
}
/// Read the state of the Ring Indicator line.
///
/// This line is also sometimes also called the RNG or RING line.
pub fn read_ri(&self) -> std::io::Result<bool> {
self.inner.read_ri()
}
/// 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 read_cd(&self) -> std::io::Result<bool> {
self.inner.read_cd()
}
}
impl std::io::Read for SerialPort {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
self.inner.read(buf)
}
fn read_vectored(&mut self, buf: &mut [IoSliceMut<'_>]) -> std::io::Result<usize> {
self.inner.read_vectored(buf)
}
}
impl std::io::Write for SerialPort {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
self.inner.write(buf)
}
fn write_vectored(&mut self, buf: &[IoSlice<'_>]) -> std::io::Result<usize> {
self.inner.write_vectored(buf)
}
fn flush(&mut self) -> std::io::Result<()> {
self.inner.flush_output()
}
}
#[cfg(unix)]
impl std::os::unix::io::AsRawFd for SerialPort {
fn as_raw_fd(&self) -> std::os::unix::io::RawFd {
self.inner.file.as_raw_fd()
}
}
#[cfg(unix)]
impl std::os::unix::io::IntoRawFd for SerialPort {
fn into_raw_fd(self) -> std::os::unix::io::RawFd {
self.inner.file.into_raw_fd()
}
}
#[cfg(unix)]
impl std::os::unix::io::FromRawFd for SerialPort {
unsafe fn from_raw_fd(fd: std::os::unix::io::RawFd) -> Self {
use std::fs::File;
Self {
inner: sys::SerialPort::from_file(File::from_raw_fd(fd)),
}
}
}
#[cfg(windows)]
impl std::os::windows::io::AsRawHandle for SerialPort {
fn as_raw_handle(&self) -> std::os::windows::io::RawHandle {
self.inner.file.as_raw_handle()
}
}
#[cfg(windows)]
impl std::os::windows::io::IntoRawHandle for SerialPort {
fn into_raw_handle(self) -> std::os::windows::io::RawHandle {
self.inner.file.into_raw_handle()
}
}
#[cfg(windows)]
impl std::os::windows::io::FromRawHandle for SerialPort {
unsafe fn from_raw_handle(handle: std::os::windows::io::RawHandle) -> Self {
use std::fs::File;
Self {
inner: sys::SerialPort::from_file(File::from_raw_handle(handle)),
}
}
}