mirror of
https://github.com/DarkFlippers/unleashed-firmware.git
synced 2025-12-13 05:06:30 +04:00
Wi-Fi Devboard documentation rework (#3944)
* New step-by-step documentation structure for Wi-Fi Devboard * Added a description of working under Windows * Added a description of switching Devboard operation mode (Black Magic, DAPLink) * The images for the documentation are uploaded to the CDN * The text in the sidebar, near the dolphin logo, changed from blue to black/white Co-authored-by: knrn64 <25254561+knrn64@users.noreply.github.com> Co-authored-by: Aleksandr Kutuzov <alleteam@gmail.com>
This commit is contained in:
Ruslan Nadyrshin
@@ -1,178 +1,80 @@
|
||||
# Get started with the Dev Board {#dev_board_get_started}
|
||||
|
||||
The Wi-Fi Developer Board serves as a tool to debug the Flipper Zero firmware. To debug the firmware, the initial step involves compiling the firmware from its source code. This process enables the debugging functionality within the firmware and generates all the necessary files required for debugging purposes.
|
||||
\image html https://cdn.flipperzero.one/Flipper_Zero_WiFi_developer_board_box_CDN.jpg width=700
|
||||
|
||||
> **NOTE:** Building and debugging the Flipper Zero firmware is fully supported on MacOS and Linux. Support for Windows is in beta test.
|
||||
Before you start using your Devboard, you need to prepare your Flipper Zero and Devboard for debugging. In this guide, we'll walk you through all the necessary steps and provide links to explore the Devboard's capabilities further.
|
||||
|
||||
***
|
||||
|
||||
## Updating the firmware of your Developer Board
|
||||
## Step 1. Enable Debug Mode on your Flipper Zero
|
||||
|
||||
Update the firmware of your Developer Board before using it. For more information, visit [Firmware update on Developer Board](https://docs.flipperzero.one/development/hardware/wifi-debugger-module/update).
|
||||
Since the main purpose of the Developer board is to debug applications on Flipper Zero, you first need to enable Debug Mode. To do so, go to **Settings → System** and set **Debug** to **ON**.
|
||||
|
||||
\image html https://cdn.flipperzero.one/Flipper_Zero_enamble_debug_CDN.jpg width=700
|
||||
|
||||
> [!note]
|
||||
> Debug Mode needs to be re-enabled after each update of Flipper Zero's firmware.
|
||||
|
||||
Debug Mode allows you to debug your apps for Flipper Zero, as well as access debugging options in apps via the user interface and CLI. To learn more about Flipper Zero CLI, visit [Command-line interface in Flipper Docs](https://docs.flipper.net/development/cli).
|
||||
|
||||
\image html https://cdn.flipperzero.one/Flipper_Zero_Command_Line_Interface_CDN.jpg width=700
|
||||
|
||||
***
|
||||
|
||||
## Installing Git
|
||||
## Step 2. Update firmware on the Developer Board
|
||||
|
||||
You'll need Git installed on your computer to clone the firmware repository. If you don't have Git, install it by doing the following:
|
||||
|
||||
* **MacOS**
|
||||
|
||||
On MacOS, install the **Xcode Command Line Tools** package, which includes Git as one of the pre-installed command-line utilities, by running in the Terminal the following command:
|
||||
|
||||
```text
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
* **Linux**
|
||||
|
||||
On Linux, you can install Git using your package manager. For example, on Ubuntu, run in the Terminal the following command:
|
||||
|
||||
```text
|
||||
sudo apt install git
|
||||
```
|
||||
|
||||
For other distributions, refer to your package manager documentation.
|
||||
The Developer Board comes with stock firmware that may not include all the latest features and bug fixes. To ensure optimal performance, please update your board's firmware using the instructions in [Firmware update on Devboard](#dev_board_fw_update).
|
||||
|
||||
***
|
||||
|
||||
## Building the firmware
|
||||
## Step 3. Plug the Devboard into Flipper Zero {#dev_board_get_started_step-3}
|
||||
|
||||
First, clone the firmware repository:
|
||||
Once your Developer Board firmware is up to date, you can proceed to plug it into your Flipper Zero. Two important things to keep in mind:
|
||||
|
||||
```text
|
||||
git clone --recursive https://github.com/flipperdevices/flipperzero-firmware.git
|
||||
cd flipperzero-firmware
|
||||
```
|
||||
1. **Power off your Flipper Zero before plugging in the Developer Board.**
|
||||
|
||||
Then, run the **Flipper Build Tool** (FBT) to build the firmware:
|
||||
If you skip this step, you may corrupt the data stored on the microSD card. Connecting external modules with a large capacitive load may affect the microSD card's power supply since both the microSD card and external module are powered from the same 3.3 V power source inside Flipper Zero.
|
||||
|
||||
```text
|
||||
./fbt
|
||||
```
|
||||
2. **Make sure the Developer Board is inserted all the way in.**
|
||||
|
||||
If your Flipper Zero isn't in a silicone case, insert the module all the way in so there is no gap between your Flipper Zero and the Devboard. You may need to apply more force to insert it completely. After that, press and hold the **BACK** button to power on your Flipper Zero.
|
||||
|
||||
\image html https://cdn.flipperzero.one/Flipper_Zero_external_module_without_case_CDN.jpg width=700
|
||||
|
||||
If your Flipper Zero is in a silicone case, insert the module all the way in so there is no gap in the middle between the silicone case and the module. After that, press and hold the **BACK** button to power on your Flipper Zero.
|
||||
|
||||
\image html https://cdn.flipperzero.one/Flipper_Zero_external_module_with_case_CDN.jpg width=700
|
||||
|
||||
***
|
||||
|
||||
## Connecting the Developer Board
|
||||
## Step 4. Connect to a computer
|
||||
|
||||
The Developer Board can work in the **Wired** mode and two **Wireless** modes: **Wi-Fi access point (AP)** mode and **Wi-Fi client (STA)** mode. The Wired mode is the simplest to set up, but requires a USB Type-C cable. The Wireless modes are more complex to set up, but they allow you to debug your Flipper Zero wirelessly.
|
||||
Now, you can connect the Developer Board to your computer via USB or Wi-Fi, depending on your needs. We described both methods in separate documents:
|
||||
|
||||
> **NOTE:** Use the following credentials when connecting to the Developer Board in **Wi-Fi access point** mode:\n
|
||||
Name: **blackmagic**\n
|
||||
Password: **iamwitcher**
|
||||
|
||||
## Wired
|
||||
|
||||
|
||||
|
||||
To connect the Developer Board in **Wired** mode, do the following:
|
||||
|
||||
1. Cold-plug the Developer Board by turning off your Flipper Zero and connecting the Developer Board, and then turning it back on.
|
||||
|
||||
2. On your computer, open the **Terminal** and run the following:
|
||||
|
||||
* **MacOS**
|
||||
|
||||
```text
|
||||
ls /dev/cu.*
|
||||
```
|
||||
|
||||
* **Linux**
|
||||
|
||||
```text
|
||||
ls /dev/tty*
|
||||
```
|
||||
|
||||
Note the list of devices.
|
||||
|
||||
3. Connect the Developer Board to your computer via a USB-C cable.
|
||||
|
||||
4. Rerun the command. Two new devices have to appear: this is the Developer Board.
|
||||
|
||||
> **NOTE:** If the Developer Board doesn't appear in the list of devices, try using a different cable, USB port, or computer.
|
||||
>
|
||||
> **NOTE:** Flipper Zero logs can only be viewed when the Developer Board is connected via USB. The option to view logs over Wi-Fi will be added in future updates. For more information, visit [Reading logs via the Dev Board](https://docs.flipperzero.one/development/hardware/wifi-debugger-module/reading-logs).
|
||||
|
||||
## Wireless
|
||||
|
||||
### Wi-Fi access point (AP) mode
|
||||
|
||||
|
||||
|
||||
Out of the box, the Developer Board is configured to work as a **Wi-Fi access point**. This means it'll create its own Wi-Fi network to which you can connect. If your Developer Board doesn't create a Wi-Fi network, it is probably configured to work in **Wi-Fi client** mode. To reset your Developer Board back to **Wi-Fi access point** mode, press and hold the **BOOT** button for 10 seconds, then wait for the module to reboot.
|
||||
|
||||
|
||||
|
||||
To connect the Developer Board in **Wi-Fi access point** mode, do the following:
|
||||
|
||||
1. Cold-plug the Developer Board by turning off your Flipper Zero and connecting the Developer Board, and then turning it back on.
|
||||
|
||||
2. Open Wi-Fi settings on your client device (phone, laptop, or other).
|
||||
|
||||
3. Connect to the network:
|
||||
|
||||
* Name: **blackmagic**
|
||||
|
||||
* Password: **iamwitcher**
|
||||
|
||||
4. To configure the Developer Board, open a browser and go to `http://192.168.4.1`.
|
||||
|
||||
### Wi-Fi client (STA) mode
|
||||
|
||||
|
||||
|
||||
To connect the Developer Board in **Wi-Fi client** mode, you need to configure it to connect to your Wi-Fi network by doing the following:
|
||||
|
||||
1. Cold-plug the Developer Board by turning off your Flipper Zero and connecting the Developer Board, and then turning it back on.
|
||||
|
||||
2. Connect to the Developer Board in **Wi-Fi access point** mode.
|
||||
|
||||
3. In a browser, go to the configuration page on `http://192.168.4.1`.
|
||||
|
||||
4. Select the **STA** mode and enter your network's **SSID** (name) and **password**. For convenience, you can click the **+** button to see the list of nearby networks.
|
||||
|
||||
5. Save the configuration and reboot the Developer Board.
|
||||
|
||||
|
||||
|
||||
After rebooting, the Developer Board connects to your Wi-Fi network. You can connect to the device using the mDNS name **blackmagic.local** or the IP address it got from your router (you'll have to figure this out yourself, every router is different).
|
||||
|
||||
After connecting to your debugger via <http://blackmagic.local>, you can find its IP address in the **SYS** tab. You can also change the debugger's mode to **AP** or **STA** there.
|
||||
|
||||
|
||||
- **[Via USB cable](#dev_board_usb_connection)** for debugging in DAP Link or Black Magic mode, and reading logs.
|
||||
- [Via Wi-Fi](#dev_board_wifi_connection) for debugging in Black Magic mode.
|
||||
|
||||
***
|
||||
|
||||
## Debugging the firmware
|
||||
## Next steps
|
||||
|
||||
Open the **Terminal** in the **flipperzero-firmware** directory that you cloned earlier and run the following command:
|
||||
You are ready to debug now! To further explore what you can do with the Devboard, check out these pages:
|
||||
|
||||
```text
|
||||
./fbt flash
|
||||
```
|
||||
- [Debugging via the Devboard](#dev_board_debugging_guide)
|
||||
- [Devboard debug modes](#dev_board_debug_modes)
|
||||
- [Reading logs via the Devboard](#dev_board_reading_logs)
|
||||
|
||||
These guides should help you get started with your Devboard. If you have any questions or you want to share your experience, don't hesitate to join our community on [Reddit](https://www.reddit.com/r/flipperzero/) and [Discord](https://discord.com/invite/flipper), where we have a dedicated #wifi-devboard channel.
|
||||
|
||||
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 using the [GDB](https://www.gnu.org/software/gdb/) debugger. We recommend using **VSCode** with the recommended extensions, and we have pre-made configurations for it.
|
||||
|
||||
To debug in **VSCode**, do the following:
|
||||
|
||||
1. In VSCode, 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. In the **Terminal**, run the `./fbt vscode_dist` command. This will generate the VSCode configuration files needed for debugging.
|
||||
|
||||
4. In VSCode, open the **Run and Debug** tab and select **Attach FW (blackmagic)** from the dropdown menu.
|
||||
|
||||
5. If needed, flash your Flipper Zero with the `./fbt flash` command, then click the **Play** 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 **Continue** button on the toolbar at the top of your VSCode window to continue execution.
|
||||
|
||||
|
||||
|
||||
To learn about debugging, visit the following pages:
|
||||
|
||||
* [Debugging with GDB](https://sourceware.org/gdb/current/onlinedocs/gdb.pdf)
|
||||
|
||||
* [Debugging in VS Code](https://code.visualstudio.com/docs/editor/debugging)
|
||||
|
||||
Reference in New Issue
Block a user