R&D: Investigate using heterogenious lists for ideal resource management workflow

[Ben-PH]

Follow-on from #745

A reference point for these R&D efforts is two-fold:

1. make the barrier-to-entry trivial, similar in spirit to Arduino
2. make esp-rs a highly attractive option for enterprise projects.
3. Minimal internal maintenance burden.

A key factor, is to make sure that #1 can be a staging ground for #2.

A near-first-time maker with zero code experience. Arduino-like simplicity

First, they have a cargo-generateed main:

#![no_std]
#![no_main]


#[entry]
fn main() -> ! {
    let resources = Resources::default_init();
}

...Then they use examples/documentation to create a blinker:

use esp_hal::gpio::{GpioPin, Output, PushPull};


#[initializer(init)]
#[derive(esp_hal::ListBuild)]
struct Blinker {
    blink_pin: GpioPin<Output<PushPull>, 8>
}

impl Blinker {
    // Specified as the initializer by `#[initializer(init)]`
    fn init(&mut self) {
        self.blink_pin.set_low().unwrap()
    }

    fn blink_loop(self, mut delay: Delay) -> ! {
        loop {
            self.blink_pin.toggle().unwrap();
            delay.delay_ms(500u32);
        }
        unreachable!();
    }
}

...and add these lines to main:

let (delay, resources) = Delay::from_list(resources);
let (blinker, _resources) = Blinker::from_list(resources);
blinker.blink_loop(delay);

Single-place specification of pin-usage. Scalable, maintainable, rapid-development

The goal in this context, is to make specifications of pins easy to extend and maintain:

#[pin_spec("pinout.json")]
#[initializer(init)]
#[derive(esp_hal::ListBuild)]
struct SomePeriph<A: InputPin, B: OutputPin> {
    #[pin_spec(A)]
    pin_a: A,
    #[pin_spec(B)]
    pin_b: B,
}

impl<A, B> SomePeriph<A, B> {
    fn init(&mut self) {
        self.pin_b.set_low().unwrap();
    }
}

...and then pinout.json that's in the project-root might look something like this:

{
    "A": {
        "ESP32-S2": 5,
        "ESP32-C3": 7,
        "ESP32-C6": 9
    },
    "B": {
        "ESP32-S2": 6,
        "ESP32-C3": 8,
        "ESP32-C6": 10
    }
}

Current state.

Current efforts are going well. At time of writing, we are close to this example being correct:

// mod/use's here

#[entry]
fn main() -> ! {
    let resources = Resources::default_init();
    let mut delay = unimplemented!("TBD");
    // `list_build` is generated by the list-build derive. it auto-magically takes ownership of the pins, initializes them, and returns the peripheral and updated list of available resources, all ready to go.
    let (mut wheel, _resources) = peripherals::WheelEncoder::list_build(resources);
    loop {
        let scroll = wheel.read_encoder();
        // do something with scroll, then delay
    }
}

...and in a peripheral module:

#[derive(ListBuild)]
struct WheelEncoder {
    #[using(GpioPin<Unknown, 35>)]
    pin_a: GpioPin<Input<PullUp>, 35>,
    #[using(GpioPin<Unknown, 36>)]
    pin_b: GpioPin<Input<PullUp>, 36>,
    #[using(GpioPin<Unknown, 0>)]
    _pin_gnd: GpioPin<Output<PushPull>, 0>,
    value: u8,
    state: bool,
    prev_state: bool,
    scroll_val: i8,
}

(One refinement idea:)

...the WheelEncoderPins below would be specified more like so:

use embedded_hal::digital::v2::{ InputPin, OutputPin };
// Pin resource-and-init declaration
#[init_with(init)]
#[derive(ListBuild)]
struct WheelEncoderPins<I: InputPin, O: OutputPin> {
    #[using(GpioPin<Unknown, 35>)]
    pin_a: I
    #[using(GpioPin<Unknown, 36>)]
    pin_b: I
    #[using(GpioPin<Unknown, 0>)]
    _pin_gnd: O
}

• the init would degrade() so that I's and O's are AnyPin
• there could be a struct that contains the pins-struct

impl WheelEncoder {
    // initialization implementation detail
    fn init(pin_a: GpioPin<Unknown, 35>, pin_b: GpioPin<Unknown, 36>, _pin_gnd: GpioPin<Unknown, 0>, ) {
        let _pin_gnd = _pin_gnd.into_push_pull_output().unwrap();
        _pin_gnd.set_low().unwrap();
        Self {
            pin_a: pin_a.into_pull_up_input().unwrap(),
            pin_b: pin_b.into_pull_up_input().unwrap(),
            _pin_gnd,
            value: 0,
            state: false,
            prev_state: false,
            scroll_val: 0,
        }
    }

    fn read_encoder(
        &mut self,
    ) -> Option<KeyCode> {
        // snip
    }

}

Next steps

Make this kind of API easy to implement

#[entry]
fn main() -> ! {
    let resources = Resources::default_init();
    let (usb, resources): (USB, _) = USB::list_build(resources);
    //...
}

List-of-pin fields:

#[init_with(init)]
#[derive(ListBuild)]
struct KeyboardMatrxPins<I: InputPin, O: OutputPin, const InN: usize, const OutN: usize> {
    #[from(gpio_HList!(3, 4, 5))]
    outs: [I ; InN],
    #[from(gpio_HList!(6, 7, 8))]
    outs: [O ; OutN]
}

Pin-out specification file

As described in an earlier drop-down

[MabezDev]

Closing for the same rationale as #745, thanks again for exploring this space :)