[RFC] digital::TriStatePin

[japaric]

What the title says. The use case for this is some sort of generic charlieplexing interface / driver / library.

Alternatives

Vanilla

/// A tri-state (low, high, floating) pin
pub trait TriStatePin {
    /// Drives the pin low
    fn set_low(&mut self);

    /// Drives the pin high
    fn set_high(&mut self);

    /// Puts the pin in floating mode
    fn float(&mut self);

    /// Checks if the pin is currently in floating mode
    fn is_floating(&self) -> bool;

    // plus maybe other `is_*` methods
}

Enum based

/// The states of a tri-state pin
enum State { Low, High, Floating }

/// A tri-state (low, high, floating) pin
pub trait TriStatePin {
    /// Changes the state of the pin
    fn set(&mut self, state: State);

    /// Gets the state of the pin
    fn state(&self) -> State;
}

Once we pick an alternative that we are happy with we can land it behind the "unproven" feature gate. Once someone has demonstrated that it works by actually implementing the trait and building some generic library on top of it we can un-feature gate it.

cc @therealprof

[jamesmunns]

I have a library that could use this (dw1000 driver).

I think I like the second alternative better (enum based), though we would need a "get state" (output/input), and "get value" (low or high, could work for input or output).

Nevermind, I see that this isn't meant to cover all states, just "Output with floating". I like the enum based approach even more.

[bachp]

+1 for the enum based variant, it seems easier to comprehend

[EugeneGonzalez]

Enum approach is more pleasing. One concern is the "state" method could be confused for an InputPin read instead of the TriStatePin's set output.

[therealprof]

Whoops, commented on so topics about this very thing that I forgot to raise my voice here. 😉

+1 for enum based, too.

[austinglaser]

I think a way to read the pin's state is critical -- with it, for instance, you could build a portable bit-banged I2C implementation on top of a TriStatePin.

What if the API looked something like:

/// The states of a tri-state pin
enum State { Low, High, Floating }

/// A tri-state (low, high, floating) pin
pub trait TriStatePin {
    /// Changes the state of the pin
    fn set(&mut self, state: State);

    /// Gets the output state of the pin
    ///
    /// Queries the state set in `set()`
    fn state(&self) -> State;

    /// Whether the pin is driven high
    ///
    /// Reads the pin's actual electrical state
    fn is_high(&self) -> bool;

    /// Whether the pin is driven low
    ///
    /// Reads the pin's actual electrical state
    fn is_low(&self) -> bool;
}

The other option would be for TriStatePin implementers to also implement InputPin -- does that make more sense from a modularity perspective? It doesn't match what's done with an OutputPin, where the one trait encompasses all pin operations.

[japaric]

@austinglaser TriStatePin does not let you use the pin as an input. State::Low means the output level is low, State::High means that the output level is high, and State::Floating leaves the output floating but you can't read the voltage level when it is in that state.

What you want for a bit banged I2C implementation is the IoPin trait proposed in #29; that trait lets you toggle between the InputPin and OutputPin modes.

---

There seems to be consensus here on the enum based API so feel free to send a PR.

[austinglaser]

@japaric I see what you're going for in principle here. I do think that there needs to be some discussion about reading the state of an output pin, however. Depending on the pin configuration in hardware (consider, for instance, an open-drain output), it can be critical to know the electrical state of a pin that is being "driven" high or low.

[therealprof]

@austinglaser Not every MCU will allow to read back the state of an output pin so you might have to switch modes anyway (or store the state and hope it'll be the current one).

[austinglaser]

@therealprof Indeed... but some do. Maybe the right place isn't in TriStatePin, but there should be some way at the trait level to express that a particular pin can be meaningfully read while in output mode

[thejpster]

trait OutputReadbackPin: OutputPin?

…

On 12 Mar 2018 17:03, "austinglaser" ***@***.***> wrote: @therealprof <https://github.com/therealprof> Indeed... but some do. Maybe the right place isn't in TriStatePin, but there should be some way at the trait level to express that a particular pin can be meaningfully read while in output mode — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#31 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA6lj4CJRyWaA3ZH_SX5fAtQjGaykV2Dks5tdqpDgaJpZM4RlcvK> .

[austinglaser]

That's a compelling idea. My first thought, though, is: "how do you read back something like a TriState pin?" Do you have a separate impl TriStateReadbackPin: TriStatePin trait? This would cause an explosion of Readback traits, for each possible type of output

What about a trait just called ReadbackPin, so you can express a trait bound such as OutputPin + ReadbackPin or TrStatePin + ReadbackPin?

[austinglaser]

Although that's starting to look a lot like (exactly like?) an InputPin -- maybe it's more of an implementation level thing, which encourages (where possible) the implementation of InputPin for OutputPins. Then, the trait bound looks like OutputPin + InputPin or TriStatePin + InputPin

[thejpster]

Not sure I agree. An InputPin must be in input mode, while we're taking about readback which is checking which mode an output pin was most recently placed in (and perhaps therefore offering a toggle API). If we give these two traits the same function names, we'll have to use UFCS which is not that obvious, so I'd suggest the traits have different functions.

…

On 12 Mar 2018 17:27, "austinglaser" ***@***.***> wrote: Although that's starting to look a lot like (exactly like?) an InputPin -- maybe it's more of an implementation level thing, which encourages (where possible) the implementation of InputPin for OutputPins. Then, the trait bound looks like OutputPin + InputPin or TriStatePin + InputPin — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#31 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA6ljzdRWuBVw1OQskuCbdgCg92Bwkbxks5tdrAMgaJpZM4RlcvK> .

[austinglaser]

What I've been talking about is actually reading the electrical state of an output pin. For cases where that makes sense (as I've said before, one such example is a pin configured in open-drain output mode), the implementation of InputPin could be the identical trait -- not a different one with the same name. I agree wholeheartedly that that would be a bad idea.