highperfocused/unleashed-firmware
1
0
Fork 0
mirror of https://github.com/DarkFlippers/unleashed-firmware.git synced 2025-10-11 01:02:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

[FL-870] Auto-generated firmware documentation take two (#2944)

Browse Source 
* Add doxygen and doxygen-awesome css, cleanup docs files
* Ignore more libraries and remove leftover local variables
* Create an actual intro page
* .md files linting
* Add doxygen action
* Fix Doxygen path
* Fix doxyfile path
* Try to upload
* Change docs branch
* Add submudules checkout
* Disable doxygen on PR
* Mention the firmware docs in the readme
* More dev docs mentions in the readme
* Fix runner group, add tags
* Test dev in PR
* Disable running on PR
* Fix a typo in the doxyfile
* Try upload to S3
* Fix local path
* Fix S3 ACL
* Add delete flag, unifying dev and tags
* Update ignored directories
* More ignored directories
* Even more ignored directories
* Fix submodule
* Change S3 uploader
* Change S3 uploader version
* Fix aws sync flags
* Fix ACL
* Disable ACL
* Improve ignores, add WiFi devboard docs
* TEMP: generate dev docs
* TEMP: generate 0.89.0 docs
* Disabling PR trigger
* Enable submodules and test build
* Enable test build
* Disable test build
* Change docs directory structure
* Fix accidentally committed submodule
* Fix submodules
* Update links to the developer documentation
* Markdown linting
* Update workflow, enable test build
* Fix doxygen dir path
* Update Doxyfile-awesome.cfg
* Change paths
* Fix upload docs path
* Disable pull_request debug trigger
* Disable tags building
* Remove autolinks and namespaces
* Establish basic documentation structure
* Add missing changes
* Improve stylesheet, move some files
* Improve examples
* Improve the main page
* Improve application dev docs
* Improve system programming docs
* Improve development tools docs
* Improve other docs
* Improve application examples
* Fix formatting
* Fix PVS-studio warnings
* Improve visuals
* Fix doxygen syntax warnings
* Fix broken links
* Update doxygen action

Co-authored-by: DrunkBatya <drunkbatya.js@gmail.com>
Co-authored-by: あく <alleteam@gmail.com>
Co-authored-by: Georgii Surkov <georgii.surkov@outlook.com>
Co-authored-by: Georgii Surkov <37121527+gsurkov@users.noreply.github.com>
This commit is contained in:
Astra
2024-03-06 08:25:21 +02:00
committed by GitHub
parent 5e47048369
commit ecab4d53d2
89 changed files with 1208 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
documentation/devboard/Firmware update on Developer Board.md Normal file
View File

@@ -0,0 +1,246 @@
# Firmware update on Developer Board {#dev_board_fw_update}
It's important to regularly update your Developer Board to keep it up to date. This tutorial will guide you through the necessary steps to successfully update the firmware of your Developer Board.
This tutorial assumes that you're familiar with the basics of the command line. If you’re unfamiliar with the command line, 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.
***
## Downloading the latest firmware
The first thing you need to do is to download the latest Developer Board firmware.
To get the latest pre-built firmware, do the following:
1. Go to the [Update Server page](https://update.flipperzero.one/builds/blackmagic-firmware).
![The Update Server page hosts different versions of the Developer Board firmware](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/gIXVO9VrE4LK05CmcMSSD_monosnap-miro-2023-07-19-17-36-23.jpg)
There, you can find the following version of the Developer Board firmware:
* **Release:** The most stable version of the firmware, which went through rigorous testing. The Release firmware version has the following format: **X.Y.Z/**, where X, Y, and Z are the build numbers. We recommend installing this version of the firmware.
* **Release-candidate:** The firmware version that hasn't been tested yet and may contain bugs. The Release-candidate firmware version has the following format: **X.Y.Z-rc/**, where X, Y, and Z are the build numbers.
* **Development:** The firmware version which builds every day and contains the latest features but might be unstable.
2. Open the folder with the latest Release firmware and download the `blackmagic-firmware-s2-full-X.Y.Z.tgz` file.
***
## Extracting the firmware
After downloading the firmware archive, extract it into a folder:
* On Windows, you can use any archive manager for this, for example, [7-Zip](https://www.7-zip.org/).
* On MacOS and Linux, you can use the `tar` command:
```text
tar -xzf blackmagic-firmware-s2-full-X.Y.Z.tgz -C <destination_directory>
```
Don't forget to replace `X.Y.Z` with the actual version number and set the destination directory!
***
## Installing the prerequisites for flashing
Install the tools below if you haven't already.
### Python
Download and install [Python3](https://www.python.org/downloads/). Make sure to check the “Add Python to PATH” option during installation.
### pip
To install the pip package manager, run the following command in the Terminal:
```text
python3 -m ensurepip --upgrade
```
If this command fails, please refer to the [official pip documentation](https://pip.pypa.io/en/stable/installation/) for alternative installation methods.
### esptool
esptool is a command-line utility for flashing ESP8266 and ESP32 microcontrollers, including the ESP32-S2 in your Developer Board.
To install esptool, run the following command in the Terminal:
```text
pip3 install esptool
```
If this command fails, try using **pip** instead of **pip3**. If this didn’t help, please refer to the [official esptool installation manual](https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html).
***
## 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.
* ***macOS***
On macOS, you can run the following command in the Terminal:
```text
ls /dev/cu.*
```
* ***Linux***
On Linux, you can run the following command in the Terminal:
```text
ls /dev/tty*
```
View the devices in the list.
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.
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)
4. Repeat Step 1 and view the name of your Developer Board that appeared in the list.
For example, on macOS:
```text
/dev/cu.usbmodem01
```
***
## Flashing the firmware
### Getting the flash command
1. Run the Terminal and navigate to the folder with the extracted firmware.
2. Run the following command to read the file with the flash command:
```text
cat flash.command
```
If you see a similar output, you can proceed to the Flashing step:
```text
esptool.py -p (PORT) -b 460800 --before default_reset --after hard_reset --chip esp32s2 write_flash --flash_mode dio --flash_freq 80m --flash_size 4MB 0x1000 bootloader.bin 0x10000 blackmagic.bin 0x8000 partition-table.bin
```
Don't use the exact command above for your Developer Board in the next step since it's just an example and may not match your firmware version!
If you get an error, ensure you’re in the correct directory and extracted the firmware archive correctly.
***
### Flashing
1. Copy the command you got from the previous step and replace the `(PORT)` part with the name of the serial device you learned earlier.
For Windows, replace `(PORT)` with the COM port number—for example, `COM3`.
2. Run the command in the Terminal.
Your command should look similar to this:
```text
esptool.py -p /dev/cu.usbmodem01 -b 460800 --before default_reset --after hard_reset --chip esp32s2 write_flash --flash_mode dio --flash_freq 80m --flash_size 4MB 0x1000 bootloader.bin 0x10000 blackmagic.bin 0x8000 partition-table.bin
```
If you get an error, ensure that you’ve entered the correct serial device name and that the Developer Board is in Bootloader mode.
3. Wait till the firmware flashing is over. The flashing process takes about 30 seconds.
The Terminal output should look similar to this:
```text
esptool.py v4.6.1
Serial port /dev/cu.usbmodem01
Connecting...
Chip is ESP32-S2 (revision v0.0)
Features: WiFi, No Embedded Flash, No Embedded PSRAM, ADC and temperature sensor
calibration in BLK2 of efuse V2
Crystal is 40MHz
MAC: 00:11:22:33:44:55
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Changed.
Configuring flash size...
Flash will be erased from 0x00001000 to 0x00004fff...
Flash will be erased from 0x00010000 to 0x000ecfff...
Flash will be erased from 0x00008000 to 0x00008fff...
Compressed 13248 bytes to 9298...
Wrote 13248 bytes (9298 compressed) at 0x00001000 in 0.3 seconds (effective 402.7 kbit/s)...
Hash of data verified.
Compressed 904288 bytes to 562550...
Wrote 904288 bytes (562550 compressed) at 0x00010000 in 6.7 seconds (effective 1076.5 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 124...
Wrote 3072 bytes (124 compressed) at 0x00008000 in 0.1 seconds (effective 360.8 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting via RTS pin...
```
If the Terminal output has these two lines at the end, your Developer Board has been successfully updated:
```text
Leaving...
Hard resetting via RTS pin...
```
If you get this warning, you can safely ignore it:
```text
WARNING: ESP32-S2 (revision v0.0) chip was placed into download mode using GPIO0.
esptool.py can not exit the download mode over USB. To run the app, reset the chip manually.
To suppress this note, set --after option to 'no_reset
```
#### If flashing failed
If you 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
```text
FileNotFoundError: [Errno 2] No such file or directory: '/dev/cu.usbmodem01'
```
Try doing the following:
* Disconnect the Developer Board from your computer, then reconnect it.
* Use a different USB port on your computer.
* Use a different USB-C cable.
***
## Finishing the installation
After flashing the firmware, you can 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)
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.

175
documentation/devboard/Get started with the Dev Board.md Normal file
View File

@@ -0,0 +1,175 @@
# 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.
> **NOTE:** Building and debugging the Flipper Zero firmware is fully supported on MacOS and Linux. Support for Windows is in beta test.
***
## Updating the firmware of your Developer Board
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).
***
## Installing Git
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.
***
## Building the firmware
First, clone the firmware repository:
```text
git clone --recursive https://github.com/flipperdevices/flipperzero-firmware.git
cd flipperzero-firmware
```
Then, run the **Flipper Build Tool** (FBT) to build the firmware:
```text
./fbt
```
***
## Connecting the Developer Board
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.
> **NOTE:** Use the following credentials when connecting to the Developer Board in **Wi-Fi access point** mode: Name: **blackmagic**, Password: **iamwitcher**
## Wired
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/jZdVlRTPVdSQVegzCyXp7_monosnap-miro-2023-06-22-16-28-06.jpg)
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
![The Developer Board in Wi-Fi access point mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/tKRTMHAuruiLSEce2a8Ve_monosnap-miro-2023-06-22-16-39-17.jpg)
Out of the box, the Developer Board is configured to work as a **Wi-Fi access point**. This means it will 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.
![You can reconfigure the Developer Board mode by pressing and holding the BOOT button](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/57eELJsAwMxeZCEA1NMJw_monosnap-miro-2023-06-22-20-33-27.jpg)
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
![The Developer Board in Wi-Fi client mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/xLQpFyYPfUS5Cx0uQhrNd_monosnap-miro-2023-06-23-12-34-36.jpg)
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.
![In the Wi-Fi tab, you can set the Developer Board mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/klbLVj8lz2bEvm7j4wRaj_monosnap-miro-2023-06-23-13-06-32.jpg)
After rebooting, the Developer Board connects to your Wi-Fi network. You can connect to the device using the mDNS name [blackmagic.local](http://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 [blackmagic.local](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.
![In the SYS tab, you can view the IP address of your Developer Board](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/5XbUptlfqzlV0p6hRUqiG_monosnap-miro-2023-06-22-18-11-30.jpg)
***
## Debugging the firmware
Open the **Terminal** in the **flipperzero-firmware** directory that you cloned earlier and run the following command:
```text
./fbt flash_blackmagic
```
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_blackmagic` 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.
![Click Continue in the toolbar to continue execution of the firmware](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/lp8ygGaZ3DvWD3OSI9yGO_monosnap-miro-2023-06-23-17-58-09.jpg)
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)

152
documentation/devboard/Reading logs via the Dev Board.md Normal file
View File

@@ -0,0 +1,152 @@
# Reading logs via the Dev Board {#dev_board_reading_logs}
The Developer Board allows you to read Flipper Zero logs via UART. Unlike reading logs via the command-line interface (CLI), the Developer Board enables you to collect logs from the device directly to a serial console independently from the operating system of Flipper Zero. It allows you to see the device's logs when it's loading, updating, or crashing. It's useful for debugging and troubleshooting during software development.
> **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.
## Setting the log level
Depending on your needs, you can set the log level by going to Main Menu -> Settings -> Log Level. To learn more about logging levels, visit [Settings](https://docs.flipperzero.one/basics/settings#d5TAt).
![You can manually set the preferred log level](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/INzQMw8QUsG9PXi30WFS0_monosnap-miro-2023-07-11-13-29-47.jpg)
***
## Viewing Flipper Zero logs
Depending on your operating system, you need to install an additional application on your computer to read logs via the Developer Board:
### MacOS
On MacOS, you need to install the **minicom** communication program by doing the following:
1. [Install Homebrew](https://brew.sh/) by running in the Terminal the following command:
```text
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
2. After installation of Homebrew, run the following command to install minicom:
```text
brew install minicom
```
After installation of minicom on your macOS computer, you can connect to the Developer Board to read Flipper Zero logs by doing the following:
1. Cold-plug the Developer Board into your Flipper Zero by turning off the Flipper Zero, connecting the developer board, and then turning it back on.
2. On your computer, open the Terminal and run the following command:
```text
ls /dev/cu.*
```
Note the list of devices.
3. Connect the developer board to your computer using a USB Type-C cable.\
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/iPpsMt2-is4aIjiVeFu5t_hjxs2i1oovrnps74v5jgsimage.png)
4. Rerun the command. Two new devices have to appear: this is the Developer Board.
```text
/dev/cu.usbmodemblackmagic1
/dev/cu.usbmodemblackmagic3
```
Your Developer Board might have different names.
5. Run the following command:
```text
minicom -D /dev/<port> -b 230400
```
Where `<port>` is the name of your device with a bigger number.
Example:
```text
minicom -D /dev/cu.usbmodemblackmagic3 -b 230400
```
6. View logs of your Flipper Zero in the Terminal.
7. To quit, close the minicom window or quit via the minicom menu.
### Linux
On Linux, you need to install the **minicom** communication program. For example, on Ubuntu, run in the Terminal the following command:
```text
sudo apt install minicom
```
After installation of minicom on your Linux computer, you can connect to the Developer Board to read Flipper Zero logs by doing the following:
1. Cold-plug the Developer Board into your Flipper Zero by turning off the Flipper Zero, connecting the developer board, and then turning it back on.
2. On your computer, open the Terminal and run the following command:
```text
ls /dev/tty*
```
Note the list of devices.
3. Connect the developer board to your computer using a USB Type-C cable.
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/iPpsMt2-is4aIjiVeFu5t_hjxs2i1oovrnps74v5jgsimage.png)
4. Rerun the command. Two new devices have to appear: this is the Developer Board.
```text
/dev/ttyACM0
/dev/ttyACM1
```
Your Developer Board might have different names.
5. Run the following command:
```text
minicom -D /dev/<port> \-b 230400
```
Where `<port>` is the name of your device with a bigger number.
Example:
```text
minicom -D /dev/ttyACM1 \-b 230400
```
6. View logs of your Flipper Zero in the Terminal.
> **NOTE:** If no logs are shown in the Terminal, try running the command from Step 5 with another device name.
7. To quit, close the minicom window or quit via the minicom menu.
### Windows
On Windows, do the following:
1. On your computer, [install the PuTTY application](https://www.chiark.greenend.org.uk/\~sgtatham/putty/latest.html).
2. Cold-plug the Developer Board into your Flipper Zero by turning off the Flipper Zero, connecting the developer board, and then turning it back on.
3. Connect the developer board to your computer using a USB Type-C cable.
![The Developer Board in Wired mode](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/iPpsMt2-is4aIjiVeFu5t_hjxs2i1oovrnps74v5jgsimage.png)
4. Find the serial port that the developer board is connected to by going to **Device Manager -> Ports (COM & LPT)** and looking for a new port that appears when you connect the Wi-Fi developer board.
![Go to Device Manager -> Ports (COM & LPT)](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/KKLQJK1lvqmI5iab3d__C_image.png)
5. Run the PuTTY application and select **Serial** as the connection type.
6. Enter the port number you found in the previous step into the **Serial line** field.
7. Set the **Speed** parameter to **230400** and click **Open**.
![Set the required parameters](https://archbee-image-uploads.s3.amazonaws.com/3StCFqarJkJQZV-7N79yY/ROBSJyfQ_CXiy4GUZcPbs_monosnap-miro-2023-07-12-13-56-47.jpg)
8. View logs of your Flipper Zero in the PuTTY terminal window.
9. To quit, close the PuTTY window.