How do I write a custom avr-hal for atmega32u4 devices?

[mainrs]

I am trying to write a hal for the arduboy. Since the device uses an atmega32u4, I wanted to base my implementation on the arduino uno crate.

But it seems that atmega-hal is not published. Is there any way to use the crate?

[Rahix]

Yeah, unfortunately we haven't published to crates.io yet (#59). In the meantime, you can just use a git-dependency on atmega-hal like this:

[dependencies.atmega-hal]
git = "https://github.com/rahix/avr-hal"
rev = "4cbb163deddac1651ce3374c8d91dbe7b7bb63ff"
features = ["rt", "atmega32u4"]

[Rahix]

And for the arduboy crate structure, you can take the arduino-hal as inspiration. Especially for the pin-renaming macro, etc.

[mainrs]

Thank you!

[mainrs]

I do have a follow-up question:

I am specifically trying to port this library to Rust. However, some pin/port definitions are not available:
https://github.com/MLXXXp/Arduboy2/blob/ca1c3ae024414174acd0b3e8df5c53c2803d1295/src/Arduboy2Core.h#L40-L119

The chip used is the atmega32u4, for which I linked the pins below.

avr-hal/mcu/atmega-hal/src/port.rs

Lines 76 to 114 in eeef51b

	#[cfg(feature = "atmega32u4")]
	avr_hal_generic::impl_port_traditional! {
	enum Ports {
	PORTB: (crate::pac::PORTB, portb, pinb, ddrb),
	PORTC: (crate::pac::PORTC, portc, pinc, ddrc),
	PORTD: (crate::pac::PORTD, portd, pind, ddrd),
	PORTE: (crate::pac::PORTE, porte, pine, ddre),
	PORTF: (crate::pac::PORTF, portf, pinf, ddrf),
	}
	pub struct Pins {
	pb0: PB0 = (crate::pac::PORTB, PORTB, 0, portb, pinb, ddrb),
	pb1: PB1 = (crate::pac::PORTB, PORTB, 1, portb, pinb, ddrb),
	pb2: PB2 = (crate::pac::PORTB, PORTB, 2, portb, pinb, ddrb),
	pb3: PB3 = (crate::pac::PORTB, PORTB, 3, portb, pinb, ddrb),
	pb4: PB4 = (crate::pac::PORTB, PORTB, 4, portb, pinb, ddrb),
	pb5: PB5 = (crate::pac::PORTB, PORTB, 5, portb, pinb, ddrb),
	pb6: PB6 = (crate::pac::PORTB, PORTB, 6, portb, pinb, ddrb),
	pb7: PB7 = (crate::pac::PORTB, PORTB, 7, portb, pinb, ddrb),
	pc6: PC6 = (crate::pac::PORTC, PORTC, 6, portc, pinc, ddrc),
	pc7: PC7 = (crate::pac::PORTC, PORTC, 7, portc, pinc, ddrc),
	pd0: PD0 = (crate::pac::PORTD, PORTD, 0, portd, pind, ddrd),
	pd1: PD1 = (crate::pac::PORTD, PORTD, 1, portd, pind, ddrd),
	pd2: PD2 = (crate::pac::PORTD, PORTD, 2, portd, pind, ddrd),
	pd3: PD3 = (crate::pac::PORTD, PORTD, 3, portd, pind, ddrd),
	pd4: PD4 = (crate::pac::PORTD, PORTD, 4, portd, pind, ddrd),
	pd5: PD5 = (crate::pac::PORTD, PORTD, 5, portd, pind, ddrd),
	pd6: PD6 = (crate::pac::PORTD, PORTD, 6, portd, pind, ddrd),
	pd7: PD7 = (crate::pac::PORTD, PORTD, 7, portd, pind, ddrd),
	pe2: PE2 = (crate::pac::PORTE, PORTE, 2, porte, pine, ddre),
	pe6: PE6 = (crate::pac::PORTE, PORTE, 6, porte, pine, ddre),
	pf0: PF0 = (crate::pac::PORTF, PORTF, 0, portf, pinf, ddrf),
	pf1: PF1 = (crate::pac::PORTF, PORTF, 1, portf, pinf, ddrf),
	pf4: PF4 = (crate::pac::PORTF, PORTF, 4, portf, pinf, ddrf),
	pf5: PF5 = (crate::pac::PORTF, PORTF, 5, portf, pinf, ddrf),
	pf6: PF6 = (crate::pac::PORTF, PORTF, 6, portf, pinf, ddrf),
	pf7: PF7 = (crate::pac::PORTF, PORTF, 7, portf, pinf, ddrf),
	}
	}

