From 588c0479f5dacd21e8654463eb3ca3d847d5dcd9 Mon Sep 17 00:00:00 2001
From: Henrik Berg <henrik1965@gmail.com>
Date: Thu, 13 Jul 2023 11:16:11 +0200
Subject: [PATCH] Add descriptions to all RP2040 examples. Some need hardware
 that was not specified.

---
 examples/rp/src/bin/adc.rs                     |  5 ++++-
 examples/rp/src/bin/blinky.rs                  |  4 ++++
 examples/rp/src/bin/button.rs                  |  4 ++++
 examples/rp/src/bin/flash.rs                   |  2 ++
 examples/rp/src/bin/gpio_async.rs              |  6 ++++--
 examples/rp/src/bin/gpout.rs                   |  4 ++++
 examples/rp/src/bin/i2c_async.rs               |  5 +++++
 examples/rp/src/bin/i2c_blocking.rs            |  5 +++++
 examples/rp/src/bin/lora_lorawan.rs            |  1 +
 examples/rp/src/bin/lora_p2p_receive.rs        |  1 +
 examples/rp/src/bin/lora_p2p_send.rs           |  1 +
 examples/rp/src/bin/lora_p2p_send_multicore.rs |  1 +
 examples/rp/src/bin/multicore.rs               |  4 ++++
 examples/rp/src/bin/pio_async.rs               | 11 ++++++++++-
 examples/rp/src/bin/pio_dma.rs                 |  2 ++
 examples/rp/src/bin/pio_hd44780.rs             |  3 +++
 examples/rp/src/bin/pio_ws2812.rs              |  3 +++
 examples/rp/src/bin/pwm.rs                     |  4 ++++
 examples/rp/src/bin/rtc.rs                     |  2 ++
 examples/rp/src/bin/spi.rs                     |  4 ++++
 examples/rp/src/bin/spi_async.rs               |  3 +++
 examples/rp/src/bin/spi_display.rs             |  5 +++++
 examples/rp/src/bin/uart.rs                    |  6 ++++++
 examples/rp/src/bin/uart_buffered_split.rs     |  6 ++++++
 examples/rp/src/bin/uart_unidir.rs             |  6 +++++-
 examples/rp/src/bin/usb_ethernet.rs            |  4 ++++
 examples/rp/src/bin/usb_logger.rs              |  4 ++++
 examples/rp/src/bin/usb_serial.rs              |  4 ++++
 examples/rp/src/bin/watchdog.rs                |  4 ++++
 examples/rp/src/bin/wifi_ap_tcp_server.rs      |  3 +++
 examples/rp/src/bin/wifi_blinky.rs             |  4 ++++
 examples/rp/src/bin/wifi_scan.rs               |  3 +++
 examples/rp/src/bin/wifi_tcp_server.rs         |  3 +++
 33 files changed, 122 insertions(+), 5 deletions(-)

