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 dma defmt async undoc-features
samd11d	samd11d dma defmt async undoc-features
samd21g	samd21g usb dma defmt async undoc-features
samd21j	samd21j usb dma defmt async undoc-features
samd51g	samd51g usb sdmmc dma defmt async undoc-features
samd51j	samd51j usb sdmmc dma defmt async undoc-features
samd51n	samd51n usb sdmmc dma defmt async undoc-features
samd51p	samd51p usb sdmmc dma defmt async undoc-features

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.

PAC docs	crates.io	Provided BSPs
atsamd11c		Bare atsamd11*
atsamd21e		Gemma M0, Serpente, Trinket M0, Neo Trinkey, NeoKey Trinkey, QT Py
atsamd21g		Arduino Nano 33 IOT, Circuit Playground Express, Feather M0*, ItsyBitsy M0, Metro M0*, MKR1000, MKR Vidor 4000, MKR ZERO, P1AM-100, SAMD21 Mini, SODAQ ONE, Wio Lite MG126, Wio Lite W600, Xiao M0
atsamd21j		SODAQ SARA AFF
atsamd51g		ItsyBitsy M4, Trellis M4
atsamd51j		EdgeBadge, Feather M4*, Metro M4*, PyGamer*, PyPortal, Matrix Portal M4
atsame51n
atsamd51p		Grand Central M4 Express, Wio Terminal
atsame51g
atsame51j
atsame51n
atsame53j
atsame53n
atsame54n
atsame54p		PathfinderZA Proto1, SAM E54 Xplained Pro Evaluation Kit*

* 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
• ADC

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:

1. Create a new Cargo package for the firmware cargo new my_firmware, cd my_firmware
2. Copy the BSP example source file cp feather_m0/examples/blinky_basic.rs src/main.rs
3. Copy Cargo config and memory layout cp -R feather_m0/.cargo feather_m0/memory.x .
4. Add the BSP and any other required dependencies to Cargo.toml:

[dependencies]
feather_m0 = "0.13"
panic-halt = "0.2"

5. cargo build should create an ELF in target/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

Undocumented chip features

Some development board manufacturers, such as Adafruit, sell some boards with pin multiplexing configurations that aren't explicitly allowed by the datasheet. As a convenience, we offer the option to enable these undocumented features by opting into the undoc-features Cargo feature. Note that even though these have shown to work in at least some situations, we do not provide any guarantees with respect to those.

Currently, we provide these features undocumented features:

SAMD21:

• Mark PA00 as I2C-capable according to circuit_playground_express.

• Mark PA01 as I2C-capable according to circuit_playground_express.

• Mark PB02 as I2C-capable according to circuit_playground_express.

• Mark PB03 as I2C-capable according to circuit_playground_express.

SAMx5x devices:

• UndocIoSet1: Implement an undocumented IoSet for PA16, PA17, PB22 & PB23 configured for Sercom1. The pygamer & feather_m4 use this combination, but it is not listed as valid in the datasheet.

• UndocIoSet2: Implement an undocumented IoSet for PA00, PA01, PB22 & PB23 configured for Sercom1. The itsybitsy_m4 uses this combination, but it is not listed as valid in the datasheet.

• Mark PB02 as I2C-capable according to metro_m4.

• Mark PB03 as I2C-capable according to metro_m4.

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.