Examples for missing pins are DDRx and PORTB5 for example. These are used in the linked library, for example here:
https://github.com/MLXXXp/Arduboy2/blob/ca1c3ae024414174acd0b3e8df5c53c2803d1295/src/Arduboy2Core.h#L107-L108

[Rahix]

I'm not sure if I understand your question... In AVR C code, you interact with pins very differently than here with avr-hal in Rust. In C, you set a pin as an output by setting the corresponding bit in the DDRx register. With avr-hal, we instead have an abstraction ontop of the raw registers. So the equivalent operation for making a pin an output is

/* Set PB5 as output in C */
DDRB |= PORTB5;

// Set PB5 as output in Rust
pins.pb5.into_output();

(See documentation)

Similarly, PORTB5 is the register bit for setting pin PB5 high or low. In Rust, you'd instead use the set_high() and set_low() methods.

---

As the headers you linked seem to be just configuration, mapping the MCUs pins to pins on the board, maybe this might be interesting for you as well:

There is a macro to create a "board specific" pins struct ontop of the one for the MCU. The MCU-specific one lives in atmega-hal and looks, for example, like this: https://rahix.github.io/avr-hal/atmega_hal/port/struct.Pins.html

You can see how the fields just have the names of the MCUs pins.

Now for your board, you probably want more descriptive names. So you can define a new struct Pins ontop of this one using our macro. This is also done in arduino-hal, for example. Here is the mapping for the Arduino Uno:

avr-hal/arduino-hal/src/port/uno.rs

