Merge pull request #1075 from UncleGrumpy/docs_pico_cmake

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

Author: bettio

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.

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.

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