Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update examples #14

Merged
merged 1 commit into from
Oct 30, 2023
Merged

Update examples #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 29 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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.
UncleGrumpy marked this conversation as resolved.
Show resolved Hide resolved
* 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

Expand Down
8 changes: 0 additions & 8 deletions elixir/Blinky/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
8 changes: 0 additions & 8 deletions elixir/HelloWorld/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
10 changes: 1 addition & 9 deletions elixir/LEDC_Example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
9 changes: 5 additions & 4 deletions elixir/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 | ✅ | ✅ | ❌ | ❌ | ❌ |
fadushin marked this conversation as resolved.
Show resolved Hide resolved
| 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.

Expand Down
90 changes: 62 additions & 28 deletions erlang/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -60,18 +62,50 @@ 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

#### 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.
10 changes: 1 addition & 9 deletions erlang/arepl_example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"},
Expand Down
3 changes: 3 additions & 0 deletions erlang/arepl_example/rebar.config
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@
{plugins, [
atomvm_rebar3_plugin, erlfmt
]}.
{atomvm_rebar3_plugin, [
{packbeam, [prune]}
]}.
8 changes: 0 additions & 8 deletions erlang/blinky/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
3 changes: 3 additions & 0 deletions erlang/blinky/rebar.config
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@
{plugins, [
atomvm_rebar3_plugin, erlfmt
]}.
{atomvm_rebar3_plugin, [
{packbeam, [prune]}
]}.
8 changes: 0 additions & 8 deletions erlang/deep_sleep/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
3 changes: 3 additions & 0 deletions erlang/deep_sleep/rebar.config
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@
{plugins, [
atomvm_rebar3_plugin, erlfmt
]}.
{atomvm_rebar3_plugin, [
{packbeam, [prune]}
]}.
8 changes: 0 additions & 8 deletions erlang/esp_nvs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
3 changes: 3 additions & 0 deletions erlang/esp_nvs/rebar.config
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@
{plugins, [
atomvm_rebar3_plugin, erlfmt
]}.
{atomvm_rebar3_plugin, [
{packbeam, [prune]}
]}.
8 changes: 0 additions & 8 deletions erlang/gpio_interrupt/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
8 changes: 0 additions & 8 deletions erlang/hello_world/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,4 @@ The `hello_world` AtomVM application prints "Hello World" to the console and the

UncleGrumpy marked this conversation as resolved.
Show resolved Hide resolved
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).
8 changes: 0 additions & 8 deletions erlang/i2c_example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
3 changes: 3 additions & 0 deletions erlang/i2c_example/rebar.config
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@
{plugins, [
atomvm_rebar3_plugin, erlfmt
]}.
{atomvm_rebar3_plugin, [
{packbeam, [prune]}
]}.
8 changes: 0 additions & 8 deletions erlang/ledc_example/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,4 @@ The `ledc_example` AtomVM application illustrates use of the AtomVM `ledc` inter

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).
3 changes: 3 additions & 0 deletions erlang/ledc_example/rebar.config
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,6 @@
{plugins, [
atomvm_rebar3_plugin, erlfmt
]}.
{atomvm_rebar3_plugin, [
{packbeam, [prune]}
]}.
Loading
Loading