From 6b55bafe1ffe9965ea5b0f30ce066d0e96a414d3 Mon Sep 17 00:00:00 2001 From: Fred Dushin Date: Fri, 13 Oct 2023 14:33:54 -0400 Subject: [PATCH] Updates to Getting Started Guide and Release Notes Signed-off-by: Fred Dushin --- doc/release-notes.md.in | 51 ++- doc/src/atomvm-tooling.md | 8 +- doc/src/build-instructions.md | 16 +- doc/src/example-programs.md | 519 ------------------------------- doc/src/getting-started-guide.md | 424 +++++++++++++++---------- doc/src/index.rst | 1 - doc/src/welcome-to-atomvm.md | 2 +- 7 files changed, 308 insertions(+), 713 deletions(-) delete mode 100644 doc/src/example-programs.md diff --git a/doc/release-notes.md.in b/doc/release-notes.md.in index 7acbdbd07..13a3dc2a1 100644 --- a/doc/release-notes.md.in +++ b/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. diff --git a/doc/src/atomvm-tooling.md b/doc/src/atomvm-tooling.md index 13b00b8d2..127c6033a 100644 --- a/doc/src/atomvm-tooling.md +++ b/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) diff --git a/doc/src/build-instructions.md b/doc/src/build-instructions.md index 72441a9a2..bd3d415be 100644 --- a/doc/src/build-instructions.md +++ b/doc/src/build-instructions.md @@ -311,7 +311,7 @@ The `/tools/release/esp32` directory contains the `mkim Running this script will generate a single `atomvm-.img` file in the `build` directory of the esp32 source tree, where `` 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 diff --git a/doc/src/example-programs.md b/doc/src/example-programs.md deleted file mode 100644 index 07838341b..000000000 --- a/doc/src/example-programs.md +++ /dev/null @@ -1,519 +0,0 @@ - - -# Example Programs - -AtomVM includes a collection of useful examples for getting started. This section describes what these examples do, and how to run them, for example, on an ESP32 device. - -## Erlang Examples - -Erlang examples may be run in the UNIX shell or on supported microcontroller devices. - -### `hello_world` - -This example program prints the string "Hello World" and quits. - -#### Command line - -The `hello_world.avm` file will get created as part of a build. This file may be supplied as an argument to the `AtomVM` command: - - shell$ ./src/AtomVM ./examples/erlang/hello_world.avm - hello_world - Return value: ok - -### `udp_server` - -This example program listens on UDP port 44444 and will print information about the received message, including the source IP, (ephemeral) source port, and packet received, to the console. - -#### Command line - -The `udp_server.avm` file will get created as part of a build. This file may be supplied as an argument to the `AtomVM` command: - - shell$ ./src/AtomVM ./examples/erlang/udp_server.avm - Opened UDP socket on "0.0.0.0:44404". - Waiting to receive data... - -You can send UDP packets to the AtomVM instance using `netcat` (or `nc` on some platforms), in a separate terminal window: - - shell$ nc -u localhost 44404 - -This command will wait for you to enter a line of text, e.g., - - testing 1 2 3 - -In the AtomVM termianl window, you see: - - Received UDP packet <<116,101,115,116,105,110,103,32,49,32,50,32,51,10>> from "127.0.0.1:55261" - Waiting to receive data... - -> Note. Netcat appends a newline character at the end of the input, so the packet binary does not display as printable text. - -### `udp_client` - -This example program send the packet of data (":アトムＶＭ") over UDP to port 44444 on the loopback address every 5 seconds, in a loop. The program will print a period (`.`) to the console, every time it sends a message. - -This command may be used in tandem with the `udp_server` program to illustrate sending messages between AtomVM processes over UDP. - -#### Command line - -The `udp_client.avm` file will get created as part of a build. This file may be supplied as an argument to the `AtomVM` command: - - shell$ ./src/AtomVM ./examples/erlang/udp_client.avm - Opened UDP socket on "0.0.0.0:63665". - Sent <<58,-94,-56,-32,54,45>> - Sent <<58,-94,-56,-32,54,45>> - Sent <<58,-94,-56,-32,54,45>> - ... - -If you are running the `udp_server` program, you should see messages like the following printed to the console: - - Received UDP packet <<58,-94,-56,-32,54,45>> from "127.0.0.1:63665" - Waiting to receive data... - Received UDP packet <<58,-94,-56,-32,54,45>> from "127.0.0.1:63665" - Waiting to receive data... - Received UDP packet <<58,-94,-56,-32,54,45>> from "127.0.0.1:63665" - Waiting to receive data... - ... - -> Note. AtomVM does not currently treat characters outside of the printable ASCII character set as printable characters. - -### `tcp_server` - -This example program listens on TCP port 44404 and accept connections on that port. Once accepted, it will wait for packets to be sent from the client. Once received, the server will print the packet received to the console, and then echo the packet back to the calling client. - -#### Command line - -The `tcp_server.avm` file will get created as part of a build. This file may be supplied as an argument to the `AtomVM` command: - - shell$ ./src/AtomVM ./examples/erlang/tcp_server.avm - Listening on "0.0.0.0:44404". - Waiting to accept connection... - -You can send TCP packets to the AtomVM instance using `netcat` (or `nc` on some platforms), in a separate terminal window: - - shell$ nc localhost 44404 - -This will open a TCP connection to the `tcp_server`, and you should see the following on the console: - - Accepted connection. local: "127.0.0.1:44404" peer: "127.0.0.1:56628" - Waiting to receive data... - Waiting to accept connection... - -The netcat command will wait for you to enter a line of text, e.g., - - testing 1 2 3 - -In the AtomVM terminal window, you see: - - Received packet [116,101,115,116,105,110,103,32,49,32,50,32,51,10] from "127.0.0.1:56628". Echoing back... - Waiting to receive data... - -> Note. Netcat appends a newline character at the end of the input, so the packet binary does not display as printable text. - -You may enter as much data as you like, though by default, the packet size will be limited to 128 bytes. - -If you stop the `netcat` command (via ^C), you should - - Connection closed. - -printed to the AtomVM console. - -Note that you can have multiple, concurrent TCP/IP connections to your AtomVM server. - -### `tcp_client` - -This example program send the packet of data (":アトムＶＭ") over TCP to port 44404 on the loopback address every 1 second, in a loop. The program will wait for a response from the server, before proceeding. - -This command may be used in tandem with the `tcp_server` program to illustrate sending messages between AtomVM processes over TCP. - -> Note. You will need to change the `Address` variable in the `tcp_client.erl` program in order to test against an AtomVM server running on a different host or device. - -#### Command line - -The `tcp_client.avm` file will get created as part of a build. This file may be supplied as an argument to the `AtomVM` command: - - shell$ ./src/AtomVM ./examples/erlang/tcp_client.avm - Connected to "127.0.0.1:44404" from "127.0.0.1:56741" - Sent <<58,-94,-56,-32,54,45>> to "127.0.0.1:44404" - Received [58,162,200,224,54,45] from "127.0.0.1:44404" - Sent <<58,-94,-56,-32,54,45>> to "127.0.0.1:44404" - Received [58,162,200,224,54,45] from "127.0.0.1:44404" - Sent <<58,-94,-56,-32,54,45>> to "127.0.0.1:44404" - Received [58,162,200,224,54,45] from "127.0.0.1:44404" - ... - -If you are running the `tcp -_server` program, you should see messages like the following printed to the console: - - Accepted connection. local: "127.0.0.1:44404" peer: "127.0.0.1:56741" - Waiting to receive data... - Waiting to accept connection... - Received packet [58,162,200,224,54,45] from "127.0.0.1:56741". Echoing back... - Waiting to receive data... - Received packet [58,162,200,224,54,45] from "127.0.0.1:56741". Echoing back... - Waiting to receive data... - Received packet [58,162,200,224,54,45] from "127.0.0.1:56741". Echoing back... - Waiting to receive data... - ... - -> Note. AtomVM does not currently treat characters outside of the printable ASCII character set as printable characters. - -You may run multiple concurrent instances of the `tcp_client` against a single `tcp_server` instance. - -## ESP32 Examples - -AtomVM includes examples that are specifically designed for the ESP32 and other microcontrollers. - -## Flashing AtomVM Examples for ESP32 - -In order to run the ESP32 examples, you will need to flash the example AVM files that are created as part of the build to your device. - -In the remainder of this document, we assume the `flash.sh` script, located in the `tools/dev` directory of the AtomVM source tree. - -> Note. You must set the `ESP_IDF` environment variable to the root directory of the ESP IDF SDK installation on your development machine. - -You can control the serial port and baud rate via the `FLASH_SERIAL_PORT` and `FLASH_BAUD_RATE` environment variables, e.g., - - shell$ export FLASH_SERIAL_PORT="/dev/tty.SLAB_USBtoUART" - shell$ export FLASH_BAUD_RATE=921600 - -The default values for these variables, if not set, are `/dev/ttyUSB0` and `115200`, respectively. - -> Note. Experiment with baud rates (e.g., 921600). You may find you can shorten the flash-debug-flash cycle with higher rates. - -You can montor the console output of these examples by issuing the `monitor` target to `make`, in the `src/platforms/esp32` directory of the AtomVM source tree: - - shell$ make monitor - MONITOR - --- WARNING: Serial ports accessed as /dev/tty.* will hang gdb if launched. - --- Using /dev/cu.SLAB_USBtoUART instead... - --- idf_monitor on /dev/cu.SLAB_USBtoUART 115200 --- - --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- - ets Jun 8 2016 00:22:57 - ... - -### `blink` - -The `blink` example will turn the blue LED on an ESP32 SoC (pin 2) on and off, once every second. - -Flash the example program to your device as follows: - - shell$ ./tools/dev/flash.sh build/examples/erlang/esp32/blink.avm - ... - Hard resetting via RTS pin... - -You should see the blue LED turn on and off on your ESP32 device. - -### `esp_random` - -This demo program illustrates use of the ESP32 `random`, `restart`, and `reset_reason` functions. - -The program will generate a random binary of a random size (at most 127 bytes) every 5 seconds. If a 0-length byte sequence is generated (1:128 probability), the ESP will restart. - -Flash the example program to your device as follows: - - shell$ ./tools/dev/flash.sh build/examples/erlang/esp32/esp_random.avm - ... - Hard resetting via RTS pin... - -You should see something like the following output when monitoring the ESP32 output (truncated for brevity): - - shell$ make monitor - ... - Found AVM partition: size: 1048576, address: 0x110000 - Booting file mapped at: 0x3f420000, size: 1048576 - Starting: esp_random.beam... - --- - Reset reason: esp_rst_poweron - Random bytes: <<71,13,221,24,8,15,...,197,120,152,205>> - Random bytes: <<37,155,124,177,44,141,40,106,...,43,48,62,109,2,78,39,107>> - Random bytes: <<217,210,239,183,...,78,68,253,146,212,71,17,208,219,126,240,218,34,0,152,80,20,166,194,106>> - Random bytes: <<112,77,123,249,162,...,238,237,128,227,58,29,64,74>> - ... - <<"">> - ets Jun 8 2016 00:22:57 - ... - Found AVM partition: size: 1048576, address: 0x110000 - Booting file mapped at: 0x3f420000, size: 1048576 - Starting: esp_random.beam... - --- - esp_rst_sw - Random bytes: <<155,174,204,143,232,202,136,...,118,177,77,230,10,21,72,91,92,160,198,115,249,217,206,52,102,32,230>> - ... - -### `esp_nvs` - -This demo program illustrates the use of ESP32 non-volatile storage (NVS). - -The program will store the number of times the device has been rebooted, along with the start time, in NVS. - -Flash the example program to your device as follows: - - shell$ ./tools/dev/flash.sh build/examples/erlang/esp32/esp_nvs.avm - ... - Hard resetting via RTS pin... - -You should see the following output when monitoring the ESP32 output (truncated for brevity): - - shell$ make monitor - ... - Found AVM partition: size: 1048576, address: 0x110000 - Booting file mapped at: 0x3f420000, size: 1048576 - Starting: esp_nvs.beam... - --- - Saving count 0 to NVS... - Reset device to increment. - AtomVM finished with return value = ok - going to sleep forever.. - -Hit the reset button on your device, and the ESP device will reboot, and display something like the following: - - Found AVM partition: size: 1048576, address: 0x110000 - Booting file mapped at: 0x3f420000, size: 1048576 - Starting: esp_nvs.beam... - --- - Saving count 1 to NVS... - Reset device to increment. - AtomVM finished with return value = ok - going to sleep forever.. - -### `reformat_nvs` - -This demo program will reformat the non-volatile storage (NVS) partition. - -Flash the example program to your device as follows: - - shell$ ./tools/dev/flash.sh build/examples/erlang/esp32/reformat_nvs.avm - ... - Hard resetting via RTS pin... - -You should see the following output when monitoring the ESP32 output (truncated for brevity): - - shell$ make monitor - ... - Found AVM partition: size: 1048576, address: 0x110000 - Booting file mapped at: 0x3f420000, size: 1048576 - Starting: esp_nvs.beam... - --- - Warning: Reformatted NVS partition! - AtomVM finished with return value = ok - going to sleep forever.. - -The NVS partition on your ESP device should be reformatted. - -> Note. This program will irrevocably delete all existing key-values stored on the NVS partition. Use with caution. - -### `set_network_config` - -This demo program can be used to set the WIFI credentials in NVS. Setting WIFI credentials in NVS can greatly simplify the task of running ESP programs that require connectivity to WIFI networks. - -> Note. Credentials are stored unencrypted and in plaintext and should not be considered secure. Future versions may use encrypted NVS storage. - -Edit the `sta_network_config.erl` program and set the `Ssid` binary with your WIFI AP SSID, and `Psk` binary with the password used to access your WIFI network. Save the file, rebuild, and flash to your device: - - shell$ make - ... - shell$ ./tools/dev/flash.sh build/examples/erlang/esp32/sta_network_config.avm - ... - Hard resetting via RTS pin... - -You should see the following output when monitoring the ESP32 output (truncated for brevity): - - shell$ make monitor - ... - Found AVM partition: size: 1048576, address: 0x110000 - Booting file mapped at: 0x3f420000, size: 1048576 - Starting: set_network_config.beam... - --- - {atomvm,sta_ssid,<<"myssid">>} - {atomvm,sta_psk,<<"xxxxxx">>} - AtomVM finished with return value = ok - going to sleep forever.. - -You may now run programs that use your WIFI network (see below) without needing to enter WIFI credentials. - -### `sta_network` - -The `sta_network` example will connect to your local WiFi network and obtain and IP address. Once a connection is established, a `connected` message will be displayed. Once an IP address is obtained, the device IP address, netmask, and gateway will be displayed on the console. - -> Note. AtomVM currently only supports station mode (STA). - -> Note. AtomVM currently only supports IPv4 addresses. - -> Note. If you have not set WIFI credentials in NVS (see above), you will need to edit the `examples/erlang/esp32/sta_network.erl` source file and set the `ssid` and `psk` parameters to match your local WiFi network, and then rebuild the example. - -Flash the example program to your device as follows: - - shell$ ./tools/dev/flash.sh build/examples/erlang/esp32/sta_network.avm - ... - Hard resetting via RTS pin... - -You should see the following output when monitoring the ESP32 output (truncated for brevity): - - shell$ make monitor - ... - Starting: sta_network.beam... - --- - I (220) wifi: wifi driver task: 3ffc3b54, prio:23, stack:3584, core=0 - I (220) wifi: wifi firmware version: d5da5a5 - I (220) wifi: config NVS flash: enabled - I (220) wifi: config nano formatting: disabled - I (230) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE - I (240) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE - I (270) wifi: Init dynamic tx buffer num: 32 - I (270) wifi: Init data frame dynamic rx buffer num: 32 - I (270) wifi: Init management frame dynamic rx buffer num: 32 - I (270) wifi: Init static rx buffer size: 1600 - I (280) wifi: Init static rx buffer num: 10 - I (280) wifi: Init dynamic rx buffer num: 32 - I (290) NETWORK: starting wifi: SSID: [myssid], password: [XXXXXXXX]. - I (360) phy: phy_version: 4000, b6198fa, Sep 3 2018, 15:11:06, 0, 0 - I (370) wifi: mode : sta (3c:71:bf:84:d9:08) - I (370) NETWORK: SYSTEM_EVENT_STA_START received. - I (490) wifi: n:1 0, o:1 0, ap:255 255, sta:1 0, prof:1 - I (1470) wifi: state: init -> auth (b0) - I (1480) wifi: state: auth -> assoc (0) - I (1490) wifi: state: assoc -> run (10) - I (1500) wifi: connected with myssid, channel 1 - I (1500) wifi: pm start, type: 1 - I (1500) NETWORK: SYSTEM_EVENT_STA_CONNECTED received. - I (3690) event: sta ip: 192.168.1.236, mask: 255.255.255.0, gw: 192.168.1.1 - I (3690) NETWORK: SYSTEM_EVENT_STA_GOT_IP: 192.168.1.236 - connected - {{192,168,1,236},{255,255,255,0},{192,168,1,1}} - -### `udp_server_blink` - -The `udp_server_blink` example will connect to your local WiFi network and obtain and IP address. It will then start a UDP server on port 44444. When a UDP message is received, the blue LED on the ESP32 SoC (pin 2) will toggle on and off. - -> Note. AtomVM currently only supports station mode (STA). - -> Note. AtomVM currently only supports IPv4 addresses. - -> Note. You will need to edit the `examples/erlang/esp32/udp_server_blink.erl` source file and set the `ssid` and `psk` parameters to match your local WiFi network, and then rebuild the example. - -Flash the example program to your device as follows: - - shell$ ./tools/dev/flash.sh build/examples/erlang/esp32/udp_server_blink.avm - ... - Hard resetting via RTS pin... - -You should see the following output when monitoring the ESP32 output (truncated for brevity): - - shell$ make monitor - ... - Found AVM partition: size: 1048576, address: 0x110000 - Booting file mapped at: 0x3f420000, size: 1048576 - Starting: udp_server_blink.beam... - --- - I (222) wifi: wifi driver task: 3ffc3de8, prio:23, stack:3584, core=0 - I (222) wifi: wifi firmware version: d5da5a5 - I (222) wifi: config NVS flash: enabled - I (232) wifi: config nano formatting: disabled - I (232) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE - I (242) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE - I (312) wifi: Init dynamic tx buffer num: 32 - I (312) wifi: Init data frame dynamic rx buffer num: 32 - I (312) wifi: Init management frame dynamic rx buffer num: 32 - I (312) wifi: Init static rx buffer size: 1600 - I (322) wifi: Init static rx buffer num: 10 - I (322) wifi: Init dynamic rx buffer num: 32 - I (332) NETWORK: starting wifi: SSID: [myssid], password: [XXXXXXXX]. - I (442) phy: phy_version: 4000, b6198fa, Sep 3 2018, 15:11:06, 0, 0 - I (442) wifi: mode : sta (3c:71:bf:84:d9:08) - I (442) NETWORK: SYSTEM_EVENT_STA_START received. - I (572) wifi: n:1 0, o:1 0, ap:255 255, sta:1 0, prof:1 - I (1552) wifi: state: init -> auth (b0) - I (1552) wifi: state: auth -> assoc (0) - I (1562) wifi: state: assoc -> run (10) - I (1582) wifi: connected with myssid, channel 1 - I (1582) wifi: pm start, type: 1 - I (1582) NETWORK: SYSTEM_EVENT_STA_CONNECTED received. - I (2212) event: sta ip: 192.168.1.236, mask: 255.255.255.0, gw: 192.168.1.1 - I (2212) NETWORK: SYSTEM_EVENT_STA_GOT_IP: 192.168.1.236 - Acquired IP address: "192.168.1.236" Netmask: "255.255.255.0" Gateway: "192.168.1.1" - Opened UDP socket on "0.0.0.0:44404". - Waiting to receive data... - -You can send UDP packets to the AtomVM instance using `netcat` (or `nc` on some platforms), in a separate terminal window: - - shell$ nc -u 192.168.1.236 44404 - -Every time you enter a line of text, the blue LED on the ESP32 SoC (pin 2) should toggle on and off, and you should see output on the console, such as - - Received UDP packet <<100,115,102,115,100,10>> from "192.168.1.237:53291" - Waiting to receive data... - -### `tcp_server_blink` - -The `tcp_server_blink` example will connect to your local WiFi network and obtain and IP address. It will then start a TCP server on port 44404. When a TCP message is received, the blue LED on the ESP32 SoC (pin 2) will toggle on and off. - -> Note. AtomVM currently only supports station mode (STA). - -> Note. AtomVM currently only supports IPv4 addresses. - -> Note. You will need to edit the `examples/erlang/esp32/tcp_server_blink.erl` source file and set the `ssid` and `psk` parameters to match your local WiFi network, and then rebuild the example. - -Flash the example program to your device as follows: - - shell$ ./tools/dev/flash.sh build/examples/erlang/esp32/tcp_server_blink.avm - ... - Hard resetting via RTS pin... - -You should see the following output when monitoring the ESP32 output (truncated for brevity): - - shell$ make monitor - Found AVM partition: size: 1048576, address: 0x110000 - Booting file mapped at: 0x3f420000, size: 1048576 - Starting: tcp_server_blink.beam... - --- - start - I (296) wifi: wifi driver task: 3ffc650c, prio:23, stack:3584, core=0 - I (296) wifi: wifi firmware version: 9415913 - I (296) wifi: config NVS flash: enabled - I (296) wifi: config nano formatting: disabled - I (296) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE - I (306) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE - I (346) wifi: Init dynamic tx buffer num: 32 - I (346) wifi: Init data frame dynamic rx buffer num: 32 - I (346) wifi: Init management frame dynamic rx buffer num: 32 - I (346) wifi: Init static rx buffer size: 1600 - I (356) wifi: Init static rx buffer num: 10 - I (356) wifi: Init dynamic rx buffer num: 32 - I (366) NETWORK: starting wifi: SSID: [myssid], password: [XXXXXXXX]. - I (446) phy: phy_version: 4008, c9ae59f, Jan 25 2019, 16:54:06, 0, 0 - I (446) wifi: mode : sta (3c:71:bf:84:d9:08) - I (446) NETWORK: SYSTEM_EVENT_STA_START received. - I (1176) wifi: n:6 0, o:1 0, ap:255 255, sta:6 0, prof:1 - I (2156) wifi: state: init -> auth (b0) - I (2166) wifi: state: auth -> assoc (0) - I (2166) wifi: state: assoc -> run (10) - I (2196) wifi: connected with myssid, channel 6 - I (2196) wifi: pm start, type: 1 - I (2196) NETWORK: SYSTEM_EVENT_STA_CONNECTED received. - I (2746) event: sta ip: 192.168.1.236, mask: 255.255.255.0, gw: 192.168.1.1 - I (2746) NETWORK: SYSTEM_EVENT_STA_GOT_IP: 192.168.1.236 - Acquired IP address: "192.168.1.236" Netmask: "255.255.255.0" Gateway: "192.168.1.1" - Listening on "0.0.0.0:44404". - Waiting to accept connection... - -You can send TCP packets to the AtomVM instance using `netcat` (or `nc` on some platforms), in a separate terminal window, e.g., - - shell$ nc 192.168.1.236 44404 - -On the ESP32 console, you should see: - - Accepted connection. local: "192.168.1.236:44404" peer: "192.168.1.237:55275" - Waiting to receive data... - Waiting to accept connection... - -Every time you enter a line of text, the blue LED on the ESP32 SoC (pin 2) should toggle on and off, and the data you entered should get echoed back to the `netcat` console. - -On the ESP32 console, you should see: - - Received packet [115,100,102,115,100,102,10] from "192.168.1.237:55275". Echoing back... - Waiting to receive data... - -every time a packet is sent to the server. diff --git a/doc/src/getting-started-guide.md b/doc/src/getting-started-guide.md index d7fc5e4ad..070594f91 100644 --- a/doc/src/getting-started-guide.md +++ b/doc/src/getting-started-guide.md @@ -6,24 +6,31 @@ # Getting Started Guide +Welcome to the AtomVM Getting Started Guide. This document is intended to get you started so that you can run Erlang or Elixir programs on the AtomVM platform as quickly as possible. + +In order to do so, you will need to provision your device (depending on the device type) with the AtomVM virtual machine. Typically, you only need to do this once (or at least once per release of the VM you would like to use). Once the VM is provisioned on the device, you can then deploy your application onto the device, and we expect this process to your typical "deploy, test, debug" development lifecycle. The subsequent chapter on [AtomVM Tooling](atomvm-tooling.md) will help you understand that process. + The getting started is broken up into the following sections: * [Getting Started on the ESP32 platform](#getting-started-on-the-esp32-platform) * [Getting Started on the STM32 platform](#getting-started-on-the-stm32-platform) * [Getting Started on the Raspberry Pi Pico platform](#getting-started-on-the-raspberry-pi-pico-platform) * [Getting Started on the Generic UNIX platform](#getting-started-on-the-generic-unix-platform) +* [Getting Started with AtomVM WebAssembly](#getting-started-with-atomvm-webassembly) + +Please use the appropriate section for the device type you intend to use. ## Getting Started on the ESP32 platform -The AtomVM virtual machine is supported on the [Espressif](https://www.espressif.com) [ESP32](https://www.espressif.com/en/products/socs/esp32) platform, allowing users to write Erlang and Elixir programs and deploy them to the ESP32 micro-controller. +The AtomVM virtual machine is supported on the [Espressif](https://www.espressif.com) [ESP32](https://www.espressif.com/en/products/socs/esp32) platform, allowing users to write Erlang and Elixir programs and deploy them to the ESP32 micro-controller. For specific information about which ESP32 boards and chip-sets are supported, please refer to the AtomVM [Release Notes](release-notes.md). -These instructions cover how to get the AtomVM virtual machine flashed to your ESP32 device, as well as how to flash your Erlang and Elixir programs that will be executed by the virtual machine running on the device. +These instructions cover how to provision the AtomVM virtual machine flashed to your ESP32 device. For most applications, you should only need to install the VM once (or at least once per desired AtomVM release). Once the VM is uploaded, you can then begin development of Erlang or Elixir applications, which can then be flashed as part of your routine development cycle. ### Requirements -Deployment of AtomVM applications requires the following components: +Deployment of AtomVM on the ESP32 platform requires the following components: * A computer running MacOS or Linux (Windows support is not currently supported); * An ESP32 module with a USB/UART connector (typically part of an ESP32 development board); @@ -34,9 +41,9 @@ Deployment of AtomVM applications requires the following components: * (recommended) For Erlang programs, [`rebar3`](https://rebar3.org); * (recommended) For Elixir programs, [`mix`](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html), which ships with the Elixir runtime; -For information about specific versions of required software, see the [Release Notes](./release-notes.md). +For information about specific versions of required software, see the AtomVM [Release Notes](./release-notes.md). -### Deployment Overview +### ESP32 Deployment Overview The ES32 AtomVM virtual machine is an IDF application that runs on the ESP32 platform. As an IDF application, it provides the object code to boot the ESP device and execute the AtomVM virtual machine code, which in turn is responsible for execution of an Erlang/Elixir application. @@ -98,28 +105,41 @@ The following methods can be used to deploy the AtomVM virtual machine to an ESP 1. Flashing a binary image; 1. Building from source. -#### Flashing a binary images +#### Flashing a binary image Flashing the ESP32 using a pre-built binary image is by far the easiest path to getting started with development on the ESP32. Binary images contain the virtual machine image and all of the necessary components to run your application. We recommend first erasing any existing applications on the ESP32 device. E.g., - shell$ esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 115200 erase_flash + shell$ esptool.py --chip auto --port /dev/ttyUSB0 --baud 115200 erase_flash ... > Note. Specify the device port and baud settings and AtomVM image name to suit your particular environment. -Next, download a stable or latest development ESP32 [release image](https://github.com/atomvm/AtomVM/releases). +Download the latest [release image](https://github.com/atomvm/AtomVM/releases) for ESP32. + +This image will generally take the form: + + Atomvm--.img + +For example: -> Note. Development images may be unstable and may result in unpredictable behavior. + Atomvm-esp32-v0.6.0.img -Finally, use the `esptool` to flash the image to the start address `0x1000` on the ESP32. E.g., +You will also find the sha256 hash for this file, which you should verify using the `sha256sum` command on your local operating system. - shell$ esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 115200 \ +> Note. Alpha and Beta images may be unstable and may result in unpredictable behavior. + +Finally, use the `esptool.py` command to flash the image to the start address `0x1000` on the ESP32. E.g., + + shell$ esptool.py \ + --chip auto \ + --port /dev/ttyUSB0 --baud 115200 \ --before default_reset --after hard_reset \ - write_flash -u --flash_mode dio --flash_freq 40m --flash_size detect \ - 0x1000 atomvm-esp32-v0.1.0.bin - ... + write_flash -u \ + --flash_mode dio --flash_freq 40m --flash_size detect \ + 0x1000 \ + /path/to/Atomvm-esp32-v0.6.0.img Once completed, your ESP32 device is ready to run Erlang or Elixir programs targeted for AtomVM. @@ -137,203 +157,269 @@ When the AtomVM virtual machine starts, it will search for the first module that AtomVM applications can be written in Erlang or Elixir, or a combination of both. The AtomVM community has provided tooling for both platforms, making deployment of AtomVM applications as seamless as possible. -This section describes both Erlang and Elixir tooling for deploying AtomVM applications to ESP32 devices. +For information about how to flash your application to your ESP32, see the [AtomVM Tooling](atomvm-tooling.md) chapter. -#### Erlang Tooling +## Getting Started on the STM32 platform -Deployment of AtomVM applications written in the Erlang programming language is supported via the [`atomvm_rebar3_plugin`](https://github.com/atomvm/atomvm_rebar3_plugin) plugin, a community-supported plugin to the [`rebar3`](https://rebar3.org) Erlang build tool. +AtomVM can run on a wide variety of STM32 chip-sets available from [STMicroelectronics](https://www.st.com). The support is not nearly as mature as for the ESP32 platform, but work is ongoing, and pull requests are always welcome. At this time AtomVM will work on any board with a minimum of around 128k ram and 512k (1M recommended) flash. Simple applications and tests have been successfully run on a stm32f411ceu6 (A.K.A. Black Pill V2). These minimum requirements may need to be raised as platform support matures. -You can generate a simple application from scratch using the `atomvm_rebar3_plugin` template, as follows: +### Requirements -Edit or create the `$HOME/.config/rebar3/rebar.config` file to include the `atomvm_rebar3_plugin` plugin: +Deployment of AtomVM on the STM32 platform requires the following components: - %% $HOME/.config/rebar3/rebar.config - {plugins, [ - atomvm_rebar3_plugin, - ... - ]}. +* A computer running MacOS or Linux (Windows support is not currently supported); +* An STM32 module with a USB/UART connector (typically part of an STM32 development board); +* A USB cable capable of connecting the STM32 module or board to your development machine (laptop or PC); +* [st-flash](https://github.com/texane/stlink), to flash both AtomVM and your packed AVM applications. Make sure to follow its [installation procedure](https://github.com/texane/stlink#installation) before proceeding further. +* 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). +* A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application. +* (recommended) For Erlang programs, [`rebar3`](https://rebar3.org); +* (recommended) For Elixir programs, [`mix`](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html), which ships with the Elixir runtime; -In any directory in which you have write permission, issue +### Deploying the AtomVM virtual machine - shell$ rebar3 new atomvm_app +The following methods can be used to deploy the AtomVM virtual machine to an STM32 device: -where `` is the name of the application you would like to create (e.g., `myapp`). This command will generate a rebar project under the directory ``. +1. Building from source. -The generated application will contain the proper `rebar.config` configuration and will contain the `.erl` module, which exports the `start/0` function with a stubbed implementation. +Note. Due to the very large number of supported chip-sets and the wide variety of board configurations, and the code changes required to support them, pre-built binaries for the stm32 platform are not currently available. -Specifically, note the following stanza in the generated `rebar.config` file: +Consult the [Build Instructions](build-instructions.md) to create a binary compatible with your board. - %% rebar.config - {plugins, [ - atomvm_rebar3_plugin, - ... - ]}. +#### Flashing a binary image -And note the `myapp` application exports a `start/0` function, e.g., +Once you have created an STM32 binary image, you can flash the image to your STM32 device using the `st-flash` application. - %% erlang - -module(myapp). - -export([start/0]). +To flash your image, use the following command: - start() -> - ok. + shell$ st-flash --reset write AtomVM-stm32f407vgt6.bin 0x8000000 -With this plugin installed, you have access to the `esp32_flash` target, which will build an AtomVM packbeam +Congratulations! You have now flashed the AtomVM VM image onto your STM32 device! - shell$ rebar3 esp32_flash --port /dev/ttyUSB0 - ===> Fetching atomvm_rebar3_plugin v0.6.0 - ===> Fetching rebar3_hex v6.11.3 - ===> Fetching hex_core v0.7.1 - ===> Fetching verl v1.0.2 - ===> Analyzing applications... - ===> Compiling verl - ===> Compiling hex_core - ===> Compiling rebar3_hex - ===> Fetching atomvm_packbeam v0.6.0 - ===> Analyzing applications... - ===> Compiling atomvm_rebar3_plugin - ===> Compiling packbeam - ===> Verifying dependencies... - ===> Analyzing applications... - ===> Compiling myapp - ===> AVM file written to : myapp.avm - ===> esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 115200 --before default_reset --after hard_reset write_flash -u --flash_mode dio --flash_freq 40m --flash_size detect 0x210000 /home/frege/myapp/_build/default/lib/myapp.avm +> Note. AtomVM expects to find the AVM at the address 0x808000. On a STM32 Discovery board this means that the 1MB of flash will be split in 512KB available for the program and 512KB available for the packed AVM. If for any reason you want to modify this, you can change `AVM_ADDRESS` and `AVM_FLASH_MAX_SIZE` defines in `main.c`. -> Note. Consult the the [`atomvm_rebar3_plugin`](https://github.com/atomvm/atomvm_rebar3_plugin) plugin documentation, for more detailed information about how to use this tool. +#### Printing -Once the application has been flashed, you may connect to the ESP32 over the serial port using `minicom`, `screen`, or equivalent. +By default, stdout and stderr are printed on USART2. On the STM32F4Discovery board, you can see them using a TTL-USB with the TX pin connected to board's pin PA2 (USART2 RX). Baudrate is 115200 and serial transmission is 8N1 with no flow control. -#### Elixir Tooling +### Deploying an AtomVM application -> TODO mix + https://github.com/atomvm/ExAtomVM + hex +An AtomVM application is a collection of BEAM files, which have been compiled using the Erlang or Elixir compiler. These BEAM files are assembled into an AtomVM "packbeam" (`.avm`) file, which in turn is flashed to the `main` data partition on the STM32 flash module, starting at address `0x210000`. -## Getting Started on the STM32 platform +When the AtomVM virtual machine starts, it will search for the first module that contains an exported `start/0` function in this partition, and it will begin execution of the BEAM bytecode at that function. -AtomVM can run on a wide variety of STM32 chipsets available from [STMicroelectronics](https://www.st.com). The support is not nearly as mature as for the ESP32 platform, but work is ongoing, and pull requests are always welcome. At this time AtomVM will work on any board with a minimum of around 128k ram and 512k (1M recommended) flash. Simple applications and tests have been successfully run on a stm32f411ceu6 (A.K.A. Black Pill V2). These minimum requirements may need to be raised as platform support matures. +AtomVM applications can be written in Erlang or Elixir, or a combination of both. The AtomVM community has provided tooling for both platforms, making deployment of AtomVM applications as seamless as possible. -### Prerequisites +For information about how to flash your application to your STM32, see the [AtomVM Tooling](atomvm-tooling.md) chapter. -* [st-flash](https://github.com/texane/stlink), to flash both AtomVM and your packed AVM applications. Make sure to follow its [installation procedure](https://github.com/texane/stlink#installation) before proceeding further. -* [`packbeam`](https://github.com/atomvm/atomvm_packbeam) the AtomVM for packing and stripping `*.beam` files into the AtomVM `*.avm` format. +## Getting Started on the Raspberry Pi Pico platform + +AtomVM supports deployment of the VM and applications onto the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/) platform. For information about supported boards, please refer to the AtomVM [Release Notes](release-notes.md). + +The following instructions show you how to install the AtomVM onto one of the [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/) boards. + +### Requirements + +Deployment of AtomVM on the Raspberry Pico platform requires the following components: + +* A computer running MacOS or Linux (Windows support is not currently supported); +* A Raspberry Pico board with a USB/UART connector (typically part of a development board); +* A USB cable capable of connecting the Raspberry Pico module or board to your development machine (laptop or PC); * A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application. +* (recommended) For Erlang programs, [`rebar3`](https://rebar3.org); +* (recommended) For Elixir programs, [`mix`](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html), which ships with the Elixir runtime; -### Build an AtomVM binary -You will first need to build a binary configured for your processor and board layout. Consult the [Build Instruction for STM32](./build-instructions#building-for-stm32) +### Deploying the AtomVM virtual machine -### Flashing -To flash AtomVM, use +The following methods can be used to deploy the AtomVM virtual machine to a Raspberry Pico device: - $ st-flash --reset write AtomVM-stm32f407vgt6.bin 0x8000000 +1. Flashing a binary image; +1. Building from source. -To flash your packed AVM, use +#### Flashing a binary image - $ st-flash --reset write /path/to/your/packed.avm 0x8080000 +Flashing the Raspberry Pico using a pre-built binary image is by far the easiest path to getting started with development on the Raspberry Pico. Binary images contain the virtual machine image and all of the necessary components to run your application. -You must include the atomvmlib.avm with your application when using [packbeam](https://github.com/atomvm/atomvm_packbeam), and it should be pruned: +Download the latest [release image](https://github.com/atomvm/AtomVM/releases) for Raspberry Pico. - $ packbeam create -p -i application.avm application.beam /path/to/AtomVM/build/libs/atomvmlib.avm +This image will generally take the form: -> Note: The option`-i` will instruct packbeam to include file names and line numbers in stack traces. This makes debugging applications far easier, but also increases size, so it may be omitted if desired. The `-p` option should be used, it instructs packbeam to prune the unused functions from the packed `.avm` file, and is strongly recommended. + Atomvm--.uf2 -AtomVM expects to find the AVM at the address 0x808000. On a STM32 Discovery board this means that the 1MB of flash will be split in 512KB available for the program and 512KB available for the packed AVM. If for any reason you want to modify this, you can change `AVM_ADDRESS` and `AVM_FLASH_MAX_SIZE` defines in `main.c`. +For example: -### Printing -By default, stdout and stderr are printed on USART2. On the STM32F4Discovery board, you can see them -using a TTL-USB with the TX pin connected to board's pin PA2 (USART2 RX). Baudrate is 115200 and serial transmission -is 8N1 with no flow control. + Atomvm-pico-v0.6.0.uf2 -### Distributed Binaries -Due to the very large number of supported chipsets, the wide variety of board configurations, and the code changes required to support them, it is unlikely pre-built binaries will be available for the stm32 platform in the near future. Consult the [Build Instruction](./build-instructions#building-for-stm32) to create a binary compatible with your board. +You will also find the sha256 hash for this file, which you should verify using the `sha256sum` command on your local operating system. -## Getting Started on the Raspberry Pi Pico platform +You will also need a copy of the AtomVM core libraries, which include all of the compiled Erlang and Elixir needed to run parts of the VM. -### Prerequisites +This library will generally take the form: -None of these tools are strictly required, but all are recommended for easier development: -* [`rebar3`](https://rebar3.org) -* [`atomvm_rebar3_plugin`](https://github.com/atomvm/atomvm_rebar3_plugin) -* [`packbeam`](https://github.com/atomvm/atomvm_packbeam) the AtomVM for packing and stripping `*.beam` files into the AtomVM `*.avm` format. (included as part of the `atomvm_rebar3_plugin`) -* A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application. + atomvmlib-.uf2 + +For example: + + atomvmlib-v0.6.0.uf2 + +You will also find the sha256 hash for this file, which you should verify using the `sha256sum` command on your local operating system. + +To flash your Raspberry Pico, you will need to undertake a few steps that interact with your operating file system. + +> Note. It is important that you downloads the `.uf2` versions of these files for the Raspbery Pico platform. + +For each of the above files, you will start your Rapberry Pico in bootloader mode by pressing the `BOOTSEL` button on the Raspberry Pico dev board, while powering on the device. Doing so will automatically boot the device and mount the Raspberry Pico on to your file system as a USB device. + +You can then use normal operating system commands (such as `cp`, or even drag-and-drop) to copy the above files to the mounted USB volume. + +Note, however, that in general the USB device will auto-unmount after each file has been copied, so you will need to repeat the procedure for each of the above two files. + +On most Linux systems, the Raspberry Pico will be mounted at `/run/media/${USER}/RPI-RP2`. -### Building AtomVM for Raspberry Pico +On macOS system, the Raspberry Pico will be mounted at `/Volumes/RPI-RP2`. -If you want to use a custom built VM for testing consult the [Build Instructions for Raspberry Pi Pico](./build-instructions#building-for-raspberry-pi-pico) +For example: -### Installing AtomVM and programs on Raspberry Pico + # power on Raspberry Pico with BOOTSEL button pressed + shell ls -l /Volumes/RPI-RP2 + total 16 + -rwxrwxrwx 1 joe staff 241 Sep 5 2008 INDEX.HTM* + -rwxrwxrwx 1 joe staff 62 Sep 5 2008 INFO_UF2.TXT* -The approach consists in installing various uf2 files which include the -address they should be loaded to. + shell$ cp ~/Downloads/AtomVM-pico-v0.6.0.uf2 /Volumes/RPI-RP2/. + ## at this point, the device will auto-unmount -You typically need three uf2 files: -- `AtomVM.uf2` for the VM -- `atomvmlib.uf2` for the standard libraries -- your application's uf2. +And again for the AtomVM core library (note that previously flashed `.uf2` files have disappeared): -We provide an escript-based (what else?) tool to build uf2 files called -`uf2tool` that you can use to bundle your `avm` into uf2. + # power on Raspberry Pico with BOOTSEL button pressed + shell ls -l /Volumes/RPI-RP2 + total 16 + -rwxrwxrwx 1 joe staff 241 Sep 5 2008 INDEX.HTM* + -rwxrwxrwx 1 joe staff 62 Sep 5 2008 INFO_UF2.TXT* -If you need to upgrade AtomVM or the standard libraries, simply copy them again. + shell$ cp ~/Downloads/atomvmlib-v0.6.0.avm /Volumes/RPI-RP2/. + ## at this point, the device will auto-unmount -### Issues with macOS +### Potential Issues with macOS There are known issues copying files to the Pico using macOS, and a lot of literature online. Usually it's best to use the Terminal rather than the Finder because the errors are more explicit. Copying may also fail with UF2 files downloaded from the Internet, typically AtomVM release binaries. -```shell -$ cp ~/Downloads/AtomVM-pico_w-v0.6.0-alpha1-test2.uf2 /Volumes/RPI-RP2/ -cp: /Volumes/RPI-RP2/AtomVM-pico_w-v0.6.0-alpha1-test2.uf2: fcopyfile failed: Operation not permitted -cp: /Users/paul/Downloads/AtomVM-pico_w-v0.6.0-alpha1-test2.uf2: could not copy extended attributes to /Volumes/RPI-RP2/AtomVM-pico_w-v0.6.0-alpha1-test2.uf2: Operation not permitted -``` + shell$ cp ~/Downloads/AtomVM-pico_w-v0.6.0.uf2 /Volumes/RPI-RP2/. + cp: /Volumes/RPI-RP2/AtomVM-pico-v0.6.0.uf2: fcopyfile failed: Operation not permitted + cp: /Users/joe/Downloads/AtomVM-pico-v0.6.0.uf2: could not copy extended attributes to /Volumes/RPI-RP2/AtomVM-pico-v0.6.0.uf2: Operation not permitted Two issues appear here: one is macOS tries to copy extended attributes and this fails (but this error is not a blocker), and the other is the "Operation not permitted" because the file is quarantined, having been downloaded from the web. + First issue can be solved with `cp -x` if you don't tolerate the error message and second with `xattr -d`. -```shell -$ xattr -d com.apple.quarantine ~/Downloads/AtomVM-pico_w-v0.6.0-alpha1-test2.uf2 -$ cp -x ~/Downloads/AtomVM-pico_w-v0.6.0-alpha1-test2.uf2 /Volumes/RPI-RP2/ -``` + shell$ xattr -d com.apple.quarantine ~/Downloads/AtomVM-pico_w-v0.6.0.uf2 + shell$ cp -x ~/Downloads/AtomVM-pico_w-v0.6.0.uf2 /Volumes/RPI-RP2/. + +### Deploying an AtomVM application -### Installing AtomVM on Raspberry Pico +An AtomVM application is a collection of BEAM files, which have been compiled using the Erlang or Elixir compiler. These BEAM files are assembled into an AtomVM "packbeam" (`.avm`) file, which in turn can be provided to the `atomvm` executable on the command line. -VM binary is file `AtomVM.uf2` - `src/platforms/rp2040/build/src/AtomVM.uf2` if build from source. Simply copy it -to the pico. The VM will crash because there is no application. +When the AtomVM virtual machine starts, it will search for the first module that contains an exported `start/0` function in this partition, and it will begin execution of the BEAM bytecode at that function. -### Installing atomvm library to Raspberry Pico +AtomVM applications can be written in Erlang or Elixir, or a combination of both. The AtomVM community has provided tooling for both platforms, making deployment of AtomVM applications as seamless as possible. -AtomVM library must be installed as well. For Build instructions consult the Raspberry Pi Pico [libAtomVM build steps](./build-instructions#libatomvm-build-steps) +For information about how to flash your application to your Raspberry Pico, see the [AtomVM Tooling](atomvm-tooling.md) chapter. -#### Installing it +## Getting Started on the Generic UNIX platform -The library to install is `atomvmlib.uf2`, `build/libs/atomvmlib.uf2` if build from source. Copy the library to the pico. +The AtomVM virtual machine is supported a wide variety of Generic UNIX platforms, including many Linux kernels and target architectures, FreeBSD, and MacOS, allowing users to write Erlang and Elixir programs and run them on a local development machine. For specific information about which Generic UNIX versions and architectures are supported, please refer to the AtomVM [Release Notes](release-notes.md). -### Running Hello Pico +These instructions cover how to provision the AtomVM virtual machine onto your development machine. Running applications locally can sometimes be a useful exercise in debugging. -This example will print a Hello Pico message repeatedly. +> Note. Not all programming interfaces are supported on all platforms. See the AtomVM [Programmers Guide](programmers-guide.md) for more information. -It is built into `build/examples/erlang/rp2040/hello_pico.uf2`. +For most applications, you should only need to install the VM once (or at least once per desired AtomVM release). Once the VM is installed, you can then begin development of Erlang or Elixir applications, which can then be flashed as part of your routine development cycle. -You can install it and then connect to the serial port with minicom. +### Requirements -### Running your own BEAM code on Raspberry Pico +Deployment of AtomVM on the Generic UNIX platform requires the following components: -You need to create an avm file using the `packbeam` tool the [`atomvm_rebar3_plugin`](https://github.com/atomvm/atomvm_rebar3_plugin). +* A computer running MacOS or Linux (Windows support is not currently supported); +* An [Erlang/OTP](https://erlang.org) and compatible [Elixir](https://elixir-lang.org) runtime; +* (recommended) For Erlang programs, [`rebar3`](https://rebar3.org); +* (recommended) For Elixir programs, [`mix`](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html), which ships with the Elixir runtime; - packbeam create -p -i packed.avm module.beam +For information about specific versions of required software, see the AtomVM [Release Notes](./release-notes.md). -or +### Installing the AtomVM virtual machine - rebar3 packbeam -p -i packed.avm module.beam +The following methods can be used to install the AtomVM virtual machine on the Generic UNIX platform: -Then the BEAM file must be converted to UF2. -The VM currently expects the application to be loaded at address 0x10100000. +1. Download Linux Binaries +1. (MacOS only) Installing via [macports](https://www.macports.org) or [Homebrew](https://brew.sh); +1. Building from source. - ./uf2tool create -o packed.uf2 -s 0x10100000 packed.avm +#### Installation on Linux Platforms -Copy this UF2 to the Pico after you copied the VM (`AtomVM.uf2`) and the -standard libraries (`atomvmlib.uf2`). +Downloading a pre-built binary image for Linux is by far the easiest path to getting started with development on a Linux development machine. Binary images contain the virtual machine. +Download the latest [release image](https://github.com/atomvm/AtomVM/releases) for Linux. -## Getting Started on the Generic UNIX platform +This image will generally take the form: + + Atomvm-linux-- + +where `` is the target architecture. + +For example: + + Atomvm-linux-x86_64-v0.6.0 + +You will also find the sha256 hash for this file, which you should verify using the `sha256sum` command on your local operating system. + +You will also need a copy of the AtomVM core libraries, which include all of the compiled Erlang and Elixir needed to run parts of the VM. + +This library will generally take the form: + + atomvmlib-.avm + +For example: + + atomvmlib-v0.6.0.avm + +You will also find the sha256 hash for this file, which you should verify using the `sha256sum` command on your local operating system. + +> Note. See the AtomVM [Build Instructions](./build-instructions.md) for instructions about how to run the `AtomVM` binary, together with the AtomVM core libraries on the command line. + +#### Installation on MacOS + +You can install AtomVM for Generic UNIX using [macports](https://www.macports.org) or [Homebrew](https://brew.sh). This instructions assume you are familiar with these package managers. + +To install via [macports](https://www.macports.org): + + shell$ sudo port install atomvm + +Once installed, the `atomvm` executable should be available in your `$PATH` environment variable. + + shell$ which atomvm + /opt/local/bin/atomvm + +To install via [Homebrew](https://brew.sh), you will first need to install the `atomvm` Homebrew Tap: + + shell$ brew tap atomvm/atomvm + +This command will make the `atomvm` [Homebrew](https://brew.sh) formula available to you. + + shell$ brew install atomvm + +Once installed, the `atomvm` executable should be available in your `$PATH` environment variable. + + shell$ which atomvm + /usr/local/bin/atomvm + +#### Building from source + +You may optionally build AtomVM from source and install the AtomVM virtual machine to your development machine. Building AtomVM from source is slightly more involved, as it requires the installation of third party libraries and is typically recommended only for users who are doing development on the AtomVM virtual machine, or for developers implementing custom Nifs or ports. + +Instructions for building AtomVM from source are covered in the AtomVM [Build Instructions](./build-instructions.md). + +### Running applications on the Generic UNIX platform AtomVM may be run on UNIX-like platforms using the `atomvm` command. @@ -344,7 +430,7 @@ You may specify one or more AVM files on the command line when running the `atom To get the current version of AtomVM, use the `-v` option, e.g.: shell$ atomvm -v - 0.6.1 + 0.6.0 Use the `-h` option to get command line help: @@ -365,75 +451,74 @@ Use the `-h` option to get command line help: $ /usr/local/lib/atomvm/AtomVM /path/to/my/application.avm /path/to/atomvmlib.avm -Currently, the `atomvm` command and libraries must be built and installed from source. +## Getting Started with AtomVM WebAssembly -> See the AtomVM [Build Instructions](./build-instructions.md) for instructions about how to build AtomVM on the Generic UNIX platform. +You can run AtomVM for WebAssembly with NodeJS or within common browsers (Safari, Chrome and Chrome-based, Firefox). -## Where to go from here +### Getting Started with AtomVM WebAssembly port for NodeJS -The following resources may be useful for understanding how to develop Erlang or Elixir applications for the AtomVM platform: +Download the latest [release image](https://github.com/atomvm/AtomVM/releases) for Node. + +This image will generally take the form: -* [Example Programs](./example-programs.md) -* [Programmers Guide](./programmers-guide.md) + Atomvm-node-.js +For example: -## Getting Started with AtomVM WebAssembly port for NodeJS + Atomvm-node-v0.6.0.js + +You will also find the sha256 hash for this file, which you should verify using the `sha256sum` command on your local operating system. AtomVM's WebAssembly port for NodeJS may be run using `node` command and AtomVM.js, AtomVM.worker.js and AtomVM.wasm files. - shell$ node /path/to/AtomVM.js /path/to/myapp.avm + shell$ node /path/to/Atomvm-node-v0.6.0.js /path/to/myapp.avm -## Getting Started with AtomVM WebAssembly port for browsers +### Getting Started with AtomVM WebAssembly port for browsers AtomVM may also be run in modern browsers (Safari, Chrome and Chrome-based, Firefox) using AtomVM.js, AtomVM.worker.js and AtomVM.wasm files. Please note that these files are different from the NodeJS ones. Because AtomVM uses SharedArrayBuffer, to be executed by a browser, these files need to be served: + - on localhost or over HTTPS - by a web server that also sends `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers. These headers are also called COOP and COEP headers. These security requirements are documented in [Mozilla's documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements). -### Trying locally from AtomVM source tree +#### Trying locally from AtomVM source tree If you compile AtomVM for Unix as well as for Node as explained in the [build instructions](./build-instructions.md), you can use an AtomVM-based toy webserver to serve the WebAssembly examples with: -``` -./src/AtomVM examples/emscripten/wasm_webserver.avm -``` + ./src/AtomVM examples/emscripten/wasm_webserver.avm This web server serves HTML files from `examples/emscripten/`. It works without HTTPS because files are served on localhost. -### Using a hosting service with a `_headers` file +#### Using a hosting service with a `_headers` file You can also host the three files on a hosting service such as Netlify that uses `_headers` files. The file could have the following content: -``` -/* - Cross-Origin-Opener-Policy: same-origin - Cross-Origin-Embedder-Policy: require-corp -``` + /* + Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp -### Using web server such as Nginx +#### Using web server such as Nginx You can also host the three files on web server such as Nginx or Apache. The configuration for Nginx would be: -``` -server { - add_header Cross-Origin-Opener-Policy "same-origin"; - add_header Cross-Origin-Embedder-Policy "require-corp"; - location / { - ... - } -} -``` + server { + add_header Cross-Origin-Opener-Policy "same-origin"; + add_header Cross-Origin-Embedder-Policy "require-corp"; + location / { + ... + } + } -### Using Javascript service worker trick +#### Using Javascript service worker trick If you have no possibility to modify the headers, for example with GitHub pages, you can still get AtomVM to run in the browser using a Javascript service worker trick. @@ -443,5 +528,6 @@ We did successfully use [coi-serviceworker](https://github.com/gzuidhof/coi-serv The following resources may be useful for understanding how to develop Erlang or Elixir applications for the AtomVM platform: -* [Example Programs](./example-programs.md) -* [Programmers Guide](./programmers-guide.md) +* [AtomVM Tooling](atomvm-tooling.md) +* [Example Programs](https://github.com/atomvm/atomvm_examples) +* [Programmers Guide](programmers-guide.md) diff --git a/doc/src/index.rst b/doc/src/index.rst index e5b1bf4f0..dad0b93a1 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -27,7 +27,6 @@ AtomVM includes many advanced features, including process spawning, monitoring, release-notes.md getting-started-guide atomvm-tooling.md - example-programs programmers-guide network-programming-guide build-instructions diff --git a/doc/src/welcome-to-atomvm.md b/doc/src/welcome-to-atomvm.md index a6be7e5d2..998571c12 100644 --- a/doc/src/welcome-to-atomvm.md +++ b/doc/src/welcome-to-atomvm.md @@ -66,5 +66,5 @@ The following guides provide more detailed information about getting started wit * [Getting Started Guide](./getting-started-guide.md) * [Programmers Guide](./programmers-guide.md) -* [Example Programs](./example-programs.md) +* [Example Programs](https://github.com/atomvm/atomvm_examples) * [Build Instructions](./build-instructions.md)