Skip to content

Commit de8b648

Browse files
UncleGrumpyUncleGrumpy
authored
Merge pull request #14 from atomvm/examples-cleanup
Update examples
2 parents 8e54aaf + 3e816c0 commit de8b648

File tree

38 files changed

+151
-212
lines changed

38 files changed

+151
-212
lines changed

‎README.md‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,14 @@ The example programs in this collection require the following:
1919
* Elixir applications:
2020
* [Elixir](https://elixir-lang.org) Version 1.13 (version compatible with OTP version selected above)
2121

22+
See the [AtomVM Release Notes](https://www.atomvm.net/doc/master/release-notes.html) for information about supported versions of the above software.
23+
2224
For instructions about how to install these requirements, consult your local operating system documentation and package management system.
2325

26+
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.
27+
28+
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).
29+
2430
### ESP32 Requirements
2531

2632
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
3339
* Some example applications require the presence of a WiFi Access Point (AP), to which the ESP32 device can connect.
3440
* 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).
3541

36-
> 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.
42+
> For information about supported ESP32 SoCs, see the AtomVM [Release Notes](https://www.atomvm.net/doc/master/release-notes.html).
3743
3844
### STM32 Requirements
3945

40-
TODO
46+
In order to flash and run these programs on an STM32 device, you will need, in addition:
47+
48+
* 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)
49+
* 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.
50+
* 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).
51+
* The [st-flash](https://github.com/texane/stlink) flashing tool.
52+
* 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).
53+
* (Recommended) A serial console program, such as [`minicom`](https://en.wikipedia.org/wiki/Minicom).
54+
55+
> For information about supported STM32 development boards, see the AtomVM [Release Notes](https://www.atomvm.net/doc/master/release-notes.html).
56+
57+
### Raspberry Pico Requirements
58+
59+
In order to flash and run these programs on a Raspberry Pico or Raspberry Pico W device, you will need, in addition:
60+
61+
* 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.
62+
* 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.
63+
* A USB cable to connect your Raspberry Pico device.
64+
* (Recommended) A serial console program, such as [`minicom`](https://en.wikipedia.org/wiki/Minicom).
65+
* 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.
66+
67+
> For information about supported Raspberry Pico devices, see the AtomVM [Release Notes](https://www.atomvm.net/doc/master/release-notes.html).
4168
4269
### Generic Unix Requirements
4370

‎elixir/Blinky/README.md‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,4 @@ To run this example, connect a 1k ohm resistor in series with a 3.3v LED between
2323
2424
For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
2525

26-
## Supported Platforms
27-
28-
| Platform | Supported |
29-
|----------|-----------|
30-
| `esp32` | ✅ |
31-
| `stm32` | ✅ |
32-
| `generic_unix` | ❌ |
33-
3426
For general information about building and executing Elixir AtomVM example programs, see the Elixir example program [README](../README.md).

‎elixir/HelloWorld/README.md‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,4 @@ The `HelloWorld` AtomVM application prints "Hello World" to the console and then
66

77
For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
88

9-
## Supported Platforms
10-
11-
| Platform | Supported |
12-
|----------|-----------|
13-
| `esp32` | ✅ |
14-
| `stm32` | ✅ |
15-
| `generic_unix` | ✅ |
16-
179
For general information about building and executing Elixir AtomVM example programs, see the Elixir example program [README](../README.md).

‎elixir/LEDC_Example/README.md‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,9 @@ Welcome to the `LEDC_Example` AtomVM application.
44

55
The `LEDC_Example` AtomVM application illustrates use of the AtomVM `LEDC` interface.
66

7-
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
7+
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
88
for the GPIO pins in the example if necessary. See the Blinky example for wiring if you are unsure.
99

1010
For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
1111

12-
## Supported Platforms
13-
14-
| Platform | Supported |
15-
|----------|-----------|
16-
| `esp32` | ✅ |
17-
| `stm32` | ❌ |
18-
| `generic_unix` | ❌ |
19-
2012
For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).

‎elixir/README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,11 @@ The applications in this directory make use of the [AtomVM Mix Plugin](https://g
77

88
Some example programs can only run on specific platform. The following table summarizes the platforms on which the Elixir example programs can be run.
99

10-
| Example Program | esp32 | stm32 | generic_unix |
11-
|-----------------|-------|-------|--------------|
12-
| Blinky | ✅ | ✅ | ❌ |
13-
| HelloWorld | ✅ | ✅ | ✅ |
10+
| Example Program | esp32 | stm32 | Pico | Pico W | generic_unix |
11+
|-----------------|-------|-------|------|--------|--------------|
12+
| Blinky | ✅ | ✅ | ❌ | ❌ | ❌ |
13+
| HelloWorld | ✅ | ✅ | ✅ | ✅ | ✅ |
14+
| LEDC_Example | ✅ | ❌ | ❌ | ❌ | ❌ |
1415

1516
To build and run an example in this directory, change your working directory to the corresponding example program, and execute the generic instructions below.
1617

‎erlang/README.md‎

Lines changed: 62 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -7,40 +7,42 @@ The applications in this directory make use of the [AtomVM Rebar3 Plugin](https:
77

88
Some example programs can only run on specific platform. The following table summarizes the platforms on which the Erlang example programs can be run.
99

10-
| Example Program | esp32 | stm32 | generic_unix |
11-
|-----------------|-------|-------|--------------|
12-
| arepl_example | ✅ | ❌ | ✅ |
13-
| blinky | ✅ | ✅ | ❌ |
14-
| deep_sleep | ✅ | ❌ | ❌ |
15-
| esp_nvs | ✅ | ❌ | ❌ |
16-
| gpio_interrupt | ✅ | ✅ | ❌ |
17-
| hello_world | ✅ | ✅ | ✅ |
18-
| http_server_example | ✅ | ❌ | ✅ |
19-
| i2c_example | ✅ | ❌ | ❌ |
20-
| ledc_example | ✅ | ❌ | ❌ |
21-
| read_priv | ✅ | ✅ | ✅ |
22-
| spi_example | ✅ | ❌ | ❌ |
23-
| system_info | ✅ | ✅ | ✅ |
24-
| tcp_client | ✅ | ❌ | ✅ |
25-
| tcp_server | ✅ | ❌ | ✅ |
26-
| uart_example | ✅ | ❌ | ❌ |
27-
| udp_client | ✅ | ❌ | ✅ |
28-
| udp_server | ✅ | ❌ | ✅ |
29-
| wifi | ✅ | ❌ | ❌ |
10+
| Example Program | esp32 | stm32 | Pico | Pico W | generic_unix |
11+
|-----------------|-------|-------|----------------|------------------|--------------|
12+
| arepl_example | ✅ | ❌ | ❌ | ❌ | ✅ |
13+
| blinky | ✅ | ❌ | ✅ | ❌ | ❌ |
14+
| deep_sleep | ✅ | ❌ | ❌ | ❌ | ❌ |
15+
| esp_nvs | ✅ | ❌ | ❌ | ❌ | ❌ |
16+
| gpio_interrupt | ✅ | ❌ | ❌ | ❌ | ❌ |
17+
| hello_world | ✅ | ✅ | ✅ | ✅ | ✅ |
18+
| http_server_example | ✅ | ❌ | ❌ | ❌ | ✅ |
19+
| i2c_example | ✅ | ❌ | ❌ | ❌ | ❌ |
20+
| ledc_example | ✅ | ❌ | ❌ | ❌ | ❌ |
21+
| read_priv | ✅ | ✅ | ✅ | ✅ | ✅ |
22+
| spi_example | ✅ | ❌ | ❌ | ❌ | ❌ |
23+
| system_info | ✅ | ✅ | ✅ | ✅ | ✅ |
24+
| tcp_client | ✅ | ❌ | ❌ | ❌ | ✅ |
25+
| tcp_server | ✅ | ❌ | ❌ | ❌ | ✅ |
26+
| uart_example | ✅ | ❌ | ❌ | ❌ | ❌ |
27+
| udp_client | ✅ | ❌ | ❌ | ❌ | ✅ |
28+
| udp_server | ✅ | ❌ | ❌ | ❌ | ✅ |
29+
| wifi | ✅ | ❌ | ❌ | ❌ | ❌ |
3030

3131
To build and run an example in this directory, change your working directory to the corresponding example program, and execute the generic instructions below.
3232

3333
## Generic Instructions
3434

3535
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.
3636

37+
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.
38+
3739
### Building
3840

3941
To build and package this application into an AtomVM AVM file, use the `packbeam` target:
4042

41-
shell$ rebar3 packbeam -p -f -i
43+
shell$ rebar3 atomvm packbeam
4244

43-
This target will create the `read_priv.avm` file in the `./_build/default/lib/` directory.
45+
This target will create the `<application>.avm` file in the `./_build/default/lib/` directory, where `<application>` is the name of the example application.
4446

4547
### Running on the ESP32 platform
4648

@@ -50,7 +52,7 @@ To run this application on the ESP32 platform, you must flash the application to
5052

5153
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:
5254

53-
shell$ rebar3 esp32_flash --port /dev/ttyUSB0
55+
shell$ rebar3 atomvm esp32_flash --port /dev/ttyUSB0
5456

5557
#### Monitoring an ESP32 Device
5658

@@ -60,18 +62,50 @@ Use a serial console program, such as `minicom`, to attach to the device over US
6062

6163
### Running on the STM32 platform
6264

63-
TODO
65+
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.
66+
67+
#### Flashing onto an STM32 Device
68+
69+
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.
70+
71+
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.,
72+
73+
shell$ rebar3 atomvm packbeam -e /path/to/atomvmlib.avm
74+
75+
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:
76+
77+
shell$ rebar3 atomvm stm32_flash
78+
79+
#### Monitoring an STM32 Device
80+
81+
Use a serial console program, such as `minicom`, to attach to the device over USB:
82+
83+
shell$ minicom -D /dev/ttyUSB0
6484

6585
### Running on the Raspberry Pico platform
6686

67-
TODO
87+
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.
88+
89+
#### Flashing onto a Raspberry Pico Device
90+
91+
To flash this application to your Pico device, issue the `pico_flash` target:
92+
93+
shell$ rebar3 atomvm pico_flash
94+
95+
#### Monitoring a Raspberry Pico Device
96+
97+
Use a serial console program, such as `minicom`, to attach to the device over USB:
98+
99+
shell$ minicom -D /dev/ttyACM0
100+
101+
> 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*`.
68102
69103
### Running on Generic Unix platforms
70104

71-
To run this application on a generic UNIX platform, supply the path to the generated AVM file, together with the AtomVM core library
105+
To run this application on a generic UNIX platform, supply the path to the generated AVM file to the `atomvm` command:
72106

73-
shell% /path/to/AtomVM ./_build/default/lib/<example-program>.avm /path/to/atomvmlib.avm
107+
shell% atomvm ./_build/default/lib/<example-program>.avm
74108

75109
where `<example-program>` is the name of the example program.
76110

77-
> Note. Currently, you must build the AtomVM virtual machine from source, in order to run AtomVM applications on the generic UNIX platform.
111+
> 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.

‎erlang/arepl_example/README.md‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,11 @@ The `arepl_example` AtomVM application demonstrates the use of the `arepl` LISP
66

77
For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
88

9-
## Supported Platforms
10-
11-
| Platform | Supported |
12-
|----------|-----------|
13-
| `esp32` | ✅ |
14-
| `stm32` | ❌ |
15-
| `generic_unix` | ✅ |
16-
179
## Build and Run Instructions
1810

1911
For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).
2012

21-
> **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:
13+
> **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:
2214
2315
sta => [
2416
{ssid, "my_sta_ssid"},

‎erlang/arepl_example/rebar.config‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
{plugins, [
44
atomvm_rebar3_plugin, erlfmt
55
]}.
6+
{atomvm_rebar3_plugin, [
7+
{packbeam, [prune]}
8+
]}.

‎erlang/blinky/README.md‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,4 @@ To run this example, connect a 1k ohm resistor in series with a 3.3v LED between
2323
2424
For more information about programming on the AtomVM platform, see the [AtomVM Programmers Guide](https://doc.atomvm.net/programmers-guide.html).
2525

26-
## Supported Platforms
27-
28-
| Platform | Supported |
29-
|----------|-----------|
30-
| `esp32` | ✅ |
31-
| `stm32` | ✅ |
32-
| `generic_unix` | ❌ |
33-
3426
For general information about building and executing Erlang AtomVM example programs, see the Erlang example program [README](../README.md).

‎erlang/blinky/rebar.config‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
{plugins, [
44
atomvm_rebar3_plugin, erlfmt
55
]}.
6+
{atomvm_rebar3_plugin, [
7+
{packbeam, [prune]}
8+
]}.

0 commit comments

Comments
 (0)