Merge pull request #125 from 42-technology-ltd/add_sparkfun_to_readme

Add README to Pro Micro RP2040 BSP.

README.md

@@ -128,7 +128,7 @@ a [Pimoroni Pico Lipo 16MB] - a board with USB-C, STEMMA QT/Qwiic connectors,
 plus a Li-Po battery charging circuit.
 
 This crate includes the [rp2040-hal], but also configures each pin of the
-RP2040 chip according to how it is connected up on the Pico Liop.
+RP2040 chip according to how it is connected up on the Pico Lipo.
 
 Note that if you use this crate the compiler will expect the full 16MB flash
 space, and so it may not work if you only have the 4MB variant. 
@@ -136,6 +136,17 @@ space, and so it may not work if you only have the 4MB variant.
 [Pimoroni Pico Lipo 16MB]: https://shop.pimoroni.com/products/pimoroni-pico-lipo?variant=39335427080275
 [pico_lipo_16mb]: https://github.com/rp-rs/rp-hal/tree/main/boards/pico_lipo_16mb
 
+### [pro_micro_rp2040] - Board Support for the [Sparkfun Pro Micro RP2040]
+
+You should include this crate if you are writing code that you want to run on
+a [Sparkfun Pro Micro RP2040] - a smaller RP2040 board with USB-C and a WS2812B addressable LED.
+
+This crate includes the [rp2040-hal], but also configures each pin of the
+RP2040 chip according to how it is connected up on the Pro Micro RP2040.
+
+[Sparkfun Pro Micro RP2040]: https://www.sparkfun.com/products/18288
+[pro_micro_rp2040]: https://github.com/rp-rs/rp-hal/tree/main/boards/pro_micro_rp2040
+
 <!-- ROADMAP -->
 ## Roadmap
 

boards/pro_micro_rp2040/README.md

