port: Add methods to temporarily switch a pin to a different mode

[Rahix]

This allows temporarily making an output pin an input and vice versa:

let mut pin = pins.d0.into_output();

pin.with_pin_as_floating_input(|p| {
    // p is input here
    p.is_high();
});

Similarly:

• pin.with_pin_as_pull_up_input()
• pin.with_pin_as_output()
• pin.with_pin_as_output_high()

TODO

• Deduplicate implementation.
• Check that all invariants are upheld and pin-state is always returned to what it was before.
• Investigate whether we want the pin to be in the same state, or just the same mode - an alternative API could be one where a correct pin must be returned from the closure again:

  let pin = pins.d0.into_output();
  assert!(pin.is_set_low())
  pin.with_temporary(|p| {
    let p = p.into_floating_input();
    // ...
    p.into_output_high()
  })
  assert!(pin.is_set_high())

[Rahix]

FWIW, other HALs have come up with a very similar API. For example: https://docs.rs/stm32f4xx-hal/0.11.1/stm32f4xx_hal/gpio/struct.Pin.html#method.with_floating_input

[mutantbob]

I wonder how this would behave if the pin were currently being used as the CS for an SPI transaction.

[Rahix]

Well, the CS pin must be managed manually anyway so you can do weird stuff in any case... I don't think this changeset here would make it worse than it already is, or am I missing something?

[haennes]

Hello,
I really need this for my project.
Is there any way I can help?
Should I fork it and then open a new PR?

[Rahix]

@haennes, giving me some feedback and testing this PR here is all I need. I just held off merging it because I wanted to hear from users first. Maybe you can comment on some of the open questions from the OP? What would be best for your usecase?

[haennes]

It works on an Arduino Nano (from Elegoo) (Atmega m328p).
I will test it on an Arduino Uno R3 (from Elegoo) (Atmega 328p) too.
Although the 2nd implementations seems better at a first glance, the way it currently is is quite perfect, as it removes a lot of boilerplate code in the users project.

[Rahix]

This implementation is still quite ugly and not 100% sound either. I quite like the approach in stm32f4xx-hal: https://docs.rs/stm32f4xx-hal/0.11.1/src/stm32f4xx_hal/gpio/convert.rs.html#476-490

This is at least more sound than my hack. So I'll try to reimplement that pattern here.

[Rahix]

Source: https://github.com/stm32-rs/stm32h7xx-hal/blob/21d9c06a57169e92cf5745e582dca171c73294c9/src/gpio/convert.rs

It looks like this will unfortunately require a larger change to make it work. But I think following that route is still a good idea and will improve the remainder of the port module as well. Will just need a bit more time...

[hiszd]

Am I correct in saying that implementing the IoPin trait from embedded-hal would take care of this as well?
https://docs.rs/embedded-hal/latest/embedded_hal/digital/v2/trait.IoPin.html

[Rahix]

@hiszd, not really. IoPin moves the pin to change its state more permanently while the methods in this PR only change the pin state for the duration of a closure.

[RenjiSann]

Hi,

I just finished implementing a driver for the DHT11 sensor on an Elegoo Arduino Uno R3.
I had to use a pull up pin with temporary output mode to send the data request signal, and I can attest that it worked without any problem.

This might need a little refactoring before it is anywhere close to presentable, but it could eventually be integrated into the examples someday.

[jaqx0r]

With regards to the final bullet in the first comment, I think the user should not be responsible for returning a valid pin from the closure. We should assume the with* function takes care of maintaining state and correctness. I think that also makes it easier to return a pin's value from the closure in the case the pin was made input.

Is there a difference between changing mode with into_output_high() and calling set_high() on a low output? I think there isn't so a user can change state if they need after calling this closure with no return control.

[Rahix]

With regards to the final bullet in the first comment, I think the user should not be responsible for returning a valid pin from the closure. We should assume the with* function takes care of maintaining state and correctness. I think that also makes it easier to return a pin's value from the closure in the case the pin was made input.

If we switch to the design from stm32-hal I linked above, this can be done. The pin is only passed to the closure by (mutable) reference so there is no way the closure can move the pin to the outside world and break invariants.

I agree that a user-controller closure return type makes for a much nicer API.

Is there a difference between changing mode with into_output_high() and calling set_high() on a low output? I think there isn't so a user can change state if they need after calling this closure with no return control.

Yes, there is a difference. Calling into_output() and then set_high() leads to a brief glitch on the pin where it's state is LOW for a short time. In some applications, this can trip up external components. into_output_high() switches from high-impedance input mode to HIGH output without any glitches.