Skip to content

Commit

Permalink
Merge pull request #1075 from UncleGrumpy/docs_pico_cmake
Browse files Browse the repository at this point in the history
Add documentation about Pico build configuration

Adds documentation about Pico `AVM_WAIT_BOOTSEL_ON_EXIT` and
`AVM_USB_WAIT_SECONDS` configuration options to "Build Instruction" and their
effects in the "AtomVM Tooling" chapter.

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
  • Loading branch information
bettio committed Feb 28, 2024
2 parents 75a2ac7 + f2718f1 commit 3904a9a
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 1 deletion.
17 changes: 16 additions & 1 deletion doc/src/atomvm-tooling.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ To use the [`atomvm_rebar3_plugin`](https://atomvm.github.io/atomvm_rebar3_plugi
* For flashing to ESP32, the [`esptool`](https://github.com/espressif/esptool) program.
* For flashing to STM32, `st-flash` via [stlink](https://github.com/stlink-org/stlink)
* (optional) A serial console program such as [minicom](https://en.wikipedia.org/wiki/Minicom) or [screen](https://en.wikipedia.org/wiki/GNU_Screen), to view console output from a device.
* (recommended) For rp2040, [`picotool`](https://github.com/raspberrypi/picotool) for software resets on Raspberry Pi Pico. (optionally used if found in PATH to disconnect active `screen` sessions, which normally prevent flashing)

### Erlang Example Program

Expand Down Expand Up @@ -227,7 +228,7 @@ $ rebar3 atomvm pico_flash

See the [`atomvm_rebar3_plugin`](https://atomvm.github.io/atomvm_rebar3_plugin) page for more detailed instructions about how to use the `pico_flash` target.

You can now use a serial console program such as [minicom](https://en.wikipedia.org/wiki/Minicom) or [screen](https://en.wikipedia.org/wiki/GNU_Screen) to view console output from a device.
You can now use a serial console program such as [minicom](https://en.wikipedia.org/wiki/Minicom) or [screen](https://en.wikipedia.org/wiki/GNU_Screen) to view console output from a device. The default build will wait 20 seconds for a serial connection to be established before starting the application.

###########################################################

Expand All @@ -249,6 +250,20 @@ You can now use a serial console program such as [minicom](https://en.wikipedia.
AtomVM finished with return value: ok
AtomVM application terminated. Going to sleep forever ...


If no connection is made before the timeout is reached the application will start, but the uart console will not be available. At this point you can use [`picotool`](https://github.com/raspberrypi/picotool) to reboot the device into `application` mode.

Example:

```shell
$ picotool reboot -f
The device was asked to reboot into application mode.

$
```

This will again give you 20 seconds to establish a serial monitor connection. For information about changing this timeout, or locking down the device so that software resets no longer work (requiring that the device be power cycled and the `BOOTSEL` button help when powering on to flash) consult the [rp2040 section](./build-instructions.md#building-for-raspberry-pi-pico) of the [Build Instructions](./build-instructions.md).

## `ExAtomVM`

The [`ExAtomVM`](https://github.com/atomvm/ExAtomVM) tool is a [mix](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html) plugin that can be used to create and flash [Elixir](https://elixir-lang.org) applications that run over AtomVM. Using this plugin greatly simplifies the process of building Elixir applications that run over AtomVM, and is strongly encouraged for new users.
Expand Down
4 changes: 4 additions & 0 deletions doc/src/build-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -769,6 +769,10 @@ $ ninja
You may want to build with option `AVM_REBOOT_ON_NOT_OK` so Pico restarts on error.
```

The default build configuration allows the device to be re-flashed with the `atomvm_rebar3_plugin` `atomvm pico_flash` task or restarting the application after exiting using [`picotool`](https://github.com/raspberrypi/picotool). This behaviour can be changed to hang the CPU when the application exits, so that power must be cycled to restart, and `BOOTSEL` must be held when power on to flash a new application. To disable software resets use `-DAVM_WAIT_BOOTSEL_ON_EXIT=off` when configuring `cmake`.

The 20 second default timeout for a USB serial connection can be changed using option `AVM_USB_WAIT_SECONDS`. The device can also be configured to wait indefinitely for a serial connection using the option `AVM_WAIT_FOR_USB_CONNECT=on`.

### libAtomVM build steps for Pico

Build of standard libraries is part of the generic unix build.
Expand Down
1 change: 1 addition & 0 deletions doc/src/getting-started-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,6 +277,7 @@ Deployment of AtomVM on the Raspberry Pico platform requires the following compo
* 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;
* (recommended) [`picotool`](https://github.com/raspberrypi/picotool), useful for resetting the device into `BOOTSEL` or `application` mode, optionally used by the `atomvm_rebar3_plugin` (if available in env $PATH) for disconnecting active `screen` sessions when attempting to flash when still connected.

### Deploying the Pico AtomVM virtual machine

Expand Down

0 comments on commit 3904a9a

Please sign in to comment.