docs: Add README.md and comment example

Set cargo version back to 0.1.0 for first release

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "dht-sensor"
-version = "0.2.0"
+version = "0.1.0"
 description = "Driver for the DHT11/DHT22 sensor based on embedded-hal"
 authors = ["Michael Beaumont <[email protected]>"]
 keywords = ["embedded", "sensor", "humidity", "temperature", "embedded-hal-driver", "dht11", "dht22"]

README.md

@@ -0,0 +1,15 @@
+# DHT11/DHT22 sensor driver
+
+This library provides a platform-agnostic driver for the [DHT11 and DHT22](https://learn.adafruit.com/dht/overview) sensors.
+
+Use one of two functions `dht11::Reading::read` and `dht22::Reading::read` to get a reading.
+
+## Usage
+
+The only prerequisites are an embedded-hal implementation that provides:
+
+- `Delay`-implementing type, for example Cortex-M microcontrollers typically use the `SysTick`.
+- `InputOutputPin`-implementing type, for example an `Output<OpenDrain>` from `stm32f0xx_hal`.
+
+See the [stm32f042 example](examples/stm32f042.rs) for a commented example of
+how to use the library.

examples/stm32f042.rs

@@ -14,12 +14,18 @@ fn main() -> ! {
     let mut p = stm32::Peripherals::take().unwrap();
     let cp = stm32::CorePeripherals::take().unwrap();
     let mut rcc = p.RCC.configure().sysclk(8.mhz()).freeze(&mut p.FLASH);
+
+    // This is used by `dht-sensor` to wait for signals
     let mut delay = delay::Delay::new(cp.SYST, &rcc);
+
+    // This could be any `gpio` port
     let gpio::gpioa::Parts { pa1, .. } = p.GPIOA.split(&mut rcc);
 
+    // The DHT11 datasheet suggests 1 second
     hprintln!("Waiting on the sensor...").unwrap();
     delay.delay_ms(1000_u16);
 
+    // An `Output<OpenDrain>` is both `InputPin` and `OutputPin`
     let mut pa1 = cortex_m::interrupt::free(|cs| pa1.into_open_drain_output(cs));
 
     match dht11::Reading::read(&mut delay, &mut pa1) {

src/lib.rs

@@ -1,3 +1,67 @@
+//! # DHT11/DHT22 sensor driver
+//!
+//! This library provides a platform-agnostic driver for the [DHT11 and DHT22](https://learn.adafruit.com/dht/overview) sensors.
+//!
+//! Use one of two functions [`dht11::Reading::read`] and [`dht22::Reading::read`] to get a reading.
+//!
+//! [`dht11::Reading::read`]: dht11/struct.Reading.html#method.read
+//! [`dht22::Reading::read`]: dht22/struct.Reading.html#method.read
+//!
+//! ## Usage
+//!
+//! The only prerequisites are an embedded-hal implementation that provides:
+//!
+//! - [`Delay`]-implementing type, for example Cortex-M microcontrollers typically use the `SysTick`.
+//! - [`InputOutputPin`]-implementing type, for example an `Output<OpenDrain>` from `stm32f0xx_hal`.
+//!
+//!
+//! ## Example
+//!
+//! See the [stm32f042 example](https://github.com/michaelbeaumont/dht-sensor/blob/master/examples/stm32f042.rs) for a working example of
+//! how to use the library.
+//!
+//! ```
+//! #![no_std]
+//! #![no_main]
+//!
+//! use crate::hal::{delay, gpio, prelude::*, stm32};
+//! use cortex_m_rt::entry;
+//! use cortex_m_semihosting::hprintln;
+//! use panic_halt as _;
+//! use stm32f0xx_hal as hal;
+//!
+//! use dht_sensor::*;
+//!
+//! #[entry]
+//! fn main() -> ! {
+//!     let mut p = stm32::Peripherals::take().unwrap();
+//!     let cp = stm32::CorePeripherals::take().unwrap();
+//!     let mut rcc = p.RCC.configure().sysclk(8.mhz()).freeze(&mut p.FLASH);
+//!
+//!     // This is used by `dht-sensor` to wait for signals
+//!     let mut delay = delay::Delay::new(cp.SYST, &rcc);
+//!
+//!     // This could be any `gpio` port
+//!     let gpio::gpioa::Parts { pa1, .. } = p.GPIOA.split(&mut rcc);
+//!
+//!     // The DHT11 datasheet suggests 1 second
+//!     hprintln!("Waiting on the sensor...").unwrap();
+//!     delay.delay_ms(1000_u16);
+//!
+//!     // An `Output<OpenDrain>` is both `InputPin` and `OutputPin`
+//!     let mut pa1 = cortex_m::interrupt::free(|cs| pa1.into_open_drain_output(cs));
+//!
+//!     match dht11::Reading::read(&mut delay, &mut pa1) {
+//!         Ok(dht11::Reading {
+//!             temperature,
+//!             relative_humidity,
+//!         }) => hprintln!("{}°, {}% RH", temperature, relative_humidity).unwrap(),
+//!         Err(e) => hprintln!("Error {:?}", e).unwrap(),
+//!     }
+//!     hprintln!("Looping forever now, thanks!").unwrap();
+//!
+//!     loop {}
+//! }
 #![no_std]
 
 mod read;