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.

Signed-off-by: Winford <[email protected]>

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