@@ -0,0 +1,94 @@
+# [pro_micro_rp2040] - Board Support for the [Sparkfun Pro Micro RP2040]
+
+You should include this crate if you are writing code that you want to run on
+a [Sparkfun Pro Micro RP2040] - a smaller [RP2040][Raspberry Pi Silicon RP2040] board with USB-C and a WS2812B addressable LED.
+
+This crate includes the [rp2040-hal], but also configures each pin of the
+RP2040 chip according to how it is connected up on the Pro Micro RP2040.
+
+[Sparkfun Pro Micro RP2040]: https://www.sparkfun.com/products/18288
+[pro_micro_rp2040]: https://github.com/rp-rs/rp-hal/tree/main/boards/pro_micro_rp2040
+[rp2040-hal]: https://github.com/rp-rs/rp-hal/tree/main/rp2040-hal
+[Raspberry Pi Silicon RP2040]: https://www.raspberrypi.org/products/rp2040/
+
+## Using
+
+To use this crate, your `Cargo.toml` file should contain:
+
+```toml
+pro_micro_rp2040 = { git = "https://github.com/rp-rs/rp-hal.git" }
+```
+
+In your program, you will need to call `pro_micro_rp2040::Pins::new` to create
+a new `Pins` structure. This will set up all the GPIOs for any on-board
+devices. See the [examples](./examples) folder for more details.
+
+## Examples
+
+### General Instructions
+
+To compile an example, clone the _rp-hal_ repository and run:
+
+```console
+rp-hal/boards/pro_micro_rp2040 $ cargo build --release --example <name>
+```
+
+You will get an ELF file called
+`./target/thumbv6m-none-eabi/release/examples/<name>`, where the `target`
+folder is located at the top of the _rp-hal_ repository checkout. Normally
+you would also need to specify `--target=thumbv6m-none-eabi` but when
+building examples from this git repository, that is set as the default.
+
+If you want to convert the ELF file to a UF2 and automatically copy it to the
+USB drive exported by the RP2040 bootloader, simply boot your board into
+bootloader mode and run:
+
+```console
+rp-hal/boards/pro_micro_rp2040 $ cargo run --release --example <name>
+```
+
+If you get an error about not being able to find `elf2uf2-rs`, try:
+
+```console
+$ cargo install elf2uf2-rs, then repeating the `cargo run` command above.
+```
+
+### [Rainbow](./examples/pro_micro_rainbow.rs)
+
+This example will display a colour-wheel rainbow effect on the on-board LED.
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to
+be learn, inspire, and create. Any contributions you make are **greatly
+appreciated**.
+
+The steps are:
+
+1. Fork the Project by clicking the 'Fork' button at the top of the page.
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Make some changes to the code or documentation.
+4. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+5. Push to the Feature Branch (`git push origin feature/AmazingFeature`)
+6. Create a [New Pull Request](https://github.com/rp-rs/rp-hal/pulls)
+7. An admin will review the Pull Request and discuss any changes that may be required.
+8. Once everyone is happy, the Pull Request can be merged by an admin, and your work is part of our project!
+
+## Code of Conduct
+
+Contribution to this crate is organized under the terms of the [Rust Code of
+Conduct][CoC], and the maintainer of this crate, the [rp-rs team], promises
+to intervene to uphold that code of conduct.
+
+[CoC]: CODE_OF_CONDUCT.md
+[rp-rs team]: https://github.com/orgs/rp-rs/teams/rp-rs
+
+## License
+
+The contents of this repository are dual-licensed under the _MIT OR Apache
+2.0_ License. That means you can chose either the MIT licence or the
+Apache-2.0 when you re-use this code. See `MIT` or `APACHE2.0` for more
+information on each specific licence.
+
+Any submissions to this project (e.g. as Pull Requests) must be made available
+under these terms.

boards/pro_micro_rp2040/examples/pro_micro_rainbow.rs

@@ -1,4 +1,10 @@
-//! Cycles colors on on the on board addressable LED.
+//! # Rainbow Example for the Pro Micro RP2040
+//!
+//! Runs a rainbow-effect colour wheel on the on-board LED.
+//!
+//! Uses the `ws2812_pio` driver to control the LED, which in turns uses the
+//! RP2040's PIO block.
+
 #![no_std]
 #![no_main]
 
@@ -22,12 +28,23 @@ use pro_micro_rp2040::{
 use smart_leds::{brightness, SmartLedsWrite, RGB8};
 use ws2812_pio::Ws2812;
 
+/// The linker will place this boot block at the start of our program image.
+/// We need this to help the ROM bootloader get our code up and running.
 #[link_section = ".boot2"]
 #[used]
 pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER;
 
+/// Entry point to our bare-metal application.
+///
+/// The `#[entry]` macro ensures the Cortex-M start-up code calls this
+/// function as soon as all global variables are initialised.
+///
+/// The function configures the RP2040 peripherals, then the LED, then runs
+/// the colour wheel in an infinite loop.
 #[entry]
 fn main() -> ! {
+    // Configure the RP2040 peripherals
+
     let mut pac = pac::Peripherals::take().unwrap();
     let mut watchdog = Watchdog::new(pac.WATCHDOG);
 
@@ -44,16 +61,21 @@ fn main() -> ! {
     .unwrap();
 
     let sio = Sio::new(pac.SIO);
+
     let pins = pro_micro_rp2040::Pins::new(
         pac.IO_BANK0,
         pac.PADS_BANK0,
         sio.gpio_bank0,
         &mut pac.RESETS,
     );
+
     let _led: Pin<_, FunctionPio0> = pins.led.into_mode();
+
     let timer = Timer::new(pac.TIMER);
     let mut delay = timer.count_down();
 
+    // Configure the addressable LED
+
     let mut ws = Ws2812::new(
         25,
         pac.PIO0,
@@ -62,6 +84,8 @@ fn main() -> ! {
         timer.count_down(),
     );
 
+    // Infinite colour wheel loop
+
     let mut n: u8 = 128;
     loop {
         ws.write(brightness(once(wheel(n)), 32)).unwrap();
@@ -71,17 +95,22 @@ fn main() -> ! {
         let _ = nb::block!(delay.wait());
     }
 }
-/// Input a value 0 to 255 to get a color value
-/// The colours are a transition r - g - b - back to r.
+
+/// Convert a number from `0..=255` to an RGB color triplet.
+///
+/// The colours are a transition from red, to green, to blue and back to red.
 fn wheel(mut wheel_pos: u8) -> RGB8 {
     wheel_pos = 255 - wheel_pos;
     if wheel_pos < 85 {
-        return (255 - wheel_pos * 3, 0, wheel_pos * 3).into();
-    }
-    if wheel_pos < 170 {
+        // No green in this sector - red and blue only
+        (255 - (wheel_pos * 3), 0, wheel_pos * 3).into()
+    } else if wheel_pos < 170 {
+        // No red in this sector - green and blue only
         wheel_pos -= 85;
-        return (0, wheel_pos * 3, 255 - wheel_pos * 3).into();
-    }
+        (0, wheel_pos * 3, 255 - (wheel_pos * 3)).into()
+    } else {
+        // No blue in this sector - red and green only
         wheel_pos -= 170;
-    (wheel_pos * 3, 255 - wheel_pos * 3, 0).into()
+        (wheel_pos * 3, 255 - (wheel_pos * 3), 0).into()
+    }
 }