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)
        }
    }
}