Lines 4 to 129 in eeef51b

	avr_hal_generic::renamed_pins! {
	type Pin = Pin;
	/// Pins of the **Arduino Uno**.
	///
	/// This struct is best initialized via the [`arduino_hal::pins!()`][pins] macro.
	pub struct Pins from atmega_hal::Pins {
	/// `A0`
	///
	/// * ADC0 (ADC input channel 0)
	/// * PCINT8 (pin change interrupt 8)
	pub a0: atmega_hal::port::PC0 = pc0,
	/// `A1`
	///
	/// * ADC1 (ADC input channel 1)
	/// * PCINT9 (pin change interrupt 9)
	pub a1: atmega_hal::port::PC1 = pc1,
	/// `A2`
	///
	/// * ADC2 (ADC input channel 2)
	/// * PCINT10 (pin change interrupt 10)
	pub a2: atmega_hal::port::PC2 = pc2,
	/// `A3`
	///
	/// * ADC3 (ADC input channel 3)
	/// * PCINT11 (pin change interrupt 11)
	pub a3: atmega_hal::port::PC3 = pc3,
	/// `A4`
	///
	/// * ADC4 (ADC input channel 4)
	/// * SDA (2-wire serial bus data input/output line)
	/// * PCINT12 (pin change interrupt 12)
	pub a4: atmega_hal::port::PC4 = pc4,
	/// `A5`
	///
	/// ADC5 (ADC input channel 5)
	/// SCL (2-wire serial bus clock line)
	/// PCINT13 (pin change interrupt 13)
	pub a5: atmega_hal::port::PC5 = pc5,
	/// `D0` / `RX`
	///
	/// * RXD (USART input pin)
	/// * PCINT16 (pin change interrupt 16)
	pub d0: atmega_hal::port::PD0 = pd0,
	/// `D1` / `TX`
	///
	/// * TXD (USART output pin)
	/// * PCINT17 (pin change interrupt 17)
	pub d1: atmega_hal::port::PD1 = pd1,
	/// `D2`
	///
	/// * INT0 (external interrupt 0 input)
	/// * PCINT18 (pin change interrupt 18)
	pub d2: atmega_hal::port::PD2 = pd2,
	/// `D3`
	///
	/// * **PWM**: [atmega328p_hal::timer::Timer3Pwm]
	/// * INT1 (external interrupt 1 input)
	/// * OC2B (Timer/Counter2 output compare match B output)
	/// * PCINT19 (pin change interrupt 19)
	pub d3: atmega_hal::port::PD3 = pd3,
	/// `D4`
	///
	/// * XCK (USART external clock input/output)
	/// * T0 (Timer/Counter 0 external counter input)
	/// * PCINT20 (pin change interrupt 20)
	pub d4: atmega_hal::port::PD4 = pd4,
	/// `D5`
	///
	/// * **PWM**: [atmega328p_hal::timer::Timer3Pwm]
	/// * T1 (Timer/Counter 1 external counter input)
	/// * OC0B (Timer/Counter0 output compare match B output)
	/// * PCINT21 (pin change interrupt 21)
	pub d5: atmega_hal::port::PD5 = pd5,
	/// `D6`
	///
	/// * **PWM**: [atmega328p_hal::timer::Timer3Pwm]
	/// * AIN0 (analog comparator positive input)
	/// * OC0A (Timer/Counter0 output compare match A output)
	/// * PCINT22 (pin change interrupt 22)
	pub d6: atmega_hal::port::PD6 = pd6,
	/// `D7`
	///
	/// * AIN1 (analog comparator negative input)
	/// * PCINT23 (pin change interrupt 23)
	pub d7: atmega_hal::port::PD7 = pd7,
	/// `D8`
	///
	/// * ICP1 (Timer/Counter1 input capture input)
	/// * CLKO (divided system clock output)
	/// * PCINT0 (pin change interrupt 0)
	pub d8: atmega_hal::port::PB0 = pb0,
	/// `D9`
	///
	/// * **PWM**: [atmega328p_hal::timer::Timer3Pwm]
	/// * OC1A (Timer/Counter1 output compare match A output)
	/// * PCINT1 (pin change interrupt 1)
	pub d9: atmega_hal::port::PB1 = pb1,
	/// `D10`
	///
	/// * **PWM**: [atmega328p_hal::timer::Timer3Pwm]
	/// * SS (SPI bus master slave select)
	/// * OC1B (Timer/Counter1 output compare match B output)
	/// * PCINT2 (pin change interrupt 2)
	pub d10: atmega_hal::port::PB2 = pb2,
	/// `D11`
	///
	/// * **PWM**: [atmega328p_hal::timer::Timer3Pwm]
	/// * MOSI (SPI bus master/slave input)
	/// * OC2A (Timer/Counter2 output compare match A output)
	/// * PCINT3 (pin change interrupt 3)
	pub d11: atmega_hal::port::PB3 = pb3,
	/// `D12`
	///
	/// * MISO (SPI bus master input/slave output)
	/// * PCINT4 (pin change interrupt 4)
	pub d12: atmega_hal::port::PB4 = pb4,
	/// `D13`
	///
	/// * SCK (SPI bus master clock input)
	/// * PCINT5 (pin change interrupt 5)
	/// * L LED on Arduino Uno
	pub d13: atmega_hal::port::PB5 = pb5,
	}
	}

For you, it might look something like this:

pub use atmega_hal::port::mode;
pub use atmega_hal::port::Pin;

avr_hal_generic::renamed_pins! {
    type Pin = Pin;

    pub struct Pins from atmega_hal::Pins {
        /// Display CS
        pub display_cs: atmega_hal::port::PD6 = pd6,
        /// Display D/C
        pub display_dc: atmega_hal::port::PD4 = pd4,
        /// Display reset
        pub display_rst: atmega_hal::port::PD7 = pd7,
        /// red color in the RGB LED
        pub led_red: atmega_hal::port::PB6 = pb6,
        /// green color in the RGB LED
        pub led_green: atmega_hal::port::PB7 = pb7,
        /// blue color in the RGB LED
        pub led_blue: atmega_hal::port::PB5 = pb5,
        // etc.......
    }
}

I hope this is roughtly what you were asking about... If not/or you need more help, just let me know!