Update examples

This change set makes the following updates to the example programs: * Added instructions and requirements for STM32 and Raspberry Pico platforms, and generally cleaned up README * Updated rebar3 commands so they use the `atomvm` namespace * Added supported and unsupported features for Raspberry Pico platforms * Removed redundant supported/unsupported tables in the example READMEs (information is already encapsulated at the top level) * Added rebar3 plugin stanzas to prune by default for all erlang examples Signed-off-by: Fred Dushin <fred@dushin.net>
atomvm · Oct 30, 2023 · 31f2d58 · 31f2d58
1 parent 8e54aaf
commit 31f2d58
Show file tree

Hide file tree

Showing 38 changed files with 153 additions and 212 deletions.
diff --git a/README.md b/README.md
@@ -19,8 +19,14 @@ The example programs in this collection require the following:
 * Elixir applications:
     * [Elixir](https://elixir-lang.org) Version 1.13 (version compatible with OTP version selected above)
 
+See the [AtomVM Release Notes](https://www.atomvm.net/doc/master/release-notes.html) for information about supported versions of the above software.
+
 For instructions about how to install these requirements, consult your local operating system documentation and package management system.
 
+The above tools make use of plugins designed specifically to simply the development and deployment of applications on to supported platforms.  For more information about these plugins, please refer to the [AtomVM Tooling](https://www.atomvm.net/doc/master/atomvm-tooling.html) documentation.
+
+These instructions assume you have already deployed the AtomVM virtual machine on to the device on which you are running.  For instructions about how to install the AtomVM virtual machine onto devices, see the AtomVM [Getting Started Guide](https://www.atomvm.net/doc/master/getting-started-guide.html).
+
 ### ESP32 Requirements
 
 In order to flash and run these programs on an ESP32 device, you will need, in addition:
@@ -33,11 +39,32 @@ In order to flash and run these programs on an ESP32 device, you will need, in a
 * Some example applications require the presence of a WiFi Access Point (AP), to which the ESP32 device can connect.
 * Some example applications require either an existing WiFi Access Point (AP) or that your personal computer be capable of connecting to the ESP32 acting as a WiFi Access Point (AP).
 
-> Note. AtomVM is currently qualified only on the [ESP32](https://www.espressif.com/en/products/socs/esp32) SoC.  Support for the ESP32-C and ESP32-S* SoCs is TBD.
+> For information about supported ESP32 SoCs, see the AtomVM [Release Notes](https://www.atomvm.net/doc/master/release-notes.html).
 
 ### STM32 Requirements
 
-TODO
+In order to flash and run these programs on an STM32 device, you will need, in addition:
+
+* An STM32 device with support for USB connectivity via UART, such as the [STMicroelectronics](https://www.st.com) [Nucleo-F429ZI](https://www.st.com/en/evaluation-tools/nucleo-f429zi.html).  (Some STM32 boards require an external adapter for UART connectivity)
+* Installation of the release of the AtomVM virtual machine image on the STM32 device.  For information about how to install a release of the AtomVM virtual machine image on an STM32 device, see the AtomVM [Getting Started Guide](https://doc.atomvm.net/getting-started-guide.html) documentation.
+* A USB cable to connect to UART and.or JTAG. (The [STM32F4Discovery](https://www.st.com/en/evaluation-tools/stm32f4discovery.html) needs two cables -- one for built in JTAG, and one for external UART, where as on the [Nucleo-F429ZI](https://www.st.com/en/evaluation-tools/nucleo-f429zi.html) board both UART and JTAG are presented on the one on-board usb connection).
+* The [st-flash](https://github.com/texane/stlink) flashing tool.
+* To use JTAG for flashing and console output debugging, you will need a [st-link v2](https://www.st.com/en/development-tools/st-link-v2.html) or [st-link v3](https://www.st.com/en/development-tools/stlink-v3set.html) device (typically already included on Nucleo and Discovery boards).
+* (Recommended) A serial console program, such as [`minicom`](https://en.wikipedia.org/wiki/Minicom).
+
+> For information about supported STM32 development boards, see the AtomVM [Release Notes](https://www.atomvm.net/doc/master/release-notes.html).
+
+### Raspberry Pico Requirements
+
+In order to flash and run these programs on a Raspberry Pico or Raspberry Pico W device, you will need, in addition:
+
+* A [Raspberry Pico](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-and-pico-h) or [Raspberry Pico W](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w-and-pico-wh) device with support for USB connectivity.
+* Installation of the release of the AtomVM virtual machine image on the Raspberry Pico device.  For information about how to install a release of the AtomVM virtual machine image on an ESP32 device, see the AtomVM [Getting Started Guide](https://doc.atomvm.net/getting-started-guide.html) documentation.
+* A USB cable to connect your Raspberry Pico device.
+* (Recommended) A serial console program, such as [`minicom`](https://en.wikipedia.org/wiki/Minicom).
+* Some example applications require the presence of a WiFi Access Point (AP), to which the Raspberry Pico W device can connect.  Note that these examples are only supported on the Raspberry Pico W.
+
+> For information about supported Raspberry Pico devices, see the AtomVM [Release Notes](https://www.atomvm.net/doc/master/release-notes.html).
 
 ### Generic Unix Requirements
 

diff --git a/elixir/Blinky/README.md b/elixir/Blinky/README.md
@@ -23,12 +23,4 @@ To run this example, connect a 1k ohm resistor in series with a 3.3v LED between
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ✅ |
-| `generic_unix`  | ❌ |
-
 For general information about building and executing Elixir AtomVM example programs, see the Elixir example program [README](../README.md).
diff --git a/elixir/HelloWorld/README.md b/elixir/HelloWorld/README.md
@@ -6,12 +6,4 @@ The `HelloWorld` AtomVM application prints "Hello World" to the console and then
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ✅ |
-| `generic_unix`  | ✅ |
-
 For general information about building and executing Elixir AtomVM example programs, see the Elixir example program [README](../README.md).
diff --git a/elixir/LEDC_Example/README.md b/elixir/LEDC_Example/README.md
@@ -4,17 +4,9 @@ Welcome to the `LEDC_Example` AtomVM application.
 
 The `LEDC_Example` AtomVM application illustrates use of the AtomVM `LEDC` interface.
 
-LEDs are wired to GPIO pins 4, 5, 18, and 19 and should use a resistor (minimum 100 Ohm up to 1K, 220 Ohm is a good choice). Change the number 
+LEDs are wired to GPIO pins 4, 5, 18, and 19 and should use a resistor (minimum 100 Ohm up to 1K, 220 Ohm is a good choice). Change the number
 for the GPIO pins in the example if necessary. See the Blinky example for wiring if you are unsure.
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ❌ |
-| `generic_unix`  | ❌ |
-
 For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
diff --git a/elixir/README.md b/elixir/README.md
@@ -7,10 +7,11 @@ The applications in this directory make use of the [AtomVM Mix Plugin](https://g
 
 Some example programs can only run on specific platform.  The following table summarizes the platforms on which the Elixir example programs can be run.
 
-| Example Program | esp32 | stm32 | generic_unix |
-|-----------------|-------|-------|--------------|
-| Blinky          | ✅ | ✅ | ❌ |
-| HelloWorld      | ✅ | ✅ | ✅ |
+| Example Program | esp32 | stm32 | Pico | Pico W | generic_unix |
+|-----------------|-------|-------|------|--------|--------------|
+| Blinky          | ✅ | ✅ | ❌ | ❌ | ❌ |
+| HelloWorld      | ✅ | ✅ | ✅ | ✅ | ✅ |
+| LEDC_Example    | ✅ | ❌ | ❌ | ❌ | ❌ |
 
 To build and run an example in this directory, change your working directory to the corresponding example program, and execute the generic instructions below.
 

diff --git a/erlang/README.md b/erlang/README.md
@@ -7,40 +7,42 @@ The applications in this directory make use of the [AtomVM Rebar3 Plugin](https:
 
 Some example programs can only run on specific platform.  The following table summarizes the platforms on which the Erlang example programs can be run.
 
-| Example Program | esp32 | stm32 | generic_unix |
-|-----------------|-------|-------|--------------|
-| arepl_example   | ✅ | ❌ | ✅ |
-| blinky          | ✅ | ✅ | ❌ |
-| deep_sleep      | ✅ | ❌ | ❌ |
-| esp_nvs         | ✅ | ❌ | ❌ |
-| gpio_interrupt  | ✅ | ✅ | ❌ |
-| hello_world     | ✅ | ✅ | ✅ |
-| http_server_example | ✅ | ❌ | ✅ |
-| i2c_example     | ✅ | ❌ | ❌ |
-| ledc_example    | ✅ | ❌ | ❌ |
-| read_priv       | ✅ | ✅ | ✅ |
-| spi_example     | ✅ | ❌ | ❌ |
-| system_info     | ✅ | ✅ | ✅ |
-| tcp_client      | ✅ | ❌ | ✅ |
-| tcp_server      | ✅ | ❌ | ✅ |
-| uart_example    | ✅ | ❌ | ❌ |
-| udp_client      | ✅ | ❌ | ✅ |
-| udp_server      | ✅ | ❌ | ✅ |
-| wifi            | ✅ | ❌ | ❌ |
+| Example Program | esp32 | stm32 | Pico | Pico W | generic_unix |
+|-----------------|-------|-------|----------------|------------------|--------------|
+| arepl_example   | ✅ | ❌ | ❌ | ❌ | ✅ |
+| blinky          | ✅ | ❌ | ✅ | ❌ | ❌ |
+| deep_sleep      | ✅ | ❌ | ❌ | ❌ | ❌ |
+| esp_nvs         | ✅ | ❌ | ❌ | ❌ | ❌ |
+| gpio_interrupt  | ✅ | ❌ | ❌ | ❌ | ❌ |
+| hello_world     | ✅ | ✅ | ✅ | ✅ | ✅ |
+| http_server_example | ✅ | ❌ | ❌ | ❌ | ✅ |
+| i2c_example     | ✅ | ❌ | ❌ | ❌ | ❌ |
+| ledc_example    | ✅ | ❌ | ❌ | ❌ | ❌ |
+| read_priv       | ✅ | ✅ | ✅ | ✅ | ✅ |
+| spi_example     | ✅ | ❌ | ❌ | ❌ | ❌ |
+| system_info     | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tcp_client      | ✅ | ❌ | ❌ | ❌ | ✅ |
+| tcp_server      | ✅ | ❌ | ❌ | ❌ | ✅ |
+| uart_example    | ✅ | ❌ | ❌ | ❌ | ❌ |
+| udp_client      | ✅ | ❌ | ❌ | ❌ | ✅ |
+| udp_server      | ✅ | ❌ | ❌ | ❌ | ✅ |
+| wifi            | ✅ | ❌ | ❌ | ❌ | ❌ |
 
 To build and run an example in this directory, change your working directory to the corresponding example program, and execute the generic instructions below.
 
 ## Generic Instructions
 
 The following generic instructions apply to the Erlang examples in this repository.  Special notes about building and running the example programs that deviate from these instructions are noted in the README file for the particular example program.
 
+These instructions make use of the [`atomvm_rebar3_plugin`](https://atomvm.github.io/atomvm_rebar3_plugin).  For more information about AtomVM tooling, please see the [AtomVM Tooling](https://www.atomvm.net/doc/master/atomvm-tooling.html) documentation.
+
 ### Building
 
 To build and package this application into an AtomVM AVM file, use the `packbeam` target:
 
-    shell$ rebar3 packbeam -p -f -i
+    shell$ rebar3 atomvm packbeam
 
-This target will create the `read_priv.avm` file in the `./_build/default/lib/` directory.
+This target will create the `<application>.avm` file in the `./_build/default/lib/` directory, where `<application>` is the name of the example application.
 
 ### Running on the ESP32 platform
 
@@ -50,7 +52,7 @@ To run this application on the ESP32 platform, you must flash the application to
 
 To flash this application to your ESP32 device, issue the `esp32_flash` target.  Use the `--port` option to specify the port to which your device is connected:
 
-    shell$ rebar3 esp32_flash --port /dev/ttyUSB0
+    shell$ rebar3 atomvm esp32_flash --port /dev/ttyUSB0
 
 #### Monitoring an ESP32 Device
 
@@ -60,18 +62,52 @@ Use a serial console program, such as `minicom`, to attach to the device over US
 
 ### Running on the STM32 platform
 
-TODO
+To run this application on the STM32 platform, you must flash the application to the device attached to your computer via USB.  You may then optionally monitor the program via a serial console program to view any data output to the console.
+
+#### Flashing onto an STM32 Device
+
+The STM32 platform requires that the core AtomVM library be included in the application you are targeting for the device.  For information about how to obtain this library, see the [AtomVM Tooling](https://www.atomvm.net/doc/master/atomvm-tooling.html) documentation.
+
+Once you have obtained this library, you must use the `packeam` task to create the AVM file to deploy to your device.  Specify the path to the AtomVM core library using the `-e` option, e.g.,
+
+    shell$ rebar3 atomvm packbeam -e /path/to/atomvmlib.avm
+
+To flash this application to your STM32 device, issue the `stm32_flash` target.  Use the `--port` option to specify the port to which your device is connected:
+
+    shell$ rebar3 atomvm stm32_flash
+
+#### Monitoring an STM32 Device
+
+Use a serial console program, such as `minicom`, to attach to the device over USB:
+
+    shell$ minicom -D /dev/ttyUSB0
 
 ### Running on the Raspberry Pico platform
 
-TODO
+To run this application on the Raspberry Pico platform, you must flash the application to the device attached to your computer via USB.  You may then optionally monitor the program via a serial console program to view any data output to the console.
+
+#### Flashing onto a Raspberry Pico Device
+
+To flash this application to your Pico device, issue the `pico_flash` target:
+
+    shell$ rebar3 atomvm pico_flash
+
+Note that your Raspberry Pico must be mount as a volume on your development machine (press and hold the BOOTSEL button while powering on the device) in order to run this target.  After the Raspberry Pico has been flashed, it should automatically unmount the the USB volume and restart.
+
+#### Monitoring a Raspberry Pico Device
+
+Use a serial console program, such as `minicom`, to attach to the device over USB:
+
+    shell$ minicom -D /dev/ttyACM0
+
+> Note.  After restart, the Pico device should show up as a device on Linux development hosts under `/dev/ttyACM0`.  On MacOS hosts, the Pico device should show up under a device name that matches `/dev/cu.usbmodem14*`.
 
 ### Running on Generic Unix platforms
 
-To run this application on a generic UNIX platform, supply the path to the generated AVM file, together with the AtomVM core library
+To run this application on a generic UNIX platform, supply the path to the generated AVM file to the `atomvm` command:
 
-    shell% /path/to/AtomVM ./_build/default/lib/<example-program>.avm /path/to/atomvmlib.avm
+    shell% atomvm ./_build/default/lib/<example-program>.avm
 
 where `<example-program>` is the name of the example program.
 
-> Note.  Currently, you must build the AtomVM virtual machine from source, in order to run AtomVM applications on the generic UNIX platform.
+> Note.  See the AtomVM [Getting Started Guide](https://www.atomvm.net/doc/master/getting-started-guide.html) for information about how to install AtomVM on the generic UNIX platform.
diff --git a/erlang/arepl_example/README.md b/erlang/arepl_example/README.md
@@ -6,19 +6,11 @@ The `arepl_example` AtomVM application demonstrates the use of the `arepl` LISP
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ❌ |
-| `generic_unix`  | ✅ |
-
 ## Build and Run Instructions
 
 For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
 
-> **IMPORTANT** If you are running this example program on an ESP32 device, you must first copy the `src/config.erl-template` file to set `src/config.erl` and edit the WiFi Access Point SSID and PSK to which the ESP32 device is to connect before building this application:
+> **IMPORTANT** If you are running this example program on a device that supports WiFi (e.g., the ESP32 or Pico W), you must first copy the `src/config.erl-template` file to set `src/config.erl` and edit the WiFi Access Point SSID and PSK to which the ESP32 device is to connect before building this application:
 
     sta => [
         {ssid, "my_sta_ssid"},

diff --git a/erlang/arepl_example/rebar.config b/erlang/arepl_example/rebar.config
@@ -3,3 +3,6 @@
 {plugins, [
     atomvm_rebar3_plugin, erlfmt
 ]}.
+{atomvm_rebar3_plugin, [
+    {packbeam, [prune]}
+]}.
diff --git a/erlang/blinky/README.md b/erlang/blinky/README.md
@@ -23,12 +23,4 @@ To run this example, connect a 1k ohm resistor in series with a 3.3v LED between
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ✅ |
-| `generic_unix`  | ❌ |
-
 For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
diff --git a/erlang/blinky/rebar.config b/erlang/blinky/rebar.config
@@ -3,3 +3,6 @@
 {plugins, [
     atomvm_rebar3_plugin, erlfmt
 ]}.
+{atomvm_rebar3_plugin, [
+    {packbeam, [prune]}
+]}.
diff --git a/erlang/deep_sleep/README.md b/erlang/deep_sleep/README.md
@@ -6,12 +6,4 @@ The `deep_sleep` AtomVM application will put the ESP32 device into low-power dee
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ❌ |
-| `generic_unix`  | ❌ |
-
 For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
diff --git a/erlang/deep_sleep/rebar.config b/erlang/deep_sleep/rebar.config
@@ -3,3 +3,6 @@
 {plugins, [
     atomvm_rebar3_plugin, erlfmt
 ]}.
+{atomvm_rebar3_plugin, [
+    {packbeam, [prune]}
+]}.
diff --git a/erlang/esp_nvs/README.md b/erlang/esp_nvs/README.md
@@ -6,12 +6,4 @@ The `esp_nvs` AtomVM application uses the ESP non-volatile storage to record the
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ❌ |
-| `generic_unix`  | ❌ |
-
 For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
diff --git a/erlang/esp_nvs/rebar.config b/erlang/esp_nvs/rebar.config
@@ -3,3 +3,6 @@
 {plugins, [
     atomvm_rebar3_plugin, erlfmt
 ]}.
+{atomvm_rebar3_plugin, [
+    {packbeam, [prune]}
+]}.
diff --git a/erlang/gpio_interrupt/README.md b/erlang/gpio_interrupt/README.md
@@ -19,12 +19,4 @@ This application will wait in a loop for interrupt signals when GPIO pin 2 is ri
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ✅ |
-| `generic_unix`  | ❌ |
-
 For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
diff --git a/erlang/hello_world/README.md b/erlang/hello_world/README.md
@@ -6,12 +6,4 @@ The `hello_world` AtomVM application prints "Hello World" to the console and the
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ✅ |
-| `generic_unix`  | ✅ |
-
 For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
diff --git a/erlang/i2c_example/README.md b/erlang/i2c_example/README.md
@@ -6,12 +6,4 @@ The `i2c_example` AtomVM application demonstrates use of the `i2c` interface usi
 
 For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
 
-## Supported Platforms
-
-| Platform | Supported |
-|----------|-----------|
-| `esp32`  | ✅ |
-| `stm32`  | ❌ |
-| `generic_unix`  | ❌ |
-
 For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
diff --git a/erlang/i2c_example/rebar.config b/erlang/i2c_example/rebar.config
@@ -3,3 +3,6 @@
 {plugins, [
     atomvm_rebar3_plugin, erlfmt
 ]}.
+{atomvm_rebar3_plugin, [
+    {packbeam, [prune]}
+]}.