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, } } }