Merge pull request #890 from fadushin/gs-guide-fixes

Getting Started Guide guide fixes

doc/release-notes.md.in

@@ -38,40 +38,57 @@ For detailed information about features and bug fixes in the current release, se
 
 ### ESP32 Support
 
+AtomVM supports deployment on the [Espressif ESP32](https://www.espressif.com/en/products/socs) family of architectures.
+
 To run applications built for AtomVM on the ESP32 platform you will need:
 
 * The [`esptool`](https://github.com/espressif/esptool) program, for flashing the AtomVM image and AtomVM programs to ESP32 MCUs.
 * A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application.
 
+AtomVM currently supports the following [Espressif ESP SoCs](https://www.espressif.com/en/products/socs):
+
+| Espressif SoCs | AtomVM support |
+|------------------------------|----------------|
+| [ESP32](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) | ✅ |
+| [ESP32c3](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) | ✅ |
+| [ESP32s2](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) | ✅ |
+| [ESP32s3](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) | ✅ |
+
 AtomVM currently supports the following versions of ESP-IDF:
 
-| Espressif supported versions | AtomVM support |
+| IDF SDK supported versions | AtomVM support |
 |------------------------------|----------------|
-| ESP-IDF v4.4 | ✅ |
-| ESP-IDF v5.0 | ✅ |
-| ESP-IDF v5.1 | ✅ |
+| ESP-IDF [v4.4](https://docs.espressif.com/projects/esp-idf/en/v4.4.6/esp32/get-started/index.html) | ✅ |
+| ESP-IDF [v5.0](https://docs.espressif.com/projects/esp-idf/en/v5.0.4/esp32/get-started/index.html) | ✅ |
+| ESP-IDF [v5.1](https://docs.espressif.com/projects/esp-idf/en/v5.1.1/esp32/get-started/index.html) | ✅ |
 
-Building the AtomVM virtual machine for ESP32 is optional.  In most cases, you can simply download a release image from the AtomVM [release](https://github.com/atomvm/AtomVM/releases) repository.  If you wish to work on development of the VM or use one on the additional drivers that are available in the ([AtomVM repositories](https://github.com/atomvm)) you will need a compatible version of ([Espressif's](https:/espressif.com)) ESP-IDF.  Espressif provides excellent [installation documentation](https://docs.espressif.com/projects/esp-idf/en/release-v4.4/esp32/get-started/index.html).
+Building the AtomVM virtual machine for ESP32 is optional.  In most cases, you can simply download a release image from the AtomVM [release](https://github.com/atomvm/AtomVM/releases) repository.  If you wish to work on development of the VM or use one on the additional drivers that are available in the [AtomVM repositories](https://github.com/atomvm) you will to build AtomVM from source.  See the [Build Instructions](build-instructions.md) for information about how to build AtomVM from source code.
 
 ### STM32 Support
 
-The following software is required to build AtomVM for the STM32 platform:
+AtomVM supports deployment on the [STMicroelectronics](https://www.st.com) [STM32](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html) architecture.
+
 
-| Package |
-|---------|
-| [11.3 ARM toolchain](https://developer.arm.com/-/media/Files/downloads/gnu/11.3.rel1/binrel/arm-gnu-toolchain-11.3.rel1-x86_64-arm-none-eabi.tar.xz) |
-| [libopencm3](https://github.com/libopencm3/libopencm3.git) version 0.8.0 |
+AtomVM has been tested on the following development boards:
+
+| STM32 Development Boards | AtomVM support |
+|------------------------------|----------------|
+| [Nucleo-F429ZI](https://www.st.com/en/evaluation-tools/nucleo-f429zi.html) | ✅ |
+| [STM32F4Discovery](https://www.st.com/en/evaluation-tools/stm32f4discovery.html) | ✅ |
+
+Due to the proliferation of boards for the [STMicroelectronics](https://www.st.com) [STM32](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html) platform, AtomVM does not currently support pre-build binaries for STM32.  In order to deploy AtomVM to the STM32 platform, you will need to build AtomVM for STM32 from source.  See the [Build Instructions](build-instructions.md) for information about how to build AtomVM from source code.
 
 > Note.  AtomVM tests this build on the latest Ubuntu github runner.
 
 ### Raspberry Pi Pico Support
 
-The following software is required to build AtomVM for the Raspberry Pi Pico platform:
+AtomVM supports deployment on the [Raspberry Pico RP2040](https://www.raspberrypi.com/documentation/microcontrollers/rp2040.html) architecture.
 
-| Package |
-|---------|
-| `gcc-arm-none-eabi` |
-| `libnewlib-arm-none-eabi` |
-| `libstdc++-arm-none-eabi-newlib` |
+AtomVM currently supports the following Raspberry Pico development boards:
 
-> Note.  AtomVM tests this build on the latest Ubuntu github runner.
+| Development Board | AtomVM support |
+|------------------------------|----------------|
+| [Raspberry Pico and Pico H](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-and-pico-h) | ✅ |
+| [Raspberry Pico W and Pico WH](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w-and-pico-wh) | ✅ |
+
+Building the AtomVM virtual machine for Raspberry Pico is optional.  In most cases, you can simply download a release image from the AtomVM [release](https://github.com/atomvm/AtomVM/releases) repository.  If you wish to work on development of the VM or use one on the additional drivers that are available in the [AtomVM repositories](https://github.com/atomvm) you will to build AtomVM from source.  See the [Build Instructions](build-instructions.md) for information about how to build AtomVM from source code.

doc/src/atomvm-tooling.md

@@ -130,9 +130,13 @@ Edit the `rebar.config` so that it includes the following `atomvm_rebar3_plugin`
 
 This stanza will guarantee that the generated packbeam file will be pruned when created.
 
+You will need to first build a packbeam file that includes the AtomVM core libraries.  Use the `packbeam` task in the `atomvm` namespace, and specify the path to the `atomvmlib.avm` file you created as part of the build.
+
+    shell$ rebar3 atomvm packbeam -e /path/to/atomvmlib.avm
+
 You may now flash your application to your STM32 device:
 
-    shell$ rebar3 atomvm stm32_flash -e /path/to/atomvmlib.avm
+    shell$ rebar3 atomvm stm32_flash
     ...
     ===> st-flash --reset write /path/to/atomvm_examples/erlang/hello_world/_build/default/lib/hello_world.avm 0x8080000
 
@@ -468,4 +472,4 @@ To get help about `packbeam` syntax, use the `help` subcommand:
 
 ## Where to go from here
 
-With knowledge of AtomVM tooling, you can more easily follow the AtomVM [Example Programs](example-programs.md)
+With knowledge of AtomVM tooling, you can more easily follow the AtomVM [Example Programs](https://github.com/atomvm/atomvm_examples)

doc/src/build-instructions.md

@@ -311,7 +311,7 @@ The `<atomvm-source-tree-root>/tools/release/esp32` directory contains the `mkim
 
 Running this script will generate a single `atomvm-<sha>.img` file in the `build` directory of the esp32 source tree, where `<sha>` is the git hash of the current checkout.  This image contains the ESP32 bootloader, AtomVM executable, and the `eavmlib` and `estdlib` Erlang libraries in one file, which can then be flashed to address `0x1000`.
 
-The `mkimage.sh` script is run from the src/platform/esp32 directory as follows:
+The `mkimage.sh` script is run from the `src/platform/esp32` directory as follows:
 
     shell$ ./build/mkimage.sh
     Writing output to /home/frege/AtomVM/src/platforms/esp32/build/atomvm-esp32-0.6.0-dev+git.602e6bc.img
@@ -423,7 +423,7 @@ If you are doing development work on the core Erlang/Elixir libraries and wish t
     Flash will be erased from 0x001d0000 to 0x001ecfff...
     Wrote 131072 bytes at 0x001d0000 in 1.8 seconds (582.1 kbit/s)...
     Hash of data verified.
-    
+
     Leaving...
     Hard resetting via RTS pin...
 
@@ -495,11 +495,19 @@ Example:
 
 ### Prerequisites
 
-* `arm-none-eabi`/`arm-elf` toolchain compatible with your system
+The following software is required to build AtomVM for the STM32 platform:
+
+| Package |
+|---------|
+| [11.3 ARM toolchain](https://developer.arm.com/-/media/Files/downloads/gnu/11.3.rel1/binrel/arm-gnu-toolchain-11.3.rel1-x86_64-arm-none-eabi.tar.xz) (or compatible with your system) |
+| [libopencm3](https://github.com/libopencm3/libopencm3.git) version 0.8.0 |
 * `cmake`
 * `make`
 * `git`
-* [`libopencm3`](https://github.com/libopencm3/libopencm3)
+
+> Note.  AtomVM tests this build on the latest Ubuntu github runner.
+
+
 
 ### Setup libopencm3