|
| 1 | +# `embedded-hal` |
| 2 | + |
| 3 | +> A Hardware Abstraction Layer (HAL) for embedded systems |
| 4 | +
|
| 5 | +This project is developed and maintained by the [HAL team][https://github.com/rust-embedded/wg#the-hal-team]. |
| 6 | + |
| 7 | +## Scope |
| 8 | + |
| 9 | +`embedded-hal` serves as a foundation for building an ecosystem of platform agnostic drivers. |
| 10 | +(driver meaning library crates that let a target platform interface an external device like a digital |
| 11 | +sensor or a wireless transceiver). |
| 12 | + |
| 13 | +The advantage of this system is that by writing the driver as a generic library on top |
| 14 | +of `embedded-hal` driver authors can support any number of target |
| 15 | +platforms (e.g. Cortex-M microcontrollers, AVR microcontrollers, embedded Linux, etc.). |
| 16 | + |
| 17 | +The advantage for application developers is that by adopting `embedded-hal` they can unlock all |
| 18 | +these drivers for their platform. |
| 19 | + |
| 20 | +For functionality that goes beyond what is provided by `embedded-hal`, users are encouraged |
| 21 | +to use the target platform directly. Abstractions of common functionality can be proposed to be |
| 22 | +included into `embedded-hal` as described [in this guide](docs/how-to-add-a-new-trait.md), though. |
| 23 | + |
| 24 | +See more about the design goals in [this documentation section](https://docs.rs/embedded-hal/latest/embedded_hal/#design-goals). |
| 25 | + |
| 26 | +## Crates |
| 27 | + |
| 28 | +The main `embedded-hal` project is not tied to a specific execution model like blocking or non-blocking. |
| 29 | + |
| 30 | +| Crate | crates.io | Docs | | |
| 31 | +|-|-|-|-| |
| 32 | +| [embedded-hal](./embedded-hal) | [](https://crates.io/crates/embedded-hal) | [](https://docs.rs/embedded-hal) | Core traits, blocking version | |
| 33 | +| [embedded-hal-async](./embedded-hal-async) | [](https://crates.io/crates/embedded-hal-async) | [](https://docs.rs/embedded-hal-async) | Core traits, async version | |
| 34 | +| [embedded-hal-nb](./embedded-hal-nb) | [](https://crates.io/crates/embedded-hal-nb) | [](https://docs.rs/embedded-hal-nb) | Core traits, polling version using the `nb` crate | |
| 35 | +| [embedded-hal-bus](./embedded-hal-bus) | [](https://crates.io/crates/embedded-hal-bus) | [](https://docs.rs/embedded-hal-bus) | Utilities for sharing SPI and I2C buses | |
| 36 | +| [embedded-can](./embedded-can) | [](https://crates.io/crates/embedded-can) | [](https://docs.rs/embedded-can) | Controller Area Network (CAN) traits | |
| 37 | + |
| 38 | +## Releases |
| 39 | + |
| 40 | +At the moment we are working towards a `1.0.0` release (see [#177]). During this process we will |
| 41 | +release alpha versions like `1.0.0-alpha.1` and `1.0.0-alpha.2`. |
| 42 | +Alpha releases are **not guaranteed** to be compatible with each other. |
| 43 | +They are provided as early previews for community testing and preparation for the final release. |
| 44 | +If you use an alpha release, we recommend you choose an exact version specification in your |
| 45 | +`Cargo.toml` like: `embedded-hal = "=1.0.0-alpha.8"` |
| 46 | + |
| 47 | +See [this guide](docs/version-policy.md) for a way to implement both an `embedded-hal` `0.2.x` |
| 48 | +version and an `-alpha` version side by side in a HAL. |
| 49 | + |
| 50 | +[#177]: https://github.com/rust-embedded/embedded-hal/issues/177 |
| 51 | + |
| 52 | +## Documents |
| 53 | + |
| 54 | +- [How-to: add a new trait](docs/how-to-add-a-new-trait.md) |
| 55 | +- [Version policy](docs/version-policy.md) |
| 56 | +- [MSRV](docs/msrv.md) |
| 57 | + |
| 58 | +## Implementations and drivers |
| 59 | + |
| 60 | +For a non-exhaustive list of `embedded-hal` implementations and driver crates check the |
| 61 | +[awesome-embedded-rust] list. |
| 62 | + |
| 63 | +You may be able to find even more HAL implementation crates and driver crates by searching for the |
| 64 | +[`embedded-hal-impl`], [`embedded-hal-driver`] and [`embedded-hal`][embedded-hal-kw] keywords |
| 65 | +on crates.io. |
| 66 | + |
| 67 | +[`embedded-hal-impl`]: https://crates.io/keywords/embedded-hal-impl |
| 68 | +[`embedded-hal-driver`]: https://crates.io/keywords/embedded-hal-driver |
| 69 | +[embedded-hal-kw]: https://crates.io/keywords/embedded-hal |
| 70 | + |
| 71 | +[awesome-embedded-rust]: https://github.com/rust-embedded/awesome-embedded-rust#driver-crates |
| 72 | + |
| 73 | +## Minimum Supported Rust Version (MSRV) |
| 74 | + |
| 75 | +This crate is guaranteed to compile on stable Rust 1.54 and up. It *might* |
| 76 | +compile with older versions but that may change in any new patch release. |
| 77 | + |
| 78 | +See [here](docs/msrv.md) for details on how the MSRV may be upgraded. |
| 79 | + |
| 80 | +## License |
| 81 | + |
| 82 | +Licensed under either of |
| 83 | + |
| 84 | +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or |
| 85 | + http://www.apache.org/licenses/LICENSE-2.0) |
| 86 | +- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) |
| 87 | + |
| 88 | +at your option. |
| 89 | + |
| 90 | +### Contribution |
| 91 | + |
| 92 | +Unless you explicitly state otherwise, any contribution intentionally submitted |
| 93 | +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be |
| 94 | +dual licensed as above, without any additional terms or conditions. |
| 95 | + |
| 96 | +## Code of Conduct |
| 97 | + |
| 98 | +Contribution to this repository is organized under the terms of the [Rust Code of |
| 99 | +Conduct](CODE_OF_CONDUCT.md), the maintainers of this repository, the [HAL team](https://github.com/rust-embedded/wg#the-hal-team), promise |
| 100 | +to intervene to uphold that code of conduct. |
0 commit comments