Struct SerialPort

Source

pub struct SerialPort { /* private fields */ }

Expand description

One serial port, reached by every clone of this handle.

§Examples

use std::time::Duration;

use pamoja_hal::port::{PortKind, SerialPort, Settings};

// TX wired to RX: what goes out comes straight back.
let port = SerialPort::looped(Settings::new(115_200));
port.write(b"PING\r\n")?;

let mut echo = [0u8; 6];
assert_eq!(port.read(&mut echo, Duration::from_millis(10))?, 6);
assert_eq!(&echo, b"PING\r\n");
assert_eq!(port.kind(), PortKind::Looped);
assert_eq!((port.written(), port.received()), (6, 6));

Implementations§

Source §

impl SerialPort

Source

pub fn open( path: impl AsRef<Path>, settings: Settings, ) -> Result<SerialPort, OpenError>

Opens the kernel’s serial device, raw: no echo, no line editing, no translation, just bytes at the given speed and character format.

Whatever the device received before it was opened is dropped.

§Arguments

path - the device file: /dev/serial0 for a Raspberry Pi’s own UART, /dev/ttyUSB0 or /dev/ttyACM0 for a USB adapter.
settings - the speed, one of the standard rates from 1200 to 921600, and the character format.

§Returns

The port, with the real line on the other end.

§Errors

OpenError::Unsupported anywhere but Linux, or in a build without the linux feature, and OpenError::Device when the file cannot be opened, the rate is not a standard one, or the terminal settings cannot be applied.

§Examples

use pamoja_hal::port::{SerialPort, Settings};

let port = SerialPort::open("/dev/serial0", Settings::new(115_200))?;

Source

pub fn looped(settings: Settings) -> SerialPort

A line looped back on itself: every byte written is waiting to be read, as with TX wired to RX.

§Arguments

settings - the speed and character format the line runs at.

§Returns

The port.

Source

pub fn pair(settings: Settings) -> (SerialPort, SerialPort)

The two ends of a null-modem pair: what one end writes, the other reads.

§Arguments

settings - the speed and character format both ends run at.

§Returns

The two ends.

Source

pub fn simulated(settings: Settings, peer: impl Peer + 'static) -> SerialPort

A simulated device on the other end of the line, answering each write.

§Arguments

settings - the speed and character format the line runs at.
peer - the device.

§Returns

The port.

Source

pub fn scripted( settings: Settings, steps: impl IntoIterator<Item = PortStep>, ) -> SerialPort

A port that plays a script: each write has to be the one the script expects next, and the bytes the far end sends become readable as the script reaches them.

§Arguments

settings - the speed and character format the line runs at.
steps - the writes and reads, in order. Reads at the start are readable at once.

§Returns

The port.

§Examples

use std::time::Duration;

use pamoja_hal::port::{PortStep, SerialPort, Settings};

let port = SerialPort::scripted(
    Settings::new(9_600),
    [PortStep::write(*b"?"), PortStep::read(*b"42")],
);
port.write(b"?")?;
let mut answer = [0u8; 2];
port.read(&mut answer, Duration::from_millis(10))?;
assert_eq!(&answer, b"42");
assert_eq!(port.remaining(), Some(0));
assert!(port.write(b"?").is_err(), "the script is done");

Source

pub fn settings(&self) -> Settings

Returns the speed and character format the port runs at.

Source

pub fn kind(&self) -> PortKind

Returns what is on the other end.

Source

pub fn write(&self, bytes: &[u8]) -> Result<(), PortError>

Writes bytes, and on the kernel’s device waits until they have left the UART.

§Arguments

bytes - the bytes, in order.

§Errors

PortError::Unexpected when a scripted port is written something its script does not expect next, and PortError::Device when the kernel’s device fails.

Source

pub fn read( &self, buffer: &mut [u8], timeout: Duration, ) -> Result<usize, PortError>

Reads what has arrived, waiting up to timeout for the first byte when nothing has.

On any port but the kernel’s device the read does not wait: when nothing has arrived it returns at once, and the timeout is added to SerialPort::waited_micros.

§Arguments

buffer - where the bytes go; at most its length is read.
timeout - how long to wait for the first byte.

§Returns

How many bytes were read, zero when the timeout passed with nothing.

§Errors

PortError::Device when the kernel’s device fails.

Source

pub fn discard_input(&self) -> Result<(), PortError>

Drops whatever has arrived and not been read, as a client does before it sends a request so a stale reply cannot be taken for the new one.

§Errors

PortError::Device when the kernel’s device fails.

Source

pub fn wait(&self, duration: Duration)

Waits, as a protocol does to leave the line silent between frames: the process sleeps on the kernel’s device, and anywhere else the wait is only counted.

§Arguments

duration - how long.

Source

pub fn written(&self) -> usize

Returns how many bytes have been written through this port and every clone of it.

Source

pub fn received(&self) -> usize

Returns how many bytes have been read through this port and every clone of it.

Source

pub fn waited_micros(&self) -> u64

Returns how long reads have waited without an answer, and SerialPort::wait has waited, in microseconds, whether or not the process slept through it.

Source