/avr-hal

embedded-hal abstractions for AVR microcontrollers

Primary LanguageRustApache License 2.0Apache-2.0

avr-hal Build Status

embedded-hal implementations for AVR microcontrollers. Based on the register definitions from avr-device.

Quickstart

You need nightly rust for compiling rust code for AVR. Go into ./boards/arduino-leonardo (or the directory for whatever board you want), and run the following commands:

# Now you are ready to build your first avr blink example!
cargo +nightly 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 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

Starting your own project

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.

  1. Start by creating a new project:

    cargo new --bin avr-example
cd avr-example

  2. If you're using rustup, you probably want to set an override for this directory, to use the nightly toolchain:

    rustup override set nightly

  3. Copy the target description for your MCU (e.g. avr-atmega32u4.json) into your project.

  4. Create a file .cargo/config.toml with the following content:

    [build]
target = "avr-atmega32u4.json"

[unstable]
build-std = ["core"]

  5. 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"

# 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"

  6. 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!()
}

  7. 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/ (or target/avr-atmega32u4/release).

  8. (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

Repository Structure

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 of avr-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.

Supported MCUs

The following HAL crates currently exist. Take a look at the docs for more details on what's supported.

Supported Boards

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.

Disclaimer

This project is not affiliated with either Microchip (former Atmel) nor any of the Vendors that created the boards supported in this repository.

License

avr-hal is licensed under either of

at your option.