Skip to content

Commit 8c73e4d

Browse files
eldruineldruin
authored
Merge pull request #476 from rust-embedded/io-docs2
Update some readmes.
2 parents 2c71ed6 + 7921e82 commit 8c73e4d

File tree

4 files changed

+86
-80
lines changed

4 files changed

+86
-80
lines changed

‎README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ The main `embedded-hal` project is not tied to a specific execution model like
3434
| [embedded-hal-nb](./embedded-hal-nb) | [![crates.io](https://img.shields.io/crates/v/embedded-hal-nb.svg)](https://crates.io/crates/embedded-hal-nb) | [![Documentation](https://docs.rs/embedded-hal-nb/badge.svg)](https://docs.rs/embedded-hal-nb) | Core traits, polling version using the `nb` crate |
3535
| [embedded-hal-bus](./embedded-hal-bus) | [![crates.io](https://img.shields.io/crates/v/embedded-hal-bus.svg)](https://crates.io/crates/embedded-hal-bus) | [![Documentation](https://docs.rs/embedded-hal-bus/badge.svg)](https://docs.rs/embedded-hal-bus) | Utilities for sharing SPI and I2C buses |
3636
| [embedded-can](./embedded-can) | [![crates.io](https://img.shields.io/crates/v/embedded-can.svg)](https://crates.io/crates/embedded-can) | [![Documentation](https://docs.rs/embedded-can/badge.svg)](https://docs.rs/embedded-can) | Controller Area Network (CAN) traits |
37+
| [embedded-io](./embedded-io) | [![crates.io](https://img.shields.io/crates/v/embedded-io.svg)](https://crates.io/crates/embedded-io) | [![Documentation](https://docs.rs/embedded-io/badge.svg)](https://docs.rs/embedded-io) | I/O traits (read, write, seek, etc.), blocking and nonblocking version. |
38+
| [embedded-io-async](./embedded-io-async) | [![crates.io](https://img.shields.io/crates/v/embedded-io-async.svg)](https://crates.io/crates/embedded-io-async) | [![Documentation](https://docs.rs/embedded-io-async/badge.svg)](https://docs.rs/embedded-io-async) | I/O traits, async version |
39+
| [embedded-io-adapters](./embedded-io-adapters) | [![crates.io](https://img.shields.io/crates/v/embedded-io-adapters.svg)](https://crates.io/crates/embedded-io-adapters) | [![Documentation](https://docs.rs/embedded-io-adapters/badge.svg)](https://docs.rs/embedded-io-adapters) | Adapters between the [`embedded-io`](https://crates.io/crates/embedded-io) and [`embedded-io-async`](https://crates.io/crates/embedded-io-async) traits and other IO traits (`std`, `tokio`, `futures`...) |
3740

3841
## Releases
3942

‎embedded-hal-async/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,13 @@ This crate contains asynchronous versions of the [`embedded-hal`](https://crates
1010

1111
This project is developed and maintained by the [HAL team](https://github.com/rust-embedded/wg#the-hal-team).
1212

13+
## Serial/UART traits
14+
15+
There is no serial traits in `embedded-hal-async`. Instead, use [`embedded-io-async`](https://crates.io/crates/embedded-io).
16+
A serial port is essentially a byte-oriented stream, and that's what `embedded-io-async` models. Sharing the traits
17+
with all byte streams has some advantages. For example, it allows generic code providing a command-line interface
18+
or a console to operate either on hardware serial ports or on virtual ones like Telnet or USB CDC-ACM.
19+
1320
## Minimum Supported Rust Version (MSRV)
1421

1522
This crate requires Rust nightly newer than `nightly-2022-11-22`, due to requiring support for

‎embedded-hal/README.md

Lines changed: 75 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,80 @@
99
1010
This project is developed and maintained by the [HAL team](https://github.com/rust-embedded/wg#the-hal-team).
1111

12-
## [API reference]
12+
**NOTE** This HAL is still is active development. Expect the traits presented here to be
13+
tweaked, split or be replaced wholesale before being stabilized, i.e. before hitting the 1.0.0
14+
release.
1315

14-
[API reference]: https://docs.rs/embedded-hal
16+
**NOTE** If you want to use an alpha release of the 1.0.0 version, use an exact version
17+
specifier in your `Cargo.toml` like: `embedded-hal = "=1.0.0-alpha.2"`.
18+
19+
## Companion crates
20+
21+
The main `embedded-hal` crate contains only blocking traits, where the operation is done
22+
synchronously before returning. Check out the following crates, which contain versions
23+
of the traits for other execution models:
24+
25+
- [`embedded-hal-async`](https://docs.rs/embedded-hal-async): async/await-based.
26+
- [`embedded-hal-nb`](https://docs.rs/embedded-hal-nb): polling-based, using the `nb` crate.
27+
28+
The [`embedded-hal-bus`](https://docs.rs/embedded-hal-bus) crate provides utilities for sharing
29+
SPI and I2C buses.
30+
31+
Additionally, more domain-specific traits are available in separate crates:
32+
- [`embedded-can`](https://docs.rs/embedded-can): Controller Area Network (CAN)
33+
34+
## Design goals
35+
36+
The HAL
37+
38+
- Must *erase* device specific details. Neither register, register blocks or magic values should
39+
appear in the API.
40+
41+
- Must be generic *within* a device and *across* devices. The API to use a serial interface must
42+
be the same regardless of whether the implementation uses the USART1 or UART4 peripheral of a
43+
device or the UART0 peripheral of another device.
44+
45+
- Where possible must *not* be tied to a specific asynchronous model. The API should be usable
46+
in blocking mode, with the `futures` model, with an async/await model or with a callback model.
47+
(cf. the [`nb`](https://docs.rs/nb) crate)
48+
49+
- Must be minimal, and thus easy to implement and zero cost, yet highly composable. People that
50+
want higher level abstraction should *prefer to use this HAL* rather than *re-implement*
51+
register manipulation code.
52+
53+
- Serve as a foundation for building an ecosystem of platform agnostic drivers. Here driver
54+
means a library crate that lets a target platform interface an external device like a digital
55+
sensor or a wireless transceiver. The advantage of this system is that by writing the driver as
56+
a generic library on top of `embedded-hal` driver authors can support any number of target
57+
platforms (e.g. Cortex-M microcontrollers, AVR microcontrollers, embedded Linux, etc.). The
58+
advantage for application developers is that by adopting `embedded-hal` they can unlock all
59+
these drivers for their platform.
60+
61+
- Trait methods must be fallible so that they can be used in any possible situation.
62+
Nevertheless, HAL implementations can additionally provide infallible versions of the same methods
63+
if they can never fail in their platform. This way, generic code can use the fallible abstractions
64+
provided here but platform-specific code can avoid fallibility-related boilerplate if possible.
65+
66+
## Out of scope
67+
68+
- Initialization and configuration stuff like "ensure this serial interface and that SPI
69+
interface are not using the same pins". The HAL will focus on *doing I/O*.
70+
71+
## Platform agnostic drivers
72+
73+
You can find platform agnostic drivers built on top of `embedded-hal` on crates.io by [searching
74+
for the *embedded-hal* keyword](https://crates.io/keywords/embedded-hal).
75+
76+
If you are writing a platform agnostic driver yourself you are highly encouraged to [add the
77+
embedded-hal keyword](https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata)
78+
to your crate before publishing it!
79+
80+
## Serial/UART traits
81+
82+
There is no serial traits in `embedded-hal`. Instead, use [`embedded-io`](https://crates.io/crates/embedded-io).
83+
A serial port is essentially a byte-oriented stream, and that's what `embedded-io` models. Sharing the traits
84+
with all byte streams has some advantages. For example, it allows generic code providing a command-line interface
85+
or a console to operate either on hardware serial ports or on virtual ones like Telnet or USB CDC-ACM.
1586

1687
## Minimum Supported Rust Version (MSRV)
1788

@@ -25,8 +96,8 @@ See [here](../docs/msrv.md) for details on how the MSRV may be upgraded.
2596
Licensed under either of
2697

2798
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
28-
http://www.apache.org/licenses/LICENSE-2.0)
29-
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
99+
<http://www.apache.org/licenses/LICENSE-2.0>)
100+
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
30101

31102
at your option.
32103

‎embedded-hal/src/lib.rs

Lines changed: 1 addition & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,4 @@
1-
//! A Hardware Abstraction Layer (HAL) for embedded systems
2-
//!
3-
//! **NOTE** This HAL is still is active development. Expect the traits presented here to be
4-
//! tweaked, split or be replaced wholesale before being stabilized, i.e. before hitting the 1.0.0
5-
//! release.
6-
//!
7-
//! **NOTE** If you want to use an alpha release of the 1.0.0 version, use an exact version
8-
//! specifier in your `Cargo.toml` like: `embedded-hal = "=1.0.0-alpha.2"`.
9-
//!
10-
//! # Companion crates
11-
//!
12-
//! The main `embedded-hal` crate contains only blocking traits, where the operation is done
13-
//! synchronously before returning. Check out the following crates, which contain versions
14-
//! of the traits for other execution models:
15-
//!
16-
//! - [`embedded-hal-async`](https://docs.rs/embedded-hal-async): async/await-based.
17-
//! - [`embedded-hal-nb`](https://docs.rs/embedded-hal-nb): polling-based, using the `nb` crate.
18-
//!
19-
//! The [`embedded-hal-bus`](https://docs.rs/embedded-hal-bus) crate provides utilities for sharing
20-
//! SPI and I2C buses.
21-
//!
22-
//! Additionally, more domain-specific traits are available in separate crates:
23-
//! - [`embedded-can`](https://docs.rs/embedded-can): Controller Area Network (CAN)
24-
//!
25-
//! # Design goals
26-
//!
27-
//! The HAL
28-
//!
29-
//! - Must *erase* device specific details. Neither register, register blocks or magic values should
30-
//! appear in the API.
31-
//!
32-
//! - Must be generic *within* a device and *across* devices. The API to use a serial interface must
33-
//! be the same regardless of whether the implementation uses the USART1 or UART4 peripheral of a
34-
//! device or the UART0 peripheral of another device.
35-
//!
36-
//! - Where possible must *not* be tied to a specific asynchronous model. The API should be usable
37-
//! in blocking mode, with the `futures` model, with an async/await model or with a callback model.
38-
//! (cf. the [`nb`](https://docs.rs/nb) crate)
39-
//!
40-
//! - Must be minimal, and thus easy to implement and zero cost, yet highly composable. People that
41-
//! want higher level abstraction should *prefer to use this HAL* rather than *re-implement*
42-
//! register manipulation code.
43-
//!
44-
//! - Serve as a foundation for building an ecosystem of platform agnostic drivers. Here driver
45-
//! means a library crate that lets a target platform interface an external device like a digital
46-
//! sensor or a wireless transceiver. The advantage of this system is that by writing the driver as
47-
//! a generic library on top of `embedded-hal` driver authors can support any number of target
48-
//! platforms (e.g. Cortex-M microcontrollers, AVR microcontrollers, embedded Linux, etc.). The
49-
//! advantage for application developers is that by adopting `embedded-hal` they can unlock all
50-
//! these drivers for their platform.
51-
//!
52-
//! - Trait methods must be fallible so that they can be used in any possible situation.
53-
//! Nevertheless, HAL implementations can additionally provide infallible versions of the same methods
54-
//! if they can never fail in their platform. This way, generic code can use the fallible abstractions
55-
//! provided here but platform-specific code can avoid fallibility-related boilerplate if possible.
56-
//!
57-
//! # Out of scope
58-
//!
59-
//! - Initialization and configuration stuff like "ensure this serial interface and that SPI
60-
//! interface are not using the same pins". The HAL will focus on *doing I/O*.
61-
//!
62-
//! # Reference implementation
63-
//!
64-
//! The [`stm32f1xx-hal`] crate contains a reference implementation of this HAL.
65-
//!
66-
//! [`stm32f1xx-hal`]: https://crates.io/crates/stm32f1xx-hal
67-
//!
68-
//! # Platform agnostic drivers
69-
//!
70-
//! You can find platform agnostic drivers built on top of `embedded-hal` on crates.io by [searching
71-
//! for the *embedded-hal* keyword](https://crates.io/keywords/embedded-hal).
72-
//!
73-
//! If you are writing a platform agnostic driver yourself you are highly encouraged to [add the
74-
//! embedded-hal keyword](https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata)
75-
//! to your crate before publishing it!
76-
1+
#![doc = include_str!("../README.md")]
772
#![warn(missing_docs)]
783
#![no_std]
794

0 commit comments

Comments
 (0)