repository·master·Indexed 25 days ago
https://github.com/rust-embedded/embedded-halA collection of Hardware Abstraction Layer (HAL) traits for the Rust embedded ecosystem, enabling platform-agnostic drivers. The ecosystem includes crates for different execution models: embedded-hal (blocking), embedded-hal-async (async/await), embedded-hal-nb (polling), embedded-hal-bus (SPI/I2C bus sharing), embedded-can (CAN bus), and embedded-io/embedded-io-async for byte-oriented I/O streams.
embedded-hal provides a Hardware Abstraction Layer (HAL) for embedded systems, serving as a foundation for platform-agnostic drivers.
By writing drivers using embedded-hal traits, driver authors can support multiple target platforms (e.g., Cortex-M, AVR, embedded Linux). Application developers can then use these drivers on any platform that implements the required embedded-hal traits.
The transition from embedded-hal 0.2.x to 1.0.0 represents a fundamental shift in purpose. While 0.2.x attempted to both standardize HAL APIs and provide traits for generic drivers, 1.0.0 focuses exclusively on providing traits for writing generic drivers that work on any HAL.
Key implications for developers:
embedded-hal-nb provides non-blocking versions of certain embedded-hal traits. It utilizes the nb crate to implement non-blocking patterns, making it suitable for embedded systems where operations might not be immediately ready. It shares the same scope and design goals as the core embedded-hal crate.The embedded-io-adapters crate provides structs that wrap an I/O stream to implement different families of I/O traits. This allows you to bridge the gap between embedded-io/embedded-io-async and other common I/O ecosystems.
Instead of separate adapters for Read, ReadBuf, or Write, a single adapter struct implements the appropriate traits based on the capabilities of the wrapped inner type. This enables seamless usage when working with trait combinations like Read + Write.
embedded-can provides a generic abstraction layer for Controller Area Network (CAN) interfaces in embedded Rust. It defines traits that allow hardware abstraction layers (HALs) to implement CAN driver functionality, enabling drivers for CAN peripherals to be written generically and used across different microcontrollers.embedded-hal-async provides asynchronous versions of the embedded-hal traits. It is designed for embedded systems requiring non-blocking hardware access. It shares the same scope and design goals as the standard embedded-hal crate.The embedded-io crate provides I/O traits for no_std embedded systems where std::io is unavailable due to its reliance on allocation (e.g., std::io::Error).
Key differences include:
Error is an associated type rather than a fixed type. This allows implementors to return custom error types without using dyn or Box, following the embedded-hal pattern.std::io where Read/Write can be blocking or non-blocking based on runtime state, embedded-io's Read and Write traits are always blocking. For non-blocking operations, use the ReadReady and WriteReady traits.The embedded-hal ecosystem follows a specific policy regarding Minimum Supported Rust Version (MSRV) upgrades. This policy ensures that patch releases remain stable for existing users, while major and minor releases may introduce higher MSRV requirements.
Upgrade Rules:
_._.*Z*): The MSRV will not be updated. Patch releases are guaranteed to maintain compatibility with the existing MSRV.*X*.*Y*._): The MSRV may be upgraded.-alpha): The MSRV may be upgraded as part of preparation for a final release.This policy applies to both 0.x.x and >=1.x.x versions.
Recommendation for users with strict MSRV requirements:
If your project requires a specific Rust version and cannot accommodate MSRV upgrades, you should pin the dependency version in your Cargo.toml to a specific version rather than using version ranges.
In embedded-hal 1.0, SPI traits are split into SpiBus (the raw bus with SCK, MOSI, MISO) and SpiDevice (a single device on a bus managed by a CS pin).
SpiBus.SpiDevice.SpiBus and SpiDevice on the same struct.SpiDevice. Do not take the CS pin as a separate OutputPin; SpiDevice manages it for you.SpiBus.SpiBus.If your HAL provides SpiBus but your driver requires SpiDevice, wrap the bus using embedded_hal_bus::spi::ExclusiveDevice along with a CS pin.
use embedded_hal_bus::spi::{ExclusiveDevice, NoDelay};
// Create the SPI from the HAL. This implements SpiBus, not SpiDevice!
let spi_bus = my_hal::spi::Spi::new(...);
// Create the CS. This must implement OutputPin.
let cs = my_hal::gpio::Output::new(...);
// Combine the SPI bus and the CS pin into a SPI device. This now does implement SpiDevice!
let spi_device = ExclusiveDevice::new(spi_bus, cs, NoDelay);
// Now you can create your driver with it!
let driver = my_driver::Driver::new(spi_device, ...);To share a single SPI bus among multiple devices, use the mechanisms provided by embedded-hal-bus to connect an SpiBus (representing the physical bus) to multiple SpiDevice instances (representing individual devices on that bus).
Important for Driver Authors: Device drivers should use the SpiDevice traits rather than SpiBus traits whenever possible. This ensures compatibility with bus-sharing adapters and allows multiple devices to coexist on the same hardware bus.
embedded-hal v1.0 has been released. If you are currently using version 0.2, you should consult the official migration guide to update your code to the new API.embedded-hal-compat crate. It provides shims to allow (generally) seamless interoperability between embedded-hal v0.2 and v1.0 without requiring manual code alterations.