Struct Board

pub struct Board { /* private fields */ }

Represents a physical board (Arduino most-likely) where your crate::devices::Device can be attached and controlled through this API. The board gives access to IoData through a communication IoProtocol.

Implementations

impl Board

pub fn run() -> Self

Creates and open a default board (using default protocol).

This method creates a board using the default RemoteIo protocol with Serial transport layer. The port will be auto-detected as the first available serial port matching a board.

Example

use hermes_five::hardware::Board;
use hermes_five::io::RemoteIo;

#[hermes_five::runtime]
async fn main() {
    // Following lines are all equivalent:
    let board = Board::run();
    let board = Board::default().open();
    let board = Board::new(RemoteIo::default()).open();
}

pub fn new<P: IoProtocol + 'static>(protocol: P) -> Self

Creates a board using a given protocol.

Example

use hermes_five::hardware::Board;
use hermes_five::io::RemoteIo;

#[hermes_five::runtime]
async fn main() {
    let board = Board::new(RemoteIo::new("COM4")).open();
}

pub fn open(self) -> Self

Starts a board connexion procedure (using the appropriate configured protocol) in an asynchronous way. Note 1: you probably might not want to call this method yourself and use Self::run() instead. Note 2: after this method, you cannot consider the board to be connected until you receive the “ready” event.

Example

Have a look at the examples/board folder more detailed examples.

use hermes_five::hardware::{Board, BoardEvent};
use hermes_five::io::IO;

#[hermes_five::runtime]
async fn main() {
    let board = Board::run();
    // Is equivalent to:
    let mut board = Board::default().open();

    // Register something to do when the board is connected.
    board.on(BoardEvent::OnReady, |_: Board| async move {
        // Something to do when connected.
        Ok(())
    });
    // code here will be executed right away, before the board is actually connected.
}

pub fn close(self) -> Self

Close a board connexion (using the appropriate configured protocol) in an asynchronous way. Note: after this method, you cannot consider the board to be connected until you receive the “close” event.

Example

Have a look at the examples/board folder more detailed examples.

use hermes_five::pause;
use hermes_five::hardware::{Board, BoardEvent};
use hermes_five::io::IO;

#[hermes_five::runtime]
async fn main() {
    let board = Board::run();
    board.on(BoardEvent::OnReady, |mut board: Board| async move {
        // Something to do when connected.
        pause!(3000);
        board.close();
        Ok(())
    });
    board.on(BoardEvent::OnClose, |_: Board| async move {
        // Something to do when connection closes.
        Ok(())
    });
}

pub fn blocking_open(self) -> Result<Self, Error>

Blocking version of Self::open() method.

pub fn blocking_close(self) -> Result<Self, Error>

Blocking version of Self::close() method.

pub fn on<S, F, T, Fut>(&self, event: S, callback: F) -> EventHandler

where S: Into<String>, T: 'static + Send + Sync + Clone, F: FnMut(T) -> Fut + Send + 'static, Fut: Future<Output = Result<(), Error>> + Send + 'static,

Registers a callback to be executed on a given event.

Available events for a board are defined by the enum: BoardEvent:

• OnRead | ready: Triggered when the board is connected and ready to run.
  The callback must receive the following parameter: |_: Board| { ... }
• OnClose | close: Triggered when the board is disconnected.
  The callback must receive the following parameter: |_: Board| { ... }

Example

use hermes_five::hardware::{Board, BoardEvent};

#[hermes_five::runtime]
async fn main() {
    let board = Board::run();
    board.on(BoardEvent::OnReady, |_: Board| async move {
        // Here, you know the board to be connected and ready to receive data.
        Ok(())
    });
}

Trait Implementations

impl Clone for Board

fn clone(&self) -> Board

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Board

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Board

fn default() -> Self

Default implementation for a board.

This method creates a board using the default RemoteIo protocol with Serial transport layer. The port will be auto-detected as the first available serial port matching a board.

/!\ The board will NOT be connected until the Board::open method is called.

Example

use hermes_five::hardware::Board;
use hermes_five::io::RemoteIo;

#[hermes_five::runtime]
async fn main() {
    // Following lines are all equivalent:
    let board = Board::run();
    let board = Board::default().open();
    let board = Board::new(RemoteIo::default()).open();
}

impl Display for Board

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: IoTransport> From<T> for Board

Creates a board using the given transport layer with the RemoteIo protocol.

Example

use hermes_five::hardware::Board;
use hermes_five::io::RemoteIo;
use hermes_five::io::Serial;

#[hermes_five::runtime]
async fn main() {
    let board = Board::from(Serial::new("/dev/ttyUSB0")).open();
}

fn from(transport: T) -> Self

Converts to this type from the input type.

impl Hardware for Board

fn get_protocol(&self) -> Box<dyn IoProtocol>

Returns the protocol used.

fn set_protocol(&mut self, protocol: Box<dyn IoProtocol>)

Sets the protocol. @todo remove this when hermes_studio finds a way around.

fn get_protocol_name(&self) -> &str

Returns the protocol name.

impl IO for Board

fn get_io(&self) -> &Arc<RwLock<IoData>>

Easy access to hardware through the board.

Example

use hermes_five::hardware::Board;
use hermes_five::hardware::BoardEvent;
use hermes_five::io::IO;

#[hermes_five::runtime]
async fn main() {
    let board = Board::run();
    board.on(BoardEvent::OnReady, |mut board: Board| async move {
        println!("Board connected: {}", board);
        println!("Pins {:#?}", board.get_io().read().pins);
        Ok(())
    });
}

fn is_connected(&self) -> bool

Checks if the communication is opened using the underlying protocol.

fn set_pin_mode(&mut self, pin: u8, mode: PinModeId) -> Result<(), Error>

Sets the mode of the specified pin.

fn digital_write(&mut self, pin: u8, level: bool) -> Result<(), Error>

Writes level to the digital pin.

fn analog_write(&mut self, pin: u8, level: u16) -> Result<(), Error>

Writes level to the analog pin.

fn digital_read(&mut self, _: u8) -> Result<bool, Error>

Reads the digital pin value.

fn analog_read(&mut self, _: u8) -> Result<u16, Error>

Reads the analog pin value.

fn servo_config(&mut self, pin: u8, pwm_range: Range<u16>) -> Result<(), Error>

Sends a SERVO_CONFIG command (0x70 - configure servo) https://github.com/firmata/protocol/blob/master/servos.md

fn i2c_config(&mut self, delay: u16) -> Result<(), Error>

Configures the delay in microseconds for I2C devices that require a delay between when the register is written to and the data in that register can be read.

fn i2c_read(&mut self, address: u8, size: u16) -> Result<(), Error>

Reads size bytes from I2C device at the specified address.

fn i2c_write(&mut self, address: u8, data: &[u16]) -> Result<(), Error>

Writes data to the I2C device at the specified address.