Update README.md: add first use section

leonardocavagnis · web-flow · commit 5acb1681861e · 2024-10-21T16:17:08.000+02:00
diff --git a/README.md b/README.md
@@ -15,25 +15,68 @@ This repository contains the official implementation of **Arduino Core** for Zep
 ## ⚙️ Installation
 
 Install the core and its toolchains via Board Manager:
-* Download and install the latest [Arduino IDE](https://www.arduino.cc/en/software) (only versions `2.x.x` are supported)
-* Open the *'Settings / Preferences'* window
-* Open the *'Boards Manager'* from the side menu and search for *'Zephyr'*
-  * If it doesn’t appear, add the following URL to the *'Additional Boards Manager URLs'* field: `https://downloads.arduino.cc/packages/package_zephyr_index.json` (if you have multiple URLs, separate them with a comma)
-* Install the `Arduino Zephyr Boards` platform
+* Download and install the latest [Arduino IDE](https://www.arduino.cc/en/software) (only versions `2.x.x` are supported).
+* Open the *'Settings / Preferences'* window.
+* Open the *'Boards Manager'* from the side menu and search for *'Zephyr'*.
+  * If it doesn’t appear, add the following URL to the *'Additional Boards Manager URLs'* field: `https://downloads.arduino.cc/packages/package_zephyr_index.json` (if you have multiple URLs, separate them with a comma).
+* Install the `Arduino Zephyr Boards` platform.
 
 Alternatively, to install the core using the command line, run the following command with the Arduino CLI:
 
 ```bash
 arduino-cli core install arduino:zephyr --additional-urls https://downloads.arduino.cc/packages/package_zephyr_index.json
 ```
 
-## 🧢 Under the hood
+## 🏗️ First Use
+
+To get started with your board:
+* Put the board in bootloader mode by double-clicking the RESET button.
+* Run the `Burn Bootloader` option from the IDE/CLI.
+  * Note that due to limitations in the Arduino IDE, you may need to select any programmer from the `Programmers` menu.
+* Once the bootloader is installed, you can load your first sketch by placing the board into bootloader mode again.
+
+> [!NOTE]  
+> After the initial setup, future sketches will be loaded automatically without needing to reset the board.
+
+## 🔧 Troubleshooting
+
+### Common Issues
 
-Unlike traditional Arduino implementations, where the final output is a standalone binary loaded by a bootloader, this core generates a freestanding `elf` file. This file can be dynamically loaded by a precompiled Zephyr firmware, referred to as the `loader`.
+#### **Q: My Sketch doesn't start (Serial doesn't appear)**
+**A:** Connect a USB-to-UART adapter to the default UART (eg. TX0/RX0 on Giga, TX/RX on Nano) and read the error message (with the sketch compiled in `Default` mode). If you don't own a USB-to-UART adapter, compile the sketch in `Debug` mode; this will force the shell to wait until you open the Serial Monitor. Then, run `sketch` command and *probably* you'll be able to read the error (if generated by `llext`). For OS crashes, the USB-to-UART adapter is the only way to collect the crash.
 
-For the end user, installing the `loader` is easy. Simply run `Burn Bootloader` option from the IDE/CLI while the board is in bootloader mode (by double-clicking the RESET button). Note that due to limitations in the Arduino IDE, you may need to select any programmer from the `Programmers` menu.
+---
+
+#### **Q: I did it and I get the error: `<err> llext: Undefined symbol with no entry in symbol table ...`**
+**A:** This means you are trying to use a Zephyr function which has not yet been exported. Open `llext_exports.c`, add the function you need and recompile/upload the loader.
+
+---
+
+#### **Q: I want to use a Zephyr subsystem which is not compiled in**
+**A:** Open the `.conf` file for your board, add the required `CONFIG_`, recompile/upload the loader.
 
-To load the first sketch, the board must also be manually placed into bootloader mode. After this initial setup, the standard "autoload" method will take over for future sketches.
+---
+
+#### **Q: I get an OS crash, like `<err> os: ***** USAGE FAULT *****`**
+**A:** This is usually due to a buffer overflow or coding error in the user's own code. However, since the project is still in beta 🧪, a [good bug report](#bug-reporting) could help identify any issues in our code.
+
+---
+
+#### **Q: I get an out of memory error**
+**A:** Since collecting bug reports is very important at this time, we are keeping Zephyr's shell enabled to allow loading a full sketch (which requires a large stack). Adjust your board's `.conf` file to reduce the stack size if your platform doesn't have enough RAM.
+
+## 📚 Libraries
+
+### Included with the core: ###
+
+### Separately supplied: ###
+- **ArduinoBLE**: This library is enabled only for the Arduino Nano 33 BLE. Please use [this branch](https://github.com/facchinm/ArduinoBLE/tree/zephyr_hci) to test it.
+
+## 🧢 Under the hood
+
+Unlike traditional Arduino implementations, where the final output is a standalone binary loaded by a bootloader, this core generates a freestanding `elf` file. This file is dynamically loaded by a precompiled Zephyr firmware, referred to as the `loader`.
+
+The `loader` is responsible for managing the interaction between your sketches and the underlying Zephyr system. After the initial bootloader installation, the `loader` takes over the sketch loading process automatically.
 
 To ensure flexibility, the `loader` project is designed to be generic. Any necessary modifications for specific boards should be made in the corresponding `DTS overlay` or a special `fixup` file, using appropriate guards to maintain stability.
 
@@ -51,7 +94,7 @@ The most important components of this project are:
 
 ## 🛠️ Setup the environment
 
-In this section, we’ll guide you through setting up your environment to work with the core, making it easy to compile and upload your sketches to compatible boards.
+In this section, we’ll guide you through setting up your environment to work with the core.
 
 Shell scripts are available to simplify the installation process (Windows is not supported at the moment 😔).
 
@@ -76,7 +119,7 @@ Download and install the Zephyr SDK for your OS from [here](https://github.com/z
 
 ### Build the Loader
 
-To build a loader, run the following commands:
+To build the loader, run the following commands:
 ```bash
 export ZEPHYR_SDK_INSTALL_DIR=$folder_where_you_installed_the_sdk
 ./extra/build.sh $zephyr_board_name $arduino_variant_board_name
@@ -97,44 +140,10 @@ If the board is fully supported by Zephyr, you can flash the firmware directly o
 west flash
 ```
 
-## 🖥️ Using the Core in Arduino IDE/CLI
+### Using the Core in Arduino IDE/CLI
 
 After running the `bootstrap` script, you can symlink the core to `$sketchbook/hardware/arduino-git/zephyr`. Once linked, it will appear in the IDE/CLI, and the board's Fully Qualified Board Name (FQBN) will be formatted as `arduino-git:zephyr:name_from_boards_txt`.
 
-## 🔧 Troubleshooting
-
-### Common Issues
-
-#### **Q: My Sketch doesn't start (Serial doesn't appear)**
-**A:** Connect a USB-to-UART adapter to the default UART (eg. TX0/RX0 on Giga, TX/RX on Nano) and read the error message (with the sketch compiled in `Default` mode). If you don't own a USB-to-UART adapter, compile the sketch in `Debug` mode; this will force the shell to wait until you open the Serial Monitor. Then, run `sketch` command and *probably* you'll be able to read the error (if generated by `llext`). For OS crashes, the USB-to-UART adapter is the only way to collect the crash.
-
----
-
-#### **Q: I did it and I get the error: `<err> llext: Undefined symbol with no entry in symbol table ...`**
-**A:** This means you are trying to use a Zephyr function which has not yet been exported. Open `llext_exports.c`, add the function you need and recompile/upload the loader.
-
----
-
-#### **Q: I want to use a Zephyr subsystem which is not compiled in**
-**A:** Open the `.conf` file for your board, add the required `CONFIG_`, recompile/upload the loader.
-
----
-
-#### **Q: I get an OS crash, like `<err> os: ***** USAGE FAULT *****`**
-**A:** This is usually due to a buffer overflow or coding error in the user's own code. However, since the project is still in beta 🧪, a [good bug report](#bug-reporting) could help identify any issues in our code.
-
----
-
-#### **Q: I get an out of memory error**
-**A:** Since collecting bug reports is very important at this time, we are keeping Zephyr's shell enabled to allow loading a full sketch (which requires a large stack). Adjust your board's `.conf` file to reduce the stack size if your platform doesn't have enough RAM.
-
-## 📚 Libraries
-
-### Included with the core: ###
-
-### Separately supplied: ###
-- **ArduinoBLE**: This library is enabled only for the Arduino Nano 33 BLE. Please use [this branch](https://github.com/facchinm/ArduinoBLE/tree/zephyr_hci) to test it.
-
 ## 🚀 Adding a new target
 
 To add a new board that is already supported by mainline Zephyr, follow these steps:
