23ee5d244d
[RFC] establish a process for adding new traits This PR establish a process for adding new traits. The details can be found in the diff. This PR is also proposing using the `embedded-hal-driver` and `embedded-hal-impl` keywords on crates.io to make implementations of `embedded-hal` and drivers built on top of it more discoverable. Feel free to suggest changes to these proposals in the comments. The PR is also adding a list of (WIP) `embedded-hal` implementations and `embedded-hal` drivers. If your crate is not listed there or if you know of a crate that should be there feel free to send a follow up PR adding it. --- Finally, I'd like to use this chance to call for collaborators that will help me with: - Merging PRs that update the lists in the README - Triaging issues to make sure that they are properly labeled and that they are following the established process. - "Shepherding" proposals / discussions by preventing them from going off topic and by helping them reach a conclusion / consensus, e.g. "Concern $X needs to be addressed before reaching a conclusion", "How would this proposal fulfill use case $Y?", etc. If you'd like to become a collaborator let me know in the comments!
embedded-hal
A Hardware Abstraction Layer (HAL) for embedded systems
API reference
How-to: add a new trait
This is the suggested approach to adding a new trait to embedded-hal
Discussion
Ideally, before proposing a new trait, or set of traits, you should create an issue where the use cases and requirements of the trait(s) are discussed.
These issues will be labeled as discussions in the issue tracker.
Proposing a trait
Once there's consensus on the requirements of the trait(s) a new issue, or a PR, with a proposal should be opened. The proposal should include the actual trait definitions as well as a link to the issue with previous discussion, if there was one.
If the proposal includes more than one alternative then there should be further discussion to try to single out the best alternative.
These issues / PRs will be labeled as proposals in the issue tracker.
Testing period
If there are no objections to the proposal the new trait(s) will land behind the "unproven" Cargo feature and an issue about the new trait(s) will be created. If the proposal includes several alternatives and a single one couldn't be chosen as the best then each alternative will land behind a different Cargo feature, e.g. "alt1" or "alt2".
The traits will undergo a testing period before they move into the set of proven traits. During this period users are encouraged to try to implement the unproven traits for their platforms and to build drivers on top of them. Problems implementing the trait(s) as well as successful implementations should be reported on the corresponding issue.
To leave the unproven state at least two implementations of the trait(s) for different platforms (ideally, the two platforms should be from different vendors) and one generic driver built on top of the trait(s), or alternatively one demo program that exercises the trait (via generic function / trait object), should be demonstrated. If, instead, reports indicate that the proposed trait(s) can't be implemented for a certain platform then the trait(s) will be removed and we'll go back to the drawing board.
Issues used to track unproven APIs will be labeled as unproven-apis in the issue tracker and they
may also include the labels needs-impl and needs-driver to signal what's required for them to
move to the set of proven traits.
Implementations
These are (WIP) implementations of embedded-hal for various platforms. Feel free to send a PR
adding yours to the list!
You may be able to find even more implementations by searching for the embedded-hal-impl keyword
an crates.io. If you publish a embedded-hal implementation to crates.io please use that keyword to
let others more easily find your crate!
Linux
linux-embedded-hal. For the Raspberry Pi and other SBC that expose pins with embedded functionality (SPI, I2C, etc.)
Nordic
NXP
ST Microelectronics
stm32f103xx-hal. Contains examples that can be run on the Blue pill and similar boards.
stm32f30x-hal. Check thef3crate for examples that can be run on the STM32F3DISCOVERY.
Texas Instruments
Drivers
These are (WIP) platform agnostic drivers that can be used with any of the above implementations to interface all sort of external devices like sensors and actuators. Feel free to send a PR adding yours to the list!
You may be able to find even more implementations by searching for the embedded-hal-driver
keyword an crates.io. If you publish a driver to crates.io please use that keyword to let others
more easily find your crate!
l3gd20. Gyroscope
lsm303dlhc. Accelerometer + compass
mag3110. Magnetometer
mfrc522.` RFID reader / writer
motor-driver. Motor drivers like the L298N and the TB6612FNG
mpu9250. Accelerometer + gyroscope + magnetometer IMU
si5351. Clock generator
si7021. Humidity and temperature sensor
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.