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

Getting Started Guide guide fixes #890

Merged
merged 1 commit into from
Oct 28, 2023
Merged

Getting Started Guide guide fixes #890

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
51 changes: 34 additions & 17 deletions doc/release-notes.md.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) | ✅ |

fadushin marked this conversation as resolved.
Show resolved Hide resolved
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.
8 changes: 6 additions & 2 deletions doc/src/atomvm-tooling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
16 changes: 12 additions & 4 deletions doc/src/build-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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...

Expand Down Expand Up @@ -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

Expand Down
Loading