3 releases (breaking)
Uses old Rust 2015
0.5.0 | Feb 1, 2017 |
---|---|
0.4.0 | Jan 29, 2017 |
0.3.0 | Nov 19, 2016 |
#44 in #uart
Used in 2 crates
26KB
208 lines
Embedded Serial Traits
Introduction
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.
There are variants of the traits for Receive and Transmit, and for blocking, blocking with timeout and non-blocking.
Unanswered Questions
- Would it be better if the different traits used the same function names?
lib.rs
:
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)
}
}
}