hermes_five/
lib.rs

1#![doc(html_root_url = "https://docs.rs/hermes-five/0.1.0")]
2
3//! <h1 align="center">HERMES-FIVE - The Rust Robotics & IoT Platform</h1>
4//! <div style="text-align:center;font-style:italic;">Hermes-Five is an open-source IoT and Robotics programming framework - written in Rust.</div>
5//! <br/>
6//! <img height="0" style="float:right;height:200px!important;" alt="Schema sample of blinking led using Arduino UNO" src="https://github.com/dclause/hermes-five/blob/develop/docs/public/examples/led/led-blink.gif?raw=true" />
7//!
8//! # Documentation
9//!
10//! This is the API documentation.<br/>
11//! To read more detailed explanations, visit the [user documentation](https://dclause.github.io/hermes-five).<br/>
12//! To see the code in action, visit the [examples](https://github.com/dclause/hermes-five/tree/develop/hermes-five/examples) directory.
13//!
14//! # Features
15//!
16//! **Hermes-Five** is a Rust library designed to "remotely" control Arduino (or compatible) boards as well as all types
17//! of input/output devices (led, servo, button, sensors, etc.) connected to it.<br/>
18//! It can be compared to _[Johnny-Five](https://johnny-five.io/)_ in the javascript ecosystem.
19//!
20//! - Define remotely controllable [`Board`](hardware::Board) (Arduino currently)
21//! - Control boards though an [`IoProtocol`](io::IoProtocol) connection ([`Serial`](io::Serial) for the moment)
22//! - Remote control all types of [`Device`](devices::Device)s such as [`Output`](devices::Output)s (LED, servo, etc.) or [`Input`](devices::Input)s (button, switch, sensors,
23//! - etc.) individually
24//! - Create and play [`Animation`](animations::Animation) with auto-interpolate movements
25//!
26//! **_If you wish to do the same with absolutely no code via a nice-and-shiny interface, please consult the [Hermes-Studio](https://github.com/dclause/hermes-studio) project._**
27//!
28//! # Prerequisites
29//!
30//! - To run the [examples](https://github.com/dclause/hermes-five/tree/develop/hermes-five/examples) provided, you will at least an Arduino board attached via the serial port of your computer (or the machine running your code).<br/>
31//! - [StandardFirmataPlus.ino](https://github.com/firmata/arduino/blob/main/examples/StandardFirmataPlus/StandardFirmataPlus.ino) Arduino sketch **MUST** be installed on the board.
32//!   _This code is available by default in Arduino IDE under the Firmata samples sketch menu._
33//!   _Uploading the sketch to the board needs to be done once only._
34//!
35//! # Getting Started
36//!
37//! - Install the compatible [Firmata Protocol client](https://github.com/firmata/arduino/blob/main/examples/StandardFirmataPlus/StandardFirmataPlus.ino) on your Arduino board.
38//!
39//! - Add the following to your `Cargo.toml`:
40//! ```toml
41//! [dependencies]
42//! hermes-five = "0.1.0"
43//! ```
44//!
45//! - Start writing your HERMES code: see the [examples](https://github.com/dclause/hermes-five/tree/develop/hermes-five/examples) directory for more examples.
46//!
47//! The following code demonstrates the simplest program we could imagine: blink the Arduino embedded led on pin 13.
48//! ```rust
49//! use hermes_five::hardware::{Board, BoardEvent};
50//! use hermes_five::devices::Led;
51//!
52//! #[hermes_five::runtime]
53//! async fn main() {
54//!
55//!     // Register a new board.
56//!     // (of type arduino + auto-detected serial port by default)
57//!     let board = Board::run();
58//!
59//!     // When board communication is ready:
60//!     board.on(BoardEvent::OnReady, |board: Board| async move {
61//!
62//!         // Register a LED on pin 13 (arduino embedded led).
63//!         // Pin: 13; OFF by default
64//!         let mut led = Led::new(&board, 13, false)?;
65//!
66//!         // Blinks the LED every 500ms: indefinitely.
67//!         led.blink(500);
68//!
69//!         Ok(())
70//!     });
71//! }
72//! ```
73//!
74//! # Feature flags
75//!
76//! - **libudev** -- (enabled by default) Activates `serialport` crate _libudev_ feature under-the-hood (required on Linux only for port listing).
77//! - **serde** -- Enables serialize/deserialize capabilities for most entities.
78//! - **mock** -- Provides mocked entities of all kinds (useful for tests mostly).
79
80#[cfg(test)]
81extern crate self as hermes_five;
82
83pub mod animations;
84pub mod devices;
85pub mod errors;
86pub mod hardware;
87pub mod io;
88#[cfg(any(test, feature = "mocks"))]
89pub mod mocks;
90pub mod utils;
91
92pub use hermes_five_macros::runtime;
hermes_five/lib.rs

hermes_five/
lib.rs
