diff --git a/.travis.yml b/.travis.yml index a7cc51a5f..90b163985 100644 --- a/.travis.yml +++ b/.travis.yml @@ -2,18 +2,18 @@ language: rust matrix: include: - - env: TARGET=x86_64-unknown-linux-gnu + - env: TARGET=x86_64-unknown-linux-gnu FEATURES=unproven if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master) - - env: TARGET=thumbv6m-none-eabi + - env: TARGET=thumbv6m-none-eabi FEATURES=unproven rust: beta if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master) - - env: TARGET=thumbv7m-none-eabi + - env: TARGET=thumbv7m-none-eabi FEATURES=unproven rust: beta if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master) - - env: TARGET=x86_64-unknown-linux-gnu + - env: TARGET=x86_64-unknown-linux-gnu FEATURES=unproven rust: nightly if: (branch = staging OR branch = trying) OR (type = pull_request AND branch = master) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d7abb561..865e32f50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## [Unreleased] +### Changed + +- [breaking-change] The digital `OutputPin`, `StatefulOutputPin`, `ToggleableOutputPin` + and `InputPin` traits have been replaced with fallible versions. + The methods now return a `Result` type as setting an output pin + and reading an input pin could potentially fail. + See [here](https://github.com/rust-embedded/embedded-hal/issues/95) for more info. + ## [v0.2.1] - 2018-05-14 ### Changed diff --git a/ci/script.sh b/ci/script.sh index 12c05e27b..982b90045 100644 --- a/ci/script.sh +++ b/ci/script.sh @@ -2,10 +2,10 @@ set -euxo pipefail main() { cargo check --target $TARGET - cargo check --target $TARGET --features unproven + cargo check --target $TARGET --features $FEATURES if [ $TRAVIS_RUST_VERSION = nightly ]; then - cargo test --target $TARGET --features unproven + cargo test --target $TARGET --features $FEATURES fi } diff --git a/src/digital.rs b/src/digital.rs index 8f49da3d9..37ff60ce0 100644 --- a/src/digital.rs +++ b/src/digital.rs @@ -1,37 +1,40 @@ -//! Digital I/O +//! Digital I/O. -/// Single digital push-pull output pin +/// Single digital push-pull output pin. pub trait OutputPin { + /// Error type + type Error; + /// Drives the pin low /// /// *NOTE* the actual electrical state of the pin may not actually be low, e.g. due to external /// electrical sources - fn set_low(&mut self); + fn set_low(&mut self) -> Result<(), Self::Error>; /// Drives the pin high /// /// *NOTE* the actual electrical state of the pin may not actually be high, e.g. due to external /// electrical sources - fn set_high(&mut self); + fn set_high(&mut self) -> Result<(), Self::Error>; } /// Push-pull output pin that can read its output state /// /// *This trait is available if embedded-hal is built with the `"unproven"` feature.* #[cfg(feature = "unproven")] -pub trait StatefulOutputPin { +pub trait StatefulOutputPin : OutputPin { /// Is the pin in drive high mode? /// /// *NOTE* this does *not* read the electrical state of the pin - fn is_set_high(&self) -> bool; + fn is_set_high(&self) -> Result; /// Is the pin in drive low mode? /// /// *NOTE* this does *not* read the electrical state of the pin - fn is_set_low(&self) -> bool; + fn is_set_low(&self) -> Result; } -/// Output pin that can be toggled +/// Output pin that can be toggled. /// /// *This trait is available if embedded-hal is built with the `"unproven"` feature.* /// @@ -41,8 +44,11 @@ pub trait StatefulOutputPin { /// implemented. Otherwise, implement this using hardware mechanisms. #[cfg(feature = "unproven")] pub trait ToggleableOutputPin { + /// Error type + type Error; + /// Toggle pin output. - fn toggle(&mut self); + fn toggle(&mut self) -> Result<(), Self::Error>; } /// If you can read **and** write the output state, a pin is @@ -58,20 +64,24 @@ pub trait ToggleableOutputPin { /// } /// /// impl OutputPin for MyPin { -/// fn set_low(&mut self) { +/// type Error = void::Void; +/// +/// fn set_low(&mut self) -> Result<(), Self::Error> { /// self.state = false; +/// Ok(()) /// } -/// fn set_high(&mut self) { +/// fn set_high(&mut self) -> Result<(), Self::Error> { /// self.state = true; +/// Ok(()) /// } /// } /// /// impl StatefulOutputPin for MyPin { -/// fn is_set_low(&self) -> bool { -/// !self.state +/// fn is_set_low(&self) -> Result { +/// Ok(!self.state) /// } -/// fn is_set_high(&self) -> bool { -/// self.state +/// fn is_set_high(&self) -> Result { +/// Ok(self.state) /// } /// } /// @@ -79,12 +89,13 @@ pub trait ToggleableOutputPin { /// impl toggleable::Default for MyPin {} /// /// let mut pin = MyPin { state: false }; -/// pin.toggle(); -/// assert!(pin.is_set_high()); -/// pin.toggle(); -/// assert!(pin.is_set_low()); +/// pin.toggle().unwrap(); +/// assert!(pin.is_set_high().unwrap()); +/// pin.toggle().unwrap(); +/// assert!(pin.is_set_low().unwrap()); /// ``` #[cfg(feature = "unproven")] +#[allow(deprecated)] pub mod toggleable { use super::{OutputPin, StatefulOutputPin, ToggleableOutputPin}; @@ -97,25 +108,31 @@ pub mod toggleable { where P: Default, { + type Error = P::Error; + /// Toggle pin output - fn toggle(&mut self) { - if self.is_set_low() { - self.set_high(); + fn toggle(&mut self) -> Result<(), Self::Error> { + if self.is_set_low()? { + self.set_high() } else { - self.set_low(); + self.set_low() } } } } -/// Single digital input pin +/// Single digital input pin. /// /// *This trait is available if embedded-hal is built with the `"unproven"` feature.* #[cfg(feature = "unproven")] pub trait InputPin { + /// Error type + type Error; + /// Is the input pin high? - fn is_high(&self) -> bool; + fn is_high(&self) -> Result; /// Is the input pin low? - fn is_low(&self) -> bool; + fn is_low(&self) -> Result; } +