Merge pull request #1650 from henrikberg/rp_examples_doc

RP examples gets file description

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,8 @@ 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
+    let temp = 27.0 - (raw_temp as f32 * 3.3 / 4096.0 - 0.706) / 0.001721;
+    let sign = if temp < 0.0 { -1.0 } else { 1.0 };
+    let rounded_temp_x10: i16 = ((temp * 10.0) + 0.5 * sign) as i16;
+    (rounded_temp_x10 as f32) / 10.0
 }

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)]

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)]

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)]

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.

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)]

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)]

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)]

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]

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]

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]

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]

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)]

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();

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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]

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)]

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)]

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)]

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)]

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)]

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)]

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)]

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)]