Awesome
atsamd & atsame support for Rust
This repository holds various crates that support/enable working with Microchip (nee Atmel) samd11, samd21, samd51 and same5x based devices using Rust.
HAL - Hardware Abstraction Layer
The Hardware Abstraction Layer (HAL - 
) crate encodes a type-safe layer over the raw PACs. This crate implements traits specified by the embedded-hal project, making it compatible with various drivers in the embedded Rust ecosystem. Cargo features are used to enable support for specific hardware variations and features. Online documentation for commonly-used feature sets is provided:
| Chip family | Documented features |
|---|---|
| samd11c | samd11c |
| samd11d | samd11d |
| samd21g | samd21g usb |
| samd21j | samd21j usb |
| samd51g | samd51g usb |
| samd51j | samd51j usb |
| samd51n | samd51n usb |
| samd51p | samd51p usb |
PAC and BSP - Peripheral Access Crate and Board Support Package
The Peripheral Access Crates (PACs) are automatically generated from Microchip SVD files, and provide low-level access to the peripherals specified by a device's SVD file.
Board Support Packages (BSPs) are provided for popular development boards, which rename pins to match silk screens or Arduino pin assignments, add helpers for initialization, and re-export the atsamd-hal crate. The BSPs included in atsamd-rs are separated in to two tiers: Tier 1 BSPs use the latest version of atsamd-hal, Tier 2 BSPs use a specific version of atsamd-hal that is not necessarily the latest.
* Tier 1 BSP
async APIs
atsamd_hal provides APIs for using async/await constructs with some of its peripherals. To enable async support, use the async Cargo feature.
Detailed documentation is provided in the atsamd_hal::async_hal module. The metro_m4 and
feather_m0 feature complete examples showing how to use async APIs.
Please note that you must bring your own executor runtime such as embassy-executor or rtic to be able to
use the async APIs.
Supported peripherals
- SPI
- I2C
- USART
- DMAC
- EIC (GPIO interrupts)
- Timers
Examples
The BSPs include examples to quickly get up and running with the board. Building the examples requires changing directory into one of the board support package directories, and some examples will require additional features:
$ cd boards/metro_m0
$ cargo build --examples --features="usb"
A new firmware can be made from one of the examples:
- Create a new Cargo package for the firmware
cargo new my_firmware,cd my_firmware - Copy the BSP example source file
cp feather_m0/examples/blinky_basic.rs src/main.rs - Copy Cargo config and memory layout
cp -R feather_m0/.cargo feather_m0/memory.x . - Add the BSP and any other required dependencies to
Cargo.toml:
[dependencies]
feather_m0 = "0.13"
panic-halt = "0.2"
cargo buildshould create an ELF intarget/thumbv6m-none-eabi/debug/my_firmware
Building
You'll need to add the proper compilation target prior to building:
$ # for samd11, samd21:
$ rustup target add thumbv6m-none-eabi
$ # for samd51, same51, same53, same54:
$ rustup target add thumbv7em-none-eabihf
CI
If you'd like to build all the same things that the CI would build but on your local system, you can run:
$ ./build-all.py
Running and debugging firmware on target hardware
See our wiki page about loading code onto the device.
Adding a new board
See our wiki page about adding a new board.
License
The included SVD files are sourced from http://packs.download.atmel.com/ and are licensed under the Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0).
The remainder of the code is 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.