/avr-hal

embedded-hal abstractions for AVR microcontrollers

Primary LanguageRustApache License 2.0Apache-2.0

avr-hal Continuous Integration arduino-hal docs atmega-hal docs attiny-hal docs

Hardware Abstraction Layer for AVR microcontrollers and common boards (for example Arduino). Based on the avr-device crate.

This is a new version of avr-hal! Older versions can be found in the old branch but will no longer get support.

Quickstart

You need a nightly Rust compiler for compiling Rust code for AVR. The correct version will be installed automatically due to the rust-toolchain.toml file.

Install dependencies:

  • Ubuntu 
    sudo apt install avr-libc gcc-avr pkg-config avrdude
  • Macos 
    xcode-select --install # if you haven't already done so
brew tap osx-cross/avr
brew install avr-gcc avrdude

Next, install "ravedude", a tool which seamlessly integrates flashing your board into the usual cargo workflow:

cargo +stable install ravedude

Go into ./examples/arduino-uno (or the directory for whatever board you want), and run the following commands:

cd examples/arduino-uno

# Build and run it on a connected board
cargo run --bin uno-blink

Starting your own project

The best way to start your own project is via the avr-hal-template which you can easily use with cargo-generate:

cargo install cargo-generate
cargo generate --git https://github.com/Rahix/avr-hal-template.git

Repository Structure

The avr-hal repository is a workspace containing all components making up the HAL. Here is an overview:

arduino-hal arduino-hal docs

arduino-hal is the batteries-included HAL for all Arduino & similar boards. This is what you probably want to use for your projects. It is intentionally built to abstract away the differences between boards as much as possible.

examples/*

The examples directory contains lots of examples for common hardware. Do note that not all examples were ported to all boards, but there is a good chance that you can still use the code. Currently, the Arduino Uno crate contains the most examples.

mcu/atmega-hal atmega-hal docs , mcu/attiny-hal attiny-hal docs

HAL crates for AVR microcontroller families. If you have a custom board, you'll want to work with these crates. Please check their documentation for a list of supported MCUs.

avr-hal-generic avr-hal-generic docs

This is a generic crate containing most of the HAL implementaions in the form of macros which are instanciated in each HAL crate for the specific MCUs. If you intend to write drivers that work with any AVR chip, targeting avr-hal-generic is probably the best route.

avr-specs/

The avr-specs/ directory contains rustc target definitions for all supported microcontrollers. You will need these for compiling rust code for AVR. The avr-hal-template already includes them for convenience.

ravedude crates.io page

ravedude is a utility for seamlessly integrating avrdude and a serial console into the cargo workflow. With a bit of configuration (check its README!) you can then upload your code to your board and view its output over the serial console by just using cargo run as you would normally.

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.

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.