embedded-hal
implementations for AVR microcontrollers. Based on the register definitions from avr-device
.
You need a nightly Rust compiler for compiling Rust code for AVR. Note: Due to a regression, versions after nightly-2021-01-07
are currently broken (see #124). Please use that version of the compiler for now. You can install it using
rustup toolchain install nightly-2021-01-07
Go into ./boards/arduino-leonardo
(or the directory for whatever board you want), and run the following commands:
cd boards/arduino-leonardo
# Now you are ready to build your first avr blink example!
cargo +nightly-2021-01-07 build --example leonardo-blink
# For some boards, you can even run it directly (this will attempt to flash it
# onto a connected board):
cargo +nightly-2021-01-07 run --example leonardo-blink
# For others, you can find the binary file in
ls ../../target/avr-atmega32u4/debug/examples/leonardo-blink.elf
# and e.g. create an ihex file using
avr-objcopy -S -j .text -j .data -O ihex leonardo-blink.elf leonardo-blink.hex
This is a step-by-step guide for creating a new project targeting Arduino Leonardo (ATmega32U4
). You can of course apply the same steps for any other microcontroller.
-
Start by creating a new project:
cargo new --bin avr-example cd avr-example
-
If you're using rustup, you probably want to set an override for this directory, to use the nightly toolchain:
rustup override set nightly
-
Copy the target description for your MCU (e.g.
avr-atmega32u4.json
) into your project. -
Create a file
.cargo/config.toml
with the following content:[build] target = "avr-atmega32u4.json" [unstable] build-std = ["core"]
-
Fill
Cargo.toml
with these additional directives:[dependencies] # A panic handler is needed. This is a crate with the most basic one. # The `leonardo-panic` example shows a more elaborate version. panic-halt = "0.2.0" [dependencies.arduino-leonardo] git = "https://github.com/Rahix/avr-hal" rev = "<insert latest git-commit hash here>" # ^- Pin the dependency to a specific version. You should use the latest # commit hash from the avr-hal master branch. You can find it here: # # https://github.com/Rahix/avr-hal/commits/master # Configure the build for minimal size [profile.dev] panic = "abort" lto = true opt-level = "s" [profile.release] panic = "abort" codegen-units = 1 debug = true lto = true opt-level = "s"
Note: If you at some point want to update to a newer version of
avr-hal
, you just need to put a later commit hash into therev =
field. For any breaking changes which might require you to fix something in your code, read the CHANGELOG. -
Start your project with this basic template:
#![no_std] #![no_main] // Pull in the panic handler from panic-halt extern crate panic_halt; use arduino_leonardo::prelude::*; #[arduino_leonardo::entry] fn main() -> ! { let dp = arduino_leonardo::Peripherals::take().unwrap(); unimplemented!() }
-
Build with these commands (make sure you're using nightly rust!):
cargo build # or cargo build --release
and find your binary in
target/avr-atmega32u4/debug/
(ortarget/avr-atmega32u4/release
). -
(Optional): To make development as smooth as possible, you can configure a cargo runner for your board. This repository contains a few example scripts (e.g.
leonardo-runner.sh
,uno-runner.sh
) which you can copy into your project. You'll then need to add the following section to your.cargo/config.toml
:[target.'cfg(target_arch = "avr")'] runner = "./leonardo-runner.sh"
And that's it, now you can build an run your project in a single command!
cargo run # or cargo run --release
This repository contains the following components:
- A generic crate containing implementations that can be used chip-independently and macros to create chip-dependent instances of peripheral abstractions. This crate is named
avr-hal-generic
. - HAL crates for each MCU in
chips/
. These make use ofavr-hal-generic
to create chip-specific definitions. - Board Support Crates for popular hardware in
boards/
. They, for the most part, just re-export functionality from the chip-HAL, with the names that are printed on the PCB.
The following HAL crates currently exist. Take a look at the docs for more details on what's supported.
atmega168-hal
- Crate Documentation- ADC
- Digital IO
- I2C using
TWI
- PWM
- SPI
- Spinning Delay
- USART Serial
atmega2560-hal
- Crate Documentation- ADC (no differential channels yet)
- Digital IO
- I2C using
TWI
- SPI
- Spinning Delay
- USART Serial
atmega328p-hal
- Crate Documentation- ADC
- Digital IO
- I2C using
TWI
- SPI
- Spinning Delay
- USART Serial
atmega32u4-hal
- Crate Documentation- ADC (no differential channels yet)
- Digital IO
- I2C using
TWI
- SPI
- Spinning Delay
- USART Serial
attiny85-hal
- Crate Documentation- Digital IO
- Spinning Delay
attiny88-hal
- Crate Documentation- Digital IO
- I2C using
TWI
- SPI
- Spinning Delay
In boards/
there are crates for the following hardware. Please note that this project is in no way affiliated with any of the vendors.
Each board crate comes with a few examples showing how to use them. For more details, follow the links to the documentation.
- Arduino diecimila - Crate Documentation
- Arduino Leonardo - Crate Documentation
- Arduino Uno - Crate Documentation
- Arduino Nano (via
arduino-uno
crate) - Crate Documentation - Arduino Mega 2560 - Crate Documentation
- Adafruit Trinket (3V3 or 5V) (not PRO!) - Crate Documentation
- BigAVR 6 - Crate Documentation
This project is not affiliated with either Microchip (former Atmel) nor any of the Vendors that created the boards supported in this repository.
avr-hal 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.