flipperdevices · skotopes · Oct 14, 2024 · Oct 14, 2024 · Oct 14, 2024
@@ -0,0 +1,88 @@
+# Debugging via the Devboard {#dev_board_debugging_guide}
+
+On this page, you'll learn about how debugging via the Wi-Fi Developer Board works. To illustrate this process, we'll start a debug session for Flipper Zero's firmware in VS Code using the native Flipper Build Tool.
+
+***
+
+## Overview
+
+The Developer Board acts as the debug probe, which provides a bridge between the IDE (integrated development environment) with a debugger running on a host computer and the target microcontroller (in your Flipper Zero). The user controls the debugging process on the computer connected to the Developer Board via [Wi-Fi](#dev_board_wifi_connection) or [USB cable](#dev_board_usb_connection).
+
+\image html https://cdn.flipperzero.one/Flipper_Zero_WiFi_hardware_CDN.jpg width=700
+
+Data exchange between the Wi-Fi Developer Board and your Flipper Zero is conducted via the Serial Wire Debug interface. The following GPIO pins serve this purpose:
+
+- **Pin 10:** Serial Wire Clock (SWCLK)
+
+- **Pin 12:** Serial Wire Debug Data I/O (SWDIO)
+
+To learn more about Flipper Zero pinout, visit [GPIO & modules in Flipper Docs](https://docs.flipper.net/gpio-and-modules).
+
+***
+
+## Prerequisites
+
+### Step 1. Installing Git
+
+You'll need Git installed on your computer to clone the firmware repository. If you don't have Git, install it following the [official installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+
+### Step 2. Building the firmware
+
+Before starting debugging, you need to clone and build Flipper Zero firmware:
+
+1. Open the **Terminal** (on Linux & macOS) or **PowerShell** (on Windows) in the directory where you want to store the firmware source code.
+
+2. Clone the firmware repository:
+
+    ```
+    git clone --recursive https://github.com/flipperdevices/flipperzero-firmware.git
+    cd flipperzero-firmware
+    ```
+
+3. Run the **Flipper Build Tool (FBT)** to build the firmware:
+
+    ```
+    ./fbt
+    ```
+
+***
+
+## Debugging the firmware
+
+From the **flipperzero-firmware** directory that you cloned earlier, run the following command:
+
+```
+./fbt flash
+```
+
+This will upload the firmware you've just built to your Flipper Zero via the Developer Board. After that, you can start debugging the firmware. We recommend using **VS Code** with the recommended extensions (as described below), and we have pre-made configurations for it.
+
+To debug in **VS Code**, do the following:
+
+1. In VS Code, open the **flipperzero-firmware** directory.
+
+2. You should see a notification about recommended extensions. Install them.
+
+    If there were no notifications, open the **Extensions** tab, enter `@recommended` in the search bar, and install the workspace recommendations.
+
+3. Run the `./fbt vscode_dist` command. This will generate the VS Code configuration files needed for debugging.
+
+4. In VS Code, open the **Run and Debug** tab and select a debugger from the dropdown menu:
+
+    - **Attach FW (blackmagic):** Can be used via **Wi-Fi** or **USB**
+    - **Attach FW (DAP):** Can be used via **USB** only
+
+    Note that when debugging via USB, you need to make sure the selected debugger matches the debug mode on your Devboard. To check the debug mode on your Devboard, access the Devboard's web interface as described [here](#dev_board_wifi_connection) and check the **USB mode** field. If you want to use a different debug mode, enable this mode by following the steps in [Devboard debug modes](#dev_board_debug_modes).
+
+5. If needed, flash your Flipper Zero with the `./fbt flash` command, then click the ▷ **Start Debugging** button in the debug sidebar to start the debugging session.
+
+6. Note that starting a debug session halts the execution of the firmware, so you'll need to click the I▷ **Continue** button on the toolbar at the top of your VS Code window to continue execution.
+
+\image html https://cdn.flipperzero.one/Flipper_Zero_Wi-Fi_devboard_VS_Code.jpg width=900
+
+> [!note]
+> If you want to use a different debug mode on your Developer Board, visit [Devboard debug modes](#dev_board_debug_modes).
+>
+> If you want to read logs via the Developer Board, see [Reading logs via the Devboard](#dev_board_reading_logs).
+> 
+> To learn about debugging in VS Code, see [VS Code official guide](https://code.visualstudio.com/docs/editor/debugging).
@@ -0,0 +1,33 @@
+# Devboard debug modes {#dev_board_debug_modes}
+
+The Wi-Fi Devboard for Flipper Zero supports **Black Magic** and **DAPLink** debug modes, and you can switch between them depending on your needs. Note that available modes depend on connection:
+
+- **Wi-Fi:** Only **Black Magic** mode is available.
+- **USB:** Switch between **Black Magic** (default) and **DAPLink**. Learn more about switching debug modes for USB connection below.
+
+> [!note]
+> Black Magic mode doesn't support RTOS threads, but you can still perform other debugging operations.
+
+***
+
+## Switching debug modes for USB connection
+
+Switching debug modes for working via USB has to be done wirelessly (yes, you read that correctly). Additionally, depending on how the Devboard wireless connection is configured, you may need to follow different steps for **Wi-Fi access point mode** or **Wi-Fi client mode**:
+
+1. If the Devboard isn't connected to your Flipper Zero, turn off your Flipper Zero and connect the Developer Board, then turn the device back on.
+
+2. Access the Devboard's web interface:
+
+    - [Wi-Fi access point mode](#wifi-access-point)
+
+    - [Wi-Fi client mode](#wifi-client-mode)
+
+3. In the **WiFi** tab, click the **USB mode** option and select **BlackMagicProbe** or **DapLink**.
+
+4. Click **SAVE**, then click **REBOOT** to apply the changes.
+
+\image html https://cdn.flipperzero.one/Flipper_Zero_WiFi_devboard_switching_modes_CDN.jpg width=700
+
+> [!note]
+> After switching debug modes on your Devboard, remember to select the same debugger in **VS Code** in the **Run and Debug** tab, and click the ▷ **Start Debugging** button.
+
@@ -1,122 +1,112 @@
 # Firmware update on Developer Board {#dev_board_fw_update}
 
-It's important to regularly update your Developer Board to ensure that you have access to the latest features and bug fixes. This tutorial will guide you through the necessary steps to update the firmware of your Developer Board.
+It's important to regularly update your Developer Board to ensure that you have access to the latest features and bug fixes. This page will guide you through the necessary steps to update the firmware of your Developer Board.
 
-This tutorial assumes that you're familiar with the basics of the command line. If you’re not, please refer to the [Windows](https://www.digitalcitizen.life/command-prompt-how-use-basic-commands/) or [MacOS/Linux](https://ubuntu.com/tutorials/command-line-for-beginners#1-overview) command line tutorials.
+> [!note]
+> This guide assumes that you're familiar with the basics of the command line. If you're new to it, we recommend checking out these [Windows](https://learn.microsoft.com/en-us/powershell/scripting/learn/ps101/01-getting-started?view=powershell-7.4) or [macOS/Linux](https://ubuntu.com/tutorials/command-line-for-beginners#1-overview) command line tutorials.
 
 ***
 
-## Installing the micro Flipper Build Tool
+## Step 1. Install the micro Flipper Build Tool
 
-Micro Flipper Build Tool (uFBT) is a cross-platform tool that enables basic development tasks for Flipper Zero, such as building and debugging applications, flashing firmware, and creating VS Code development configurations.
+ is a cross-platform tool developed and supported by our team that enables basic development tasks for Flipper Zero, such as building and debugging applications, flashing firmware, creating VS Code development configurations, and flashing firmware to the Wi-Fi Developer Board.
 
-Install uFBT on your computer by running the following command in the Terminal:
+**On Linux & macOS:**
 
-**For Linux & macOS:**
+Run the following command in the Terminal:
 
-```text
+```
 python3 -m pip install --upgrade ufbt
 ```
 
-**For Windows:**
+**On Windows:**
 
-```text
-py -m pip install --upgrade ufbt
-```
+1. Download the latest version of Python on 
+2. Run the following command in the PowerShell
 
-If you want to learn more about uFBT, visit [the project's page](https://pypi.org/project/ufbt/).
+    ```
+    py -m pip install --upgrade ufbt
+    ```
 
 ***
 
-## Connecting the Developer Board to your computer
-
-1. List all of the serial devices on your computer.
-
-    **Windows**
-
-    On Windows, go to Device Manager and expand the Ports (COM & LPT) section.
+## Step 2. Connect the Devboard to PC
 
-    **macOS**
+To update the firmware, you need to switch your Developer Board to Bootloader mode, connect to a PC via a USB cable, and make sure that the PC detects the Developer Board:
 
-    On macOS, you can run the following command in the Terminal:
-
-    ```text
-    ls /dev/cu.*
-    ```
+1. List all of the serial devices on your computer.
 
-    **Linux**
+    - **macOS:** Run the `ls /dev/cu.*` command in the Terminal.
 
-    On Linux, you can run the following command in the Terminal:
+    - **Linux:** Run the `ls /dev/tty*` command in the Terminal.
 
-    ```text
-    ls /dev/tty*
-    ```
-
-    View the devices in the list.
+    - **Windows:** Go to **Device Manager** and expand the **Ports (COM & LPT)** section.
 
 2. Connect the Developer Board to your computer using a USB-C cable.
-![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/Aq7gfMI-m_5H6sGGjwb4I_monosnap-miro-2023-07-19-19-47-39.jpg)
-
-3. Switch your Developer Board to Bootloader mode:
 
-    3.1.  Press and hold the **BOOT** button.
+    \image html https://cdn.flipperzero.one/Flipper_Zero_Wi-Fi_devboard_update_wired_connection.jpg width=700
 
-    3.2.  Press the **RESET** button while holding the **BOOT** button.
-
-    3.3. Release the **BOOT** button.\
-![You can easily switch the Dev Board to Bootloader mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/KynP9iT6sJ3mXLaLyI82__image.png)
+3. Switch your Developer Board to Bootloader mode:
 
-4. Repeat Step 1 and view the name of your Developer Board that appeared in the list.
+    1. Press and hold the **BOOT** button.
+    2. Press the **RESET** button while holding the **BOOT** button.
+    3. Release the **BOOT** button.
 
-    For example, on macOS:
+    \image html https://cdn.flipperzero.one/Flipper_Zero_Wi-Fi_devboard_reboot_to_bootloader.png width=700
 
-    ```text
-    /dev/cu.usbmodem01
-    ```
+4. Repeat **Step 1** and view the name of your Developer Board that appeared in the list.
 
 ***
 
-## Flashing the firmware
+## Step 3. Flash the firmware
 
-To flash the firmware onto your Developer Board, run the following command in the terminal:
+**On Linux & macOS:**
 
-```text
+```
 python3 -m ufbt devboard_flash
 ```
 
+**On Windows:** Run the following command in the PowerShell:
+
+```
+py -m ufbt devboard_flash
+```
+
 You should see the following message: `WiFi board flashed successfully`.
 
-## If flashing failed
+### If flashing failed
 
-If you get an error message during the flashing process, such as this:
+Occasionally, you might get an error message during the flashing process, such as:
 
-```text
+```
 A fatal error occurred: Serial data stream stopped: Possible serial noise or corruption.
 ```
 
-Or this:
+*or*
 
-```text
+```
 FileNotFoundError: [Errno 2] No such file or directory: '/dev/cu.usbmodem01'
 ```
 
-Try doing the following:
+To fix it, try doing the following:
 
-* Disconnect the Developer Board from your computer, then reconnect it.
+- Disconnect the Developer Board from your computer, then reconnect it. After that, switch your Developer Board to Bootloader mode once again, as described in 
 
-* Use a different USB port on your computer.
+- Use a different USB port on your computer.
 
-* Use a different USB-C cable.
+- Use a different USB-C cable.
 
 ***
 
-## Finishing the installation
-
-After flashing the firmware:
+## Step 4. Finish the installation
 
 1. Reboot the Developer Board by pressing the **RESET** button.
-![Reset the Developer Board](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/rcQeKARgrVwa51tLoo-qY_monosnap-miro-2023-07-20-18-29-33.jpg)
+
+    \image html https://cdn.flipperzero.one/Flipper_Zero_Wi-Fi_devboard_reboot_after_flashing.jpg width=700
 
 2. Disconnect and reconnect the USB-C cable.
 
-The Developer Board should appear as a serial device on your computer. Now, you can use it with the Black Magic Debug client of your choice.
+    You've successfully updated the firmware of your Developer Board!
+
+If you followed the **Get started with the Devboard** guide, you're ready for the next step: [Step 3. Plug the Devboard into Flipper Zero](#dev_board_get_started_step-3).
+