diff --git a/examples/rp/src/bin/adc.rs b/examples/rp/src/bin/adc.rs
index 65069cde..c0cbe017 100644
--- a/examples/rp/src/bin/adc.rs
+++ b/examples/rp/src/bin/adc.rs
@@ -1,3 +1,6 @@
+//! This example test the ADC (Analog to Digital Conversion) of the RS2040 pin 26, 27 and 28.
+//! It also reads the temperature sensor in the chip.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
@@ -38,5 +41,5 @@ async fn main(_spawner: Spawner) {
 
 fn convert_to_celsius(raw_temp: u16) -> f32 {
     // According to chapter 4.9.5. Temperature Sensor in RP2040 datasheet
-    27.0 - (raw_temp as f32 * 3.3 / 4096.0 - 0.706) / 0.001721 as f32
+    27.0 - (raw_temp as f32 * 3.3 / 4096.0 - 0.706) / 0.001721
 }
diff --git a/examples/rp/src/bin/blinky.rs b/examples/rp/src/bin/blinky.rs
index 7aa36a19..295b000f 100644
--- a/examples/rp/src/bin/blinky.rs
+++ b/examples/rp/src/bin/blinky.rs
@@ -1,3 +1,7 @@
+//! This example test the RP Pico on board LED.
+//!
+//! It does not work with the RP Pico W board. See wifi_blinky.rs.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/button.rs b/examples/rp/src/bin/button.rs
index 0d246c09..d7aa8941 100644
--- a/examples/rp/src/bin/button.rs
+++ b/examples/rp/src/bin/button.rs
@@ -1,3 +1,7 @@
+//! This example uses the RP Pico on board LED to test input pin 28. This is not the button on the board.
+//!
+//! It does not work with the RP Pico W board. Use wifi_blinky.rs and add input pin.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/flash.rs b/examples/rp/src/bin/flash.rs
index 19076150..4c4982ac 100644
--- a/examples/rp/src/bin/flash.rs
+++ b/examples/rp/src/bin/flash.rs
@@ -1,3 +1,5 @@
+//! This example test the flash connected to the RP2040 chip.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/gpio_async.rs b/examples/rp/src/bin/gpio_async.rs
index 52d13a9d..bf58044d 100644
--- a/examples/rp/src/bin/gpio_async.rs
+++ b/examples/rp/src/bin/gpio_async.rs
@@ -1,3 +1,7 @@
+//! This example shows how async gpio can be used with a RP2040.
+//!
+//! The LED on the RP Pico W board is connected differently. See wifi_blinky.rs.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
@@ -9,8 +13,6 @@ use embassy_time::{Duration, Timer};
 use gpio::{Input, Level, Output, Pull};
 use {defmt_rtt as _, panic_probe as _};
 
-/// This example shows how async gpio can be used with a RP2040.
-///
 /// It requires an external signal to be manually triggered on PIN 16. For
 /// example, this could be accomplished using an external power source with a
 /// button so that it is possible to toggle the signal from low to high.
diff --git a/examples/rp/src/bin/gpout.rs b/examples/rp/src/bin/gpout.rs
index 64461fc5..0a3b5fa9 100644
--- a/examples/rp/src/bin/gpout.rs
+++ b/examples/rp/src/bin/gpout.rs
@@ -1,3 +1,7 @@
+//! This example shows how GPOUT (General purpose clock outputs) can toggle a output pin.
+//!
+//! The LED on the RP Pico W board is connected differently. Add a LED and resistor to another pin.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/i2c_async.rs b/examples/rp/src/bin/i2c_async.rs
index cf3cf742..93224bc4 100644
--- a/examples/rp/src/bin/i2c_async.rs
+++ b/examples/rp/src/bin/i2c_async.rs
@@ -1,3 +1,8 @@
+//! This example shows how to communicate asynchronous using i2c with external chips.
+//!
+//! Example written for the [`MCP23017 16-Bit I2C I/O Expander with Serial Interface`] chip.
+//! (https://www.microchip.com/en-us/product/mcp23017)
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/i2c_blocking.rs b/examples/rp/src/bin/i2c_blocking.rs
index 7623e33c..1c8c2039 100644
--- a/examples/rp/src/bin/i2c_blocking.rs
+++ b/examples/rp/src/bin/i2c_blocking.rs
@@ -1,3 +1,8 @@
+//! This example shows how to communicate using i2c with external chips.
+//!
+//! Example written for the [`MCP23017 16-Bit I2C I/O Expander with Serial Interface`] chip.
+//! (https://www.microchip.com/en-us/product/mcp23017)
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/lora_lorawan.rs b/examples/rp/src/bin/lora_lorawan.rs
index a9c84bf9..d631fafa 100644
--- a/examples/rp/src/bin/lora_lorawan.rs
+++ b/examples/rp/src/bin/lora_lorawan.rs
@@ -1,5 +1,6 @@
 //! This example runs on the Raspberry Pi Pico with a Waveshare board containing a Semtech Sx1262 radio.
 //! It demonstrates LoRaWAN join functionality.
+
 #![no_std]
 #![no_main]
 #![macro_use]
diff --git a/examples/rp/src/bin/lora_p2p_receive.rs b/examples/rp/src/bin/lora_p2p_receive.rs
index 25041920..396d669d 100644
--- a/examples/rp/src/bin/lora_p2p_receive.rs
+++ b/examples/rp/src/bin/lora_p2p_receive.rs
@@ -1,5 +1,6 @@
 //! This example runs on the Raspberry Pi Pico with a Waveshare board containing a Semtech Sx1262 radio.
 //! It demonstrates LORA P2P receive functionality in conjunction with the lora_p2p_send example.
+
 #![no_std]
 #![no_main]
 #![macro_use]
diff --git a/examples/rp/src/bin/lora_p2p_send.rs b/examples/rp/src/bin/lora_p2p_send.rs
index 3a0544b1..a0f70fa5 100644
--- a/examples/rp/src/bin/lora_p2p_send.rs
+++ b/examples/rp/src/bin/lora_p2p_send.rs
@@ -1,5 +1,6 @@
 //! This example runs on the Raspberry Pi Pico with a Waveshare board containing a Semtech Sx1262 radio.
 //! It demonstrates LORA P2P send functionality.
+
 #![no_std]
 #![no_main]
 #![macro_use]
diff --git a/examples/rp/src/bin/lora_p2p_send_multicore.rs b/examples/rp/src/bin/lora_p2p_send_multicore.rs
index eef2f7a5..89a62818 100644
--- a/examples/rp/src/bin/lora_p2p_send_multicore.rs
+++ b/examples/rp/src/bin/lora_p2p_send_multicore.rs
@@ -1,5 +1,6 @@
 //! This example runs on the Raspberry Pi Pico with a Waveshare board containing a Semtech Sx1262 radio.
 //! It demonstrates LORA P2P send functionality using the second core, with data provided by the first core.
+
 #![no_std]
 #![no_main]
 #![macro_use]
diff --git a/examples/rp/src/bin/multicore.rs b/examples/rp/src/bin/multicore.rs
index 57278dd6..893b724b 100644
--- a/examples/rp/src/bin/multicore.rs
+++ b/examples/rp/src/bin/multicore.rs
@@ -1,3 +1,7 @@
+//! This example shows how to send messages between the two cores in the RP2040 chip.
+//!
+//! The LED on the RP Pico W board is connected differently. See wifi_blinky.rs.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/pio_async.rs b/examples/rp/src/bin/pio_async.rs
index 69034c92..c001d644 100644
--- a/examples/rp/src/bin/pio_async.rs
+++ b/examples/rp/src/bin/pio_async.rs
@@ -1,3 +1,5 @@
+//! This example shows powerful PIO module in the RP2040 chip.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
@@ -54,7 +56,14 @@ fn setup_pio_task_sm1<'a>(pio: &mut Common<'a, PIO0>, sm: &mut StateMachine<'a,
     // Setupm sm1
 
     // Read 0b10101 repeatedly until ISR is full
-    let prg = pio_proc::pio_asm!(".origin 8", "set x, 0x15", ".wrap_target", "in x, 5 [31]", ".wrap",);
+    let prg = pio_proc::pio_asm!(
+        //
+        ".origin 8",
+        "set x, 0x15",
+        ".wrap_target",
+        "in x, 5 [31]",
+        ".wrap",
+    );
 
     let relocated = RelocatedProgram::new(&prg.program);
     let mut cfg = Config::default();
diff --git a/examples/rp/src/bin/pio_dma.rs b/examples/rp/src/bin/pio_dma.rs
index 80c96355..9ab72e1f 100644
--- a/examples/rp/src/bin/pio_dma.rs
+++ b/examples/rp/src/bin/pio_dma.rs
@@ -1,3 +1,5 @@
+//! This example shows powerful PIO module in the RP2040 chip.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/pio_hd44780.rs b/examples/rp/src/bin/pio_hd44780.rs
index 0a4514a6..8aedd24b 100644
--- a/examples/rp/src/bin/pio_hd44780.rs
+++ b/examples/rp/src/bin/pio_hd44780.rs
@@ -1,3 +1,6 @@
+//! This example shows powerful PIO module in the RP2040 chip to communicate with a HD44780 display.
+//! See (https://www.sparkfun.com/datasheets/LCD/HD44780.pdf)
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/pio_ws2812.rs b/examples/rp/src/bin/pio_ws2812.rs
index 4a111e7a..3de2bd48 100644
--- a/examples/rp/src/bin/pio_ws2812.rs
+++ b/examples/rp/src/bin/pio_ws2812.rs
@@ -1,3 +1,6 @@
+//! This example shows powerful PIO module in the RP2040 chip to communicate with WS2812 LED modules.
+//! See (https://www.sparkfun.com/categories/tags/ws2812)
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/pwm.rs b/examples/rp/src/bin/pwm.rs
index 2b3d5d97..9d919287 100644
--- a/examples/rp/src/bin/pwm.rs
+++ b/examples/rp/src/bin/pwm.rs
@@ -1,3 +1,7 @@
+//! This example shows how to use PWM (Pulse Width Modulation) in the RP2040 chip.
+//!
+//! The LED on the RP Pico W board is connected differently. Add a LED and resistor to another pin.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/rtc.rs b/examples/rp/src/bin/rtc.rs
index d569f598..15aa8243 100644
--- a/examples/rp/src/bin/rtc.rs
+++ b/examples/rp/src/bin/rtc.rs
@@ -1,3 +1,5 @@
+//! This example shows how to use RTC (Real Time Clock) in the RP2040 chip.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/spi.rs b/examples/rp/src/bin/spi.rs
index a830a17a..602348f7 100644
--- a/examples/rp/src/bin/spi.rs
+++ b/examples/rp/src/bin/spi.rs
@@ -1,3 +1,7 @@
+//! This example shows how to use SPI (Serial Peripheral Interface) in the RP2040 chip.
+//!
+//! Example for resistive touch sensor in Waveshare Pico-ResTouch
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/spi_async.rs b/examples/rp/src/bin/spi_async.rs
index 671a9caa..328074e8 100644
--- a/examples/rp/src/bin/spi_async.rs
+++ b/examples/rp/src/bin/spi_async.rs
@@ -1,3 +1,6 @@
+//! This example shows how to use SPI (Serial Peripheral Interface) in the RP2040 chip.
+//! No specific hardware is specified in this example. If you connect pin 11 and 12 you should get the same data back.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/spi_display.rs b/examples/rp/src/bin/spi_display.rs
index 2fd20159..26c258e1 100644
--- a/examples/rp/src/bin/spi_display.rs
+++ b/examples/rp/src/bin/spi_display.rs
@@ -1,3 +1,8 @@
+//! This example shows how to use SPI (Serial Peripheral Interface) in the RP2040 chip.
+//!
+//! Example written for a display using the ST7789 chip. Possibly the Waveshare Pico-ResTouch
+//! (https://www.waveshare.com/wiki/Pico-ResTouch-LCD-2.8)
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/uart.rs b/examples/rp/src/bin/uart.rs
index 05177a6b..451c3c39 100644
--- a/examples/rp/src/bin/uart.rs
+++ b/examples/rp/src/bin/uart.rs
@@ -1,3 +1,9 @@
+//! This example shows how to use UART (Universal asynchronous receiver-transmitter) in the RP2040 chip.
+//!
+//! No specific hardware is specified in this example. Only output on pin 0 is tested.
+//! The Raspberry Pi Debug Probe (https://www.raspberrypi.com/products/debug-probe/) could be used
+//! with its UART port.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/uart_buffered_split.rs b/examples/rp/src/bin/uart_buffered_split.rs
index 9df99bd5..73520171 100644
--- a/examples/rp/src/bin/uart_buffered_split.rs
+++ b/examples/rp/src/bin/uart_buffered_split.rs
@@ -1,3 +1,9 @@
+//! This example shows how to use UART (Universal asynchronous receiver-transmitter) in the RP2040 chip.
+//!
+//! No specific hardware is specified in this example. If you connect pin 0 and 1 you should get the same data back.
+//! The Raspberry Pi Debug Probe (https://www.raspberrypi.com/products/debug-probe/) could be used
+//! with its UART port.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/uart_unidir.rs b/examples/rp/src/bin/uart_unidir.rs
index c0943a1b..c1515a91 100644
--- a/examples/rp/src/bin/uart_unidir.rs
+++ b/examples/rp/src/bin/uart_unidir.rs
@@ -1,5 +1,9 @@
-//! test TX-only and RX-only UARTs. You need to connect GPIO0 to GPIO5 for
+//! This example shows how to use UART (Universal asynchronous receiver-transmitter) in the RP2040 chip.
+//!
+//! Test TX-only and RX-only on two different UARTs. You need to connect GPIO0 to GPIO5 for
 //! this to work
+//! The Raspberry Pi Debug Probe (https://www.raspberrypi.com/products/debug-probe/) could be used
+//! with its UART port.
 
 #![no_std]
 #![no_main]
diff --git a/examples/rp/src/bin/usb_ethernet.rs b/examples/rp/src/bin/usb_ethernet.rs
index 91d1ec8e..0a08f667 100644
--- a/examples/rp/src/bin/usb_ethernet.rs
+++ b/examples/rp/src/bin/usb_ethernet.rs
@@ -1,3 +1,7 @@
+//! This example shows how to use USB (Universal Serial Bus) in the RP2040 chip.
+//!
+//! This is a CDC-NCM class implementation, aka Ethernet over USB.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/usb_logger.rs b/examples/rp/src/bin/usb_logger.rs
index 7c90d0ca..9c5e6897 100644
--- a/examples/rp/src/bin/usb_logger.rs
+++ b/examples/rp/src/bin/usb_logger.rs
@@ -1,3 +1,7 @@
+//! This example shows how to use USB (Universal Serial Bus) in the RP2040 chip.
+//!
+//! This creates the possibility to send log::info/warn/error/debug! to USB serial port.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/usb_serial.rs b/examples/rp/src/bin/usb_serial.rs
index ca728536..164e2052 100644
--- a/examples/rp/src/bin/usb_serial.rs
+++ b/examples/rp/src/bin/usb_serial.rs
@@ -1,3 +1,7 @@
+//! This example shows how to use USB (Universal Serial Bus) in the RP2040 chip.
+//!
+//! This creates a USB serial port that echos.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/watchdog.rs b/examples/rp/src/bin/watchdog.rs
index ece5cfe3..fe5eaf92 100644
--- a/examples/rp/src/bin/watchdog.rs
+++ b/examples/rp/src/bin/watchdog.rs
@@ -1,3 +1,7 @@
+//! This example shows how to use Watchdog in the RP2040 chip.
+//!
+//! It does not work with the RP Pico W board. See wifi_blinky.rs or connect external LED and resistor.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/wifi_ap_tcp_server.rs b/examples/rp/src/bin/wifi_ap_tcp_server.rs
index 3e41f83b..e3e39344 100644
--- a/examples/rp/src/bin/wifi_ap_tcp_server.rs
+++ b/examples/rp/src/bin/wifi_ap_tcp_server.rs
@@ -1,3 +1,6 @@
+//! This example uses the RP Pico W board Wifi chip (cyw43).
+//! Creates an Access point Wifi network and creates a TCP endpoint on port 1234.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/wifi_blinky.rs b/examples/rp/src/bin/wifi_blinky.rs
index 6eb207af..33d43788 100644
--- a/examples/rp/src/bin/wifi_blinky.rs
+++ b/examples/rp/src/bin/wifi_blinky.rs
@@ -1,3 +1,7 @@
+//! This example test the RP Pico W on board LED.
+//!
+//! It does not work with the RP Pico board. See blinky.rs.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/wifi_scan.rs b/examples/rp/src/bin/wifi_scan.rs
index aef18aa2..743fab61 100644
--- a/examples/rp/src/bin/wifi_scan.rs
+++ b/examples/rp/src/bin/wifi_scan.rs
@@ -1,3 +1,6 @@
+//! This example uses the RP Pico W board Wifi chip (cyw43).
+//! Scans Wifi for ssid names.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]
diff --git a/examples/rp/src/bin/wifi_tcp_server.rs b/examples/rp/src/bin/wifi_tcp_server.rs
index 4fce74a6..0223a363 100644
--- a/examples/rp/src/bin/wifi_tcp_server.rs
+++ b/examples/rp/src/bin/wifi_tcp_server.rs
@@ -1,3 +1,6 @@
+//! This example uses the RP Pico W board Wifi chip (cyw43).
+//! Connects to specified Wifi network and creates a TCP endpoint on port 1234.
+
 #![no_std]
 #![no_main]
 #![feature(type_alias_impl_trait)]