Update pico readmes with additional clarity (#39)

Co-authored-by: Rauhul Varma <[email protected]>

Author: mredig

README.md

@@ -11,11 +11,22 @@ This repository is a set of demonstration projects of **Embedded Swift**. Embedd
 > [!WARNING]
 > Embedded Swift is experimental. Some information on this page might be out of date with latest development.
 
-> [!IMPORTANT]
-> Use the latest downloadable 'main' [Development Snapshot](https://www.swift.org/install/macos/#development-snapshots) from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.
+## Building the examples
 
-> [!NOTE]
-> This repository contains code that is not continuously developed, instead it's presented "as is" for educational and demonstrational purposes. Making major improvements to existing examples is discouraged, but additions of new examples is welcome.
+Each example in this repository contains build and deployment instructions, however there are a couple common steps needed for many of the examples included below:
+
+1. Install the latest downloadable 'main' [Development Snapshot](https://www.swift.org/install/macos/#development-snapshots) from swift.org to use Embedded Swift. Public releases of Swift do not yet support Embedded Swift.
+	
+  You can follow the [tutorial here](https://apple.github.io/swift-matter-examples/tutorials/swiftmatterexamples/setup-macos/) for instructions on installing and using nighly Swift toolchains.
+
+2. Install the Python3 dependencies listed in `requirements.txt`.
+
+  ```console
+  $ cd swift-embedded-examples
+  $ python3 -m venv .venv
+  $ source .venv/bin/activate
+  $ python3 -m pip install -r Tools/requirements.txt
+  ```
 
 ## Catalog of Examples
 
@@ -55,6 +66,8 @@ Please note that the presence of community repositories and devices in this list
 
 ## Contributing to this repository
 
+This repository contains code that is not continuously developed, instead it's presented "as is" for educational and demonstrational purposes. Making major improvements to existing examples is discouraged, but additions of new examples is welcome.
+
 ### Code of Conduct
 
 Like all Swift.org projects, we would like these Embedded Swift example projects to foster a diverse and friendly community. We expect contributors to adhere to the [Swift.org Code of Conduct](https://swift.org/code-of-conduct/).

nrfx-blink-sdk/README.md

@@ -23,7 +23,7 @@ This example demonstrates how to integrate with the Zephyr SDK via CMake and how
 ``` console
 $ cd nrfx-blink-sdk
 $ source ~/zephyrproject/.venv/bin/activate
-(.venv) export TOOLCHAINS='<toolchain-name>'
+(.venv) export TOOLCHAINS='<toolchain-identifier>'
 (.venv) cmake -B build -G Ninja -DBOARD=nrf52840dk_nrf52840 -DUSE_CCACHE=0 .
 (.venv) cmake --build build
 ```

pico-blink-sdk/README.md

@@ -20,12 +20,13 @@ This example demonstrates how to integrate with the Pico SDK which is using CMak
 
 - Make sure you have a recent nightly Swift toolchain that has Embedded Swift support.
 - Build and copy the program in the UF2 format to the Mass Storage device to trigger flashing the program into memory (after which the device will reboot and run the firmware):
+
 ``` console
 $ cd pico-blink-sdk
-$ export TOOLCHAINS='<toolchain-name>'
+$ export TOOLCHAINS='<toolchain-identifier>'
 $ export PICO_BOARD=pico
 $ export PICO_SDK_PATH='<path-to-your-pico-sdk>'
-$ export PICO_TOOLCHAIN_PATH='<path-to-the-arm-toolchain>'
+$ export PICO_TOOLCHAIN_PATH='<path-to-the-arm-toolchain>' # A default `brew` install will be located at `/Applications/ArmGNUToolchain/[version]/arm-none-eabi`
 $ cmake -B build -G Ninja .
 $ cmake --build build
 ```

pico-blink/README.md

@@ -13,7 +13,7 @@
 - Build and copy the program in the UF2 format to the Mass Storage device to trigger flashing the program into memory (after which the device will reboot and run the firmware):
 ``` console
 $ cd pico-blink
-$ TOOLCHAINS='<toolchain-name>' ./build.sh
+$ TOOLCHAINS='<toolchain-identifier>' ./build.sh
 $ cp .build/blink.uf2 /Volumes/RP2040
 ```
 - The green LED should now be blinking in a pattern.

pico-w-blink-sdk/README.md

@@ -22,7 +22,7 @@ This example demonstrates how to integrate with the Pico SDK which is using CMak
 - Build and copy the program in the UF2 format to the Mass Storage device to trigger flashing the program into memory (after which the device will reboot and run the firmware):
 ``` console
 $ cd pico-w-blink-sdk
-$ export TOOLCHAINS='<toolchain-name>'
+$ export TOOLCHAINS='<toolchain-identifier>'
 $ export PICO_BOARD=pico_w
 $ export PICO_SDK_PATH='<path-to-your-pico-sdk>'
 $ export PICO_TOOLCHAIN_PATH='<path-to-the-arm-toolchain>'

pico2-neopixel/README.md

@@ -37,7 +37,7 @@ index f6867b5..a2291db 100644
 - Build and copy the program in the UF2 format to the Mass Storage device to trigger flashing the program into memory (after which the device will reboot and run the firmware):
 ``` console
 $ cd pico2-neopixel
-$ TOOLCHAINS='<toolchain-name>' make
+$ TOOLCHAINS='<toolchain-identifier>' make
 $ cp .build/release/Application.uf2 /Volumes/RP2350
 ```
 - The RGB LED should be animating through the color wheel.

stm32-blink/README.md

@@ -12,7 +12,7 @@ This example shows a simple baremetal firmware for an STM32 board that blinks an
 - Build and upload the program to flash memory of the microcontroller:
 ```console
 $ cd stm32-blink
-$ TOOLCHAINS='<toolchain-name>' ./build.sh
+$ TOOLCHAINS='<toolchain-identifier>' ./build.sh
 $ st-flash --reset write .build/blink.bin 0x08000000
 ```
 - The green LED next to the RESET button should now be blinking in a pattern.

stm32-lcd-logo/README.md

@@ -10,7 +10,7 @@
 - Build and upload the program to flash memory of the STM:
 ```console
 $ cd stm32-lcd-logo
-$ TOOLCHAINS='<toolchain-name>' ./build.sh
+$ TOOLCHAINS='<toolchain-identifier>' ./build.sh
 $ st-flash --reset write .build/lcd-logo.bin 0x08000000
 ```
 - The LCD display on the board should now be showing a bouncing animating Swift logo on a fading background, and the user LED on should be blinking.

stm32-neopixel/README.md

@@ -24,7 +24,7 @@ We recommend including a capacitor across the LED strip power supply.
 - Build and upload the program to flash memory of the STM:
 ```console
 $ cd stm32-neopixel
-$ export TOOLCHAINS='<toolchain-name>'
+$ export TOOLCHAINS='<toolchain-identifier>'
 $ make
 $ st-flash --reset write .build/release/Application.bin 0x08000000
 ```

stm32-uart-echo/README.md

@@ -14,7 +14,7 @@ $ screen /dev/cu.usbmodem<...> 115200
 - Build and upload the program to flash memory of the STM:
 ```console
 $ cd stm32-uart-echo
-$ export TOOLCHAINS='<toolchain-name>'
+$ export TOOLCHAINS='<toolchain-identifier>'
 $ make
 $ st-flash --reset write .build/release/Application.bin 0x08000000
 ```