Make digital pin traits fallible

.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)
 

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

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
 }
 

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<bool, Self::Error>;
 
     /// 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<bool, Self::Error>;
 }
 
-/// 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,33 +64,38 @@ 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<bool, Self::Error> {
+///        Ok(!self.state)
 ///    }
-///    fn is_set_high(&self) -> bool {
-///        self.state
+///    fn is_set_high(&self) -> Result<bool, Self::Error> {
+///        Ok(self.state)
 ///    }
 /// }
 ///
 /// /// Opt-in to the software implementation.
 /// 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<bool, Self::Error>;
 
     /// Is the input pin low?
-    fn is_low(&self) -> bool;
+    fn is_low(&self) -> Result<bool, Self::Error>;
 }
+