diff --git a/examples/rng-hal/src/main.rs b/examples/rng-hal/src/main.rs
index 175129f..e9c0020 100644
--- a/examples/rng-hal/src/main.rs
+++ b/examples/rng-hal/src/main.rs
@@ -36,7 +36,7 @@ fn main() -> ! {
let mut seed: [u8; 16] = [0; 16];
- /* Read 4 bytes of data from hardware RNG */
+ /* Read 16 bytes of data from hardware RNG */
rng.random(&mut seed);
let rng = Pcg32::from_seed(seed);
diff --git a/microbit-common/src/display/nonblocking/mod.rs b/microbit-common/src/display/nonblocking/mod.rs
index 62b74fa..30c76af 100644
--- a/microbit-common/src/display/nonblocking/mod.rs
+++ b/microbit-common/src/display/nonblocking/mod.rs
@@ -99,26 +99,26 @@
//!
//! Internally types implementing [`Render`](tiny_led_matrix::Render) aren't used directly with the [`Display`];
//! instead they're used to update a [`MicrobitFrame`] instance which is in
-//! turn passed to the `tiny_led_matrix::Display`.
+//! turn passed to the [`tiny_led_matrix::Display`].
//!
-//! A `MicrobitFrame` instance is a 'compiled' representation of a 5×5
+//! A [`MicrobitFrame`] instance is a 'compiled' representation of a 5×5
//! greyscale image, in a form that's more directly usable by the display
//! code.
//!
//! This is exposed in the public API so that you can construct the
-//! `MicrobitFrame` representation in code running at a low priority. Then
+//! [`MicrobitFrame`] representation in code running at a low priority. Then
//! only [`Display::show_frame()`] has to be called in code that can't be
//! interrupted by the display timer.
//!
//! ## Timer integration
//!
//! The [`Display`] expects to control a single timer. It can use the
-//! micro:bit's `TIMER0`, `TIMER1`, or `TIMER2`.
+//! micro:bit's [`TIMER0`](crate::hal::pac::TIMER0), [`TIMER1`](crate::hal::pac::TIMER1), or [`TIMER2`](crate::hal::pac::TIMER2).
//!
//! This uses a 6ms period to light each of the three internal LED rows, so
//! that the entire display is updated every 18ms.
//!
-//! When rendering greyscale images, the `Display` requests extra interrupts
+//! When rendering greyscale images, the [`Display`] requests extra interrupts
//! within each 6ms period. It only requests interrupts for the greyscale
//! levels which are actually required for what's currently being displayed.
//!
@@ -129,7 +129,8 @@
//!
//! ## Usage
//!
-//! Choose a timer to drive the display from (`TIMER0`, `TIMER1`, or `TIMER2`).
+//! Choose a timer to drive the display from [`TIMER0`](crate::hal::pac::TIMER0),
+//! [`TIMER1`](crate::hal::pac::TIMER1), or [`TIMER2`](crate::hal::pac::TIMER2).
//!
//! When your program starts:
//! - create a [`Display`] struct passing the timer and
@@ -139,7 +140,7 @@
//!
//! To change what's displayed; pass an image ([`GreyscaleImage`] or [`BitImage`]) to [`Display::show`].
//!
-//! You can call `show()` at any time, so long as you're not interrupting, or interruptable by,
+//! You can call [`show()`](Display::show) at any time, so long as you're not interrupting, or interruptable by,
//! [`Display::handle_display_event()`].
//!
//! See [`display_rtic`](https://github.com/nrf-rs/microbit/blob/master/examples/display_rtic) or
diff --git a/microbit-common/src/v1/board.rs b/microbit-common/src/v1/board.rs
index 71736b5..9178b30 100644
--- a/microbit-common/src/v1/board.rs
+++ b/microbit-common/src/v1/board.rs
@@ -70,10 +70,70 @@ pub struct Board {
/// nRF51 peripheral: GPIOTE
pub GPIOTE: pac::GPIOTE,
- /// nRF51 peripheral: RADIO
+ /// nRF51 peripheral: RADIO
+ /// Can be used with [`Radio::init()`](`crate::hal::ieee802154::Radio::init()`)
+ /// ```no_run
+ /// # use microbit_common as microbit;
+ /// # use microbit::{
+ /// # Board,
+ /// # hal::Clocks,
+ /// # display::blocking::Display,
+ /// # };
+ /// # use embedded_hal::blocking::delay::DelayMs;
+ /// # use core::ops::Deref;
+ /// use microbit::hal::ieee802154;
+ /// // take the board
+ /// let board = Board::take().unwrap();
+ /// // setup a timer for the receiving radio messages within a certain timeframe
+ /// let mut radio_timer = microbit::hal::Timer::new(board.TIMER0);
+ /// // set the clock to a high frequency one
+ /// let clock = Clocks::new(board.CLOCK).enable_ext_hfosc();
+ /// // create the radio instance
+ /// let mut radio = ieee802154::Radio::init(board.RADIO, &clock);
+ ///
+ /// // create an empty message packet
+ /// let mut packet = ieee802154::Packet::new();
+ ///
+ /// // Wait if a package gets received for 1.000 microseconds
+ /// match radio
+ /// .recv_timeout(&mut packet, &mut radio_timer, 1000)
+ /// {
+ /// // Use the received radio packet...
+ /// Ok(_) => {
+ /// if packet.deref()[0] == 2u8 { /* ... */ }
+ /// }
+ /// // Expected timeout if no message was received in time
+ /// Err(ieee802154::Error::Timeout) => {}
+ /// Err(ieee802154::Error::Crc(error_code)) => {/* Handle crc error */}
+ /// }
+ ///
+ /// // fill the packet payload with 2 bytes of 42
+ /// packet.copy_from_slice(&[42u8;2]);
+ /// // send the radio packet
+ /// radio.send(&mut packet);
+ /// # loop {
+ /// # }
+ /// ```
pub RADIO: pac::RADIO,
- /// nRF51 peripheral: RNG
+ /// nRF51 peripheral: RNG
+ /// Can be used with [`Rng::new()`](`crate::hal::rng::Rng::new()`)
+ /// ```no_run
+ /// # use microbit_common as microbit;
+ /// use microbit::{hal::{clocks, rng}, Board};
+ /// // take the board
+ /// let board = Board::take().unwrap();
+ ///
+ /// // start low frequency clock
+ /// clocks::Clocks::new(board.CLOCK).start_lfclk();
+ ///
+ /// // create a new hardware rng instance
+ /// let mut rng = rng::Rng::new(board.RNG);
+ ///
+ /// // read random u32 directly from hardware rng
+ /// let small_int = rng.random_u32();
+ /// # loop {}
+ /// ```
pub RNG: pac::RNG,
/// nRF51 peripheral: RTC0
@@ -83,13 +143,16 @@ pub struct Board {
/// Can be used with [`Temp::new()`](`crate::hal::temp::Temp::new()`)
pub TEMP: pac::TEMP,
- /// nRF51 peripheral: TIMER0
+ /// nRF51 peripheral: TIMER0
+ /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
pub TIMER0: pac::TIMER0,
- /// nRF51 peripheral: TIMER1
+ /// nRF51 peripheral: TIMER1
+ /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
pub TIMER1: pac::TIMER1,
- /// nRF51 peripheral: TIMER2
+ /// nRF51 peripheral: TIMER2
+ /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
pub TIMER2: pac::TIMER2,
/// nRF51 peripheral: TWI0
diff --git a/microbit-common/src/v2/board.rs b/microbit-common/src/v2/board.rs
index f65ff85..018bde8 100644
--- a/microbit-common/src/v2/board.rs
+++ b/microbit-common/src/v2/board.rs
@@ -81,50 +81,122 @@ pub struct Board {
/// nRF52 peripheral: GPIOTE
pub GPIOTE: pac::GPIOTE,
- /// nRF52 peripheral: PWM0
+ /// nRF52 peripheral: PWM0
+ /// Can be used with [`Pwm::new()`](`crate::hal::pwm::Pwm::new()`)
pub PWM0: pac::PWM0,
- /// nRF52 peripheral: PWM1
+ /// nRF52 peripheral: PWM1
+ /// Can be used with [`Pwm::new()`](`crate::hal::pwm::Pwm::new()`)
pub PWM1: pac::PWM1,
- /// nRF52 peripheral: PWM2
+ /// nRF52 peripheral: PWM2
+ /// Can be used with [`Pwm::new()`](`crate::hal::pwm::Pwm::new()`)
pub PWM2: pac::PWM2,
- /// nRF52 peripheral: PWM3
+ /// nRF52 peripheral: PWM3
+ /// Can be used with [`Pwm::new()`](`crate::hal::pwm::Pwm::new()`)
pub PWM3: pac::PWM3,
- /// nRF52 peripheral: RADIO
+ /// nRF52 peripheral: RADIO
+ /// Can be used with [`Radio::init()`](`crate::hal::ieee802154::Radio::init()`)
+ /// ```no_run
+ /// # use microbit_common as microbit;
+ /// # use microbit::{
+ /// # Board,
+ /// # hal::Clocks,
+ /// # display::blocking::Display,
+ /// # };
+ /// # use embedded_hal::blocking::delay::DelayMs;
+ /// # use core::ops::Deref;
+ /// use microbit::hal::ieee802154;
+ /// // take the board
+ /// let board = Board::take().unwrap();
+ /// // setup a timer for the receiving radio messages within a certain timeframe
+ /// let mut radio_timer = microbit::hal::Timer::new(board.TIMER0);
+ /// // set the clock to a high frequency one
+ /// let clock = Clocks::new(board.CLOCK).enable_ext_hfosc();
+ /// // create the radio instance
+ /// let mut radio = ieee802154::Radio::init(board.RADIO, &clock);
+ ///
+ /// // create an empty message packet
+ /// let mut packet = ieee802154::Packet::new();
+ ///
+ /// // Wait if a package gets received for 1.000 microseconds
+ /// match radio
+ /// .recv_timeout(&mut packet, &mut radio_timer, 1000)
+ /// {
+ /// // Use the received radio packet...
+ /// Ok(_) => {
+ /// if packet.deref()[0] == 2u8 { /* ... */ }
+ /// }
+ /// // Expected timeout if no message was received in time
+ /// Err(ieee802154::Error::Timeout) => {}
+ /// Err(ieee802154::Error::Crc(error_code)) => {/* Handle crc error */}
+ /// }
+ ///
+ /// // fill the packet payload with 2 bytes of 42
+ /// packet.copy_from_slice(&[42u8;2]);
+ /// // send the radio packet
+ /// radio.send(&mut packet);
+ /// # loop {
+ /// # }
+ /// ```
pub RADIO: pac::RADIO,
- /// nRF52 peripheral: RNG
+ /// nRF52 peripheral: RNG
+ /// Can be used with [`Rng::new()`](`crate::hal::rng::Rng::new()`)
+ /// ```no_run
+ /// # use microbit_common as microbit;
+ /// use microbit::{hal::{clocks, rng}, Board};
+ /// // take the board
+ /// let board = Board::take().unwrap();
+ ///
+ /// // start low frequency clock
+ /// clocks::Clocks::new(board.CLOCK).start_lfclk();
+ ///
+ /// // create a new hardware rng instance
+ /// let mut rng = rng::Rng::new(board.RNG);
+ ///
+ /// // read random u32 directly from hardware rng
+ /// let small_int = rng.random_u32();
+ /// # loop {}
+ /// ```
pub RNG: pac::RNG,
/// nRF52 peripheral: RTC0
pub RTC0: pac::RTC0,
-
+
/// nRF52 peripheral: RTC1
pub RTC1: pac::RTC1,
/// nRF52 peripheral: RTC2
- pub RTC2: pac::RTC2,
+ pub RTC2: pac::RTC2,
+
+ /// nRF52 peripheral: SAADC
+ pub SAADC: pac::SAADC,
/// nRF52 peripheral: TEMP
/// Can be used with [`Temp::new()`](`crate::hal::temp::Temp::new()`)
pub TEMP: pac::TEMP,
- /// nRF52 peripheral: TIMER0
+ /// nRF52 peripheral: TIMER0
+ /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
pub TIMER0: pac::TIMER0,
- /// nRF52 peripheral: TIMER1
+ /// nRF52 peripheral: TIMER1
+ /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
pub TIMER1: pac::TIMER1,
- /// nRF52 peripheral: TIMER2
+ /// nRF52 peripheral: TIMER2
+ /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
pub TIMER2: pac::TIMER2,
- /// nRF52 peripheral: TIMER3
+ /// nRF52 peripheral: TIMER3
+ /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
pub TIMER3: pac::TIMER3,
- /// nRF52 peripheral: TIMER4
+ /// nRF52 peripheral: TIMER4
+ /// Can be used with [`Timer::new()`](`crate::hal::Timer::new()`) or other Timer instances
pub TIMER4: pac::TIMER4,
/// nRF52 peripheral: TWIM0
@@ -138,9 +210,6 @@ pub struct Board {
/// nRF52 peripheral: UARTE1
pub UARTE1: pac::UARTE1,
-
- /// nRF52 peripheral: SAADC
- pub SAADC: pac::SAADC,
}
impl Board {
@@ -253,7 +322,8 @@ impl Board {
RNG: p.RNG,
RTC0: p.RTC0,
RTC1: p.RTC1,
- RTC2: p.RTC2,
+ RTC2: p.RTC2,
+ SAADC: p.SAADC,
TEMP: p.TEMP,
TIMER0: p.TIMER0,
TIMER1: p.TIMER1,
@@ -264,7 +334,6 @@ impl Board {
TWIS0: p.TWIS0,
UARTE0: p.UARTE0,
UARTE1: p.UARTE1,
- SAADC: p.SAADC,
}
}
}