Expand description
§Embedded Serial traits
Traits to describe Serial port (UART) functionality.
A serial port is taken here to mean a device which can send and/or receive
data one octet at a time, in order. Octets are represented using the u8
type. We are careful here to talk only in octets, not characters (although
if you ASCII or UTF-8 encode your strings, they become a sequence of
octets).
This crate contains traits that are suitable for embedded development. This allows developers to produce crates that depend upon generic UART functionality (for example, an AT command interface), allowing the application developer to combine the crate with the specific UART available on their board.
It is similar to the C idea of using the functions getc
and putc
to
decouple the IO device from the library, but in a more Rustic fashion.
Here’s an example with the MutBlockingTx
trait.
use embedded_serial::MutBlockingTx;
struct SomeStruct<T> { uart: T };
impl<T> SomeStruct<T> where T: MutBlockingTx {
fn new(uart: T) -> SomeStruct<T> {
SomeStruct { uart: uart }
}
fn write_data(&mut self) -> Result<(), <T as MutBlockingTx>::Error> {
self.uart.puts(b"AT\n").map_err(|e| e.1)?;
Ok(())
}
}
Here’s an example with the MutBlockingTxWithTimeout
trait.
struct SomeStruct<T> { uart: T };
use embedded_serial::MutBlockingTxWithTimeout;
impl<T> SomeStruct<T> where T: MutBlockingTxWithTimeout {
fn new(uart: T) -> SomeStruct<T> {
SomeStruct { uart: uart }
}
fn write_data(&mut self, timeout: &<T as MutBlockingTxWithTimeout>::Timeout) -> Result<bool, <T as MutBlockingTxWithTimeout>::Error> {
let len = self.uart.puts_wait(b"AT\n", timeout).map_err(|e| e.1)?;
Ok(len == 3)
}
}
Here’s an example with the MutNonBlockingTx
trait. You would call the write_data
function until it returned Ok(true)
.
use embedded_serial::MutNonBlockingTx;
struct SomeStruct<T> {
sent: Option<usize>,
uart: T
};
impl<T> SomeStruct<T> where T: MutNonBlockingTx {
fn new(uart: T) -> SomeStruct<T> {
SomeStruct { uart: uart, sent: Some(0) }
}
fn write_data(&mut self) -> Result<bool, <T as MutNonBlockingTx>::Error> {
let data = b"AT\n";
if let Some(len) = self.sent {
match self.uart.puts_try(&data[len..]) {
// Sent some or more of the data
Ok(sent) => {
let total = len + sent;
self.sent = if total == data.len() {
None
} else {
Some(total)
};
Ok(false)
}
// Sent some of the data but errored out
Err((sent, e)) => {
let total = len + sent;
self.sent = if total == data.len() {
None
} else {
Some(total)
};
Err(e)
}
}
} else {
Ok(true)
}
}
}
In this example, we read three octets from a blocking serial port.
use embedded_serial::MutBlockingRx;
pub struct SomeStruct<T> { uart: T }
impl<T> SomeStruct<T> where T: MutBlockingRx {
pub fn new(uart: T) -> SomeStruct<T> {
SomeStruct { uart: uart }
}
pub fn read_response(&mut self) -> Result<(), <T as MutBlockingRx>::Error> {
let mut buffer = [0u8; 3];
// If we got an error, we don't care any many we actually received.
self.uart.gets(&mut buffer).map_err(|e| e.1)?;
// process data in buffer here
Ok(())
}
}
In this example, we read three octets from a blocking serial port, with a timeout.
use embedded_serial::MutBlockingRxWithTimeout;
pub struct SomeStruct<T> { uart: T }
impl<T> SomeStruct<T> where T: MutBlockingRxWithTimeout {
pub fn new(uart: T) -> SomeStruct<T> {
SomeStruct { uart: uart }
}
pub fn read_response(&mut self, timeout: &<T as MutBlockingRxWithTimeout>::Timeout) -> Result<bool, <T as MutBlockingRxWithTimeout>::Error> {
let mut buffer = [0u8; 3];
// If we got an error, we don't care any many we actually received.
let len = self.uart.gets_wait(&mut buffer, timeout).map_err(|e| e.1)?;
// process data in buffer here
Ok(len == buffer.len())
}
}
In this example, we read 16 octets from a non-blocking serial port into a
vector which grows to contain exactly as much as we have read so far. You
would call the read_data
function until it returned Ok(true)
. This differs
from the other examples in that we have an immutable reference to our UART
instead of owning it.
use embedded_serial::ImmutNonBlockingRx;
struct SomeStruct<'a, T> where T: 'a {
buffer: Vec<u8>,
uart: &'a T
};
const CHUNK_SIZE: usize = 4;
const WANTED: usize = 16;
impl<'a, T> SomeStruct<'a, T> where T: ImmutNonBlockingRx {
fn new(uart: &T) -> SomeStruct<T> {
SomeStruct { uart: uart, buffer: Vec::new() }
}
fn read_data(&mut self) -> Result<bool, <T as ImmutNonBlockingRx>::Error> {
let mut buffer = [0u8; CHUNK_SIZE];
if self.buffer.len() < WANTED {
let needed = WANTED - self.buffer.len();
let this_time = if needed < CHUNK_SIZE { needed } else { CHUNK_SIZE };
match self.uart.gets_try(&mut buffer[0..needed]) {
// Read some or more of the data
Ok(read) => {
self.buffer.extend(&buffer[0..read]);
Ok(self.buffer.len() == WANTED)
}
// Sent some of the data but errored out
Err((read, e)) => {
self.buffer.extend(&buffer[0..read]);
Err(e)
}
}
} else {
Ok(true)
}
}
}
Re-exports§
pub use MutBlockingTx as BlockingTx;
pub use MutBlockingTxWithTimeout as BlockingTxWithTimeout;
pub use MutNonBlockingTx as NonBlockingTx;
pub use MutBlockingRx as BlockingRx;
pub use MutBlockingRxWithTimeout as BlockingRxWithTimeout;
pub use MutNonBlockingRx as NonBlockingRx;
Traits§
- Implementors of this trait offer octet based serial data reception using a blocking API and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data reception using a blocking API with an upper bound on blocking time, and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data transmission using a blocking API and only requiring an immutable reference to self.
- Implementors of this trait offer octet based serial data transmission using a blocking API with an upper bound on blocking time, and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data reception using a non-blocking API, and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data transmission using a non-blocking API and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data reception using a blocking API and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data reception using a blocking API with an upper bound on blocking time, and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data transmission using a blocking API and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data transmission using a blocking API with an upper bound on blocking time, and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data reception using a non-blocking API, and requiring a mutable reference to self.
- Implementors of this trait offer octet based serial data transmission using a non-blocking API and requiring a mutable reference to self.