diff --git a/doc/src/atomvm-tooling.md b/doc/src/atomvm-tooling.md index f9c493750..4038a995b 100644 --- a/doc/src/atomvm-tooling.md +++ b/doc/src/atomvm-tooling.md @@ -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 @@ -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. ########################################################### @@ -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. diff --git a/doc/src/build-instructions.md b/doc/src/build-instructions.md index 6d31c4be0..80e6d19cf 100644 --- a/doc/src/build-instructions.md +++ b/doc/src/build-instructions.md @@ -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. diff --git a/doc/src/getting-started-guide.md b/doc/src/getting-started-guide.md index 838aadcec..10d03a145 100644 --- a/doc/src/getting-started-guide.md +++ b/doc/src/getting-started-guide.md @@ -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