flipperzero-firmware Documentation

1. Project Overview & Quickstart (flipperdevices/flipperzero-firmware) Copy Chapter

1. Project Overview & Quickstart (flipperdevices/flipperzero-firmware) Copy Chapter

flipperzero-firmware

Flipper Zero firmware source code

Repository Details Copy Section

• Repository: flipperdevices/flipperzero-firmware
• GitHub Stars: ⭐ 16,272
• Primary Language: C

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (flipperdevices/docs) Copy Chapter

Flipper Zero Docs

Participation Copy Chapter

To fix a bug or add something new to this repository, you need to open a pull-request. Also,
on every page of the site, there is an edit icon (pencil) to the right of the header.

I18N and `shared` folder Copy Section

• Put assets, custom HTMLs, scripts, and stylesheets to shared until they're language-specific
• Keep the navigation structure the same for all languages* so the language selector can work properly

Creating a new document Copy Section

After creating a new document, add it to the nav: block in the language-specific mkdocs.yml.

Writing Copy Section

Documents are written in Markdown. Material for Mkdocs and Mkdocs docs might help you showing what blocks are supported.

Assets Copy Section

All images, videos, and other assets must be uploaded to the assets folder.

GIFs, Videos and screenshots Copy Section

We have some custom macros to embed "gifs" and videos.

To embed a "gif" (autoplayable silent MP4 video), use:

{{ gif("/assets/example-gif-file-name.mp4") }}

To embed a video, use:

{{ video("/assets/example-video-file-name.mp4") }}

To embed a Flipper Zero screenshot, use:

{{ screenshot("/assets/example-screenshot.png") }}

The screenshot should be 128*64 PNG with transparent background.

Live MkDocs server Copy Chapter

You can run mkdocs server locally and render changes on the fly while editing.

macOS Copy Chapter

1. brew install yq rsync

2. Install mkdocs insiders version if you have a token:

   pip3 install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git

   pip3 install mkdocs-macros-plugin mkdocs-git-revision-date-localized-plugin mkdocs-smart-meta-plugin

OR onstall public version

pip3 install mkdocs-material mkdocs-macros-plugin mkdocs-git-revision-date-localized-plugin mkdocs-smart-meta-plugin

3. Run python3 ./serve.py being in the root directory
4. Proceed to http://localhost:8000

P.S. If you use publoc version of mkdocs the live preview might look a bit different to production, because we use mkdocs-material-insiders version.

Linux Copy Chapter

TODO

Windows Copy Chapter

TODO

2. Official Technical Reference & Guides (flipperdevices/docs) Copy Chapter

File: README.md Copy Chapter

Flipper Zero Docs

Participation Copy Chapter

To fix a bug or add something new to this repository, you need to open a pull-request. Also,
on every page of the site, there is an edit icon (pencil) to the right of the header.

I18N and `shared` folder Copy Section

• Put assets, custom HTMLs, scripts, and stylesheets to shared until they're language-specific
• Keep the navigation structure the same for all languages* so the language selector can work properly

Creating a new document Copy Section

After creating a new document, add it to the nav: block in the language-specific mkdocs.yml.

Writing Copy Section

Documents are written in Markdown. Material for Mkdocs and Mkdocs docs might help you showing what blocks are supported.

Assets Copy Section

All images, videos, and other assets must be uploaded to the assets folder.

GIFs, Videos and screenshots Copy Section

We have some custom macros to embed "gifs" and videos.

To embed a "gif" (autoplayable silent MP4 video), use:

{{ gif("/assets/example-gif-file-name.mp4") }}

To embed a video, use:

{{ video("/assets/example-video-file-name.mp4") }}

To embed a Flipper Zero screenshot, use:

{{ screenshot("/assets/example-screenshot.png") }}

The screenshot should be 128*64 PNG with transparent background.

Live MkDocs server Copy Chapter

You can run mkdocs server locally and render changes on the fly while editing.

macOS Copy Chapter

1. brew install yq rsync

2. Install mkdocs insiders version if you have a token:

   pip3 install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git

   pip3 install mkdocs-macros-plugin mkdocs-git-revision-date-localized-plugin mkdocs-smart-meta-plugin

OR onstall public version

pip3 install mkdocs-material mkdocs-macros-plugin mkdocs-git-revision-date-localized-plugin mkdocs-smart-meta-plugin

3. Run python3 ./serve.py being in the root directory
4. Proceed to http://localhost:8000

P.S. If you use publoc version of mkdocs the live preview might look a bit different to production, because we use mkdocs-material-insiders version.

Linux Copy Chapter

TODO

Windows Copy Chapter

TODO

File: en/content/development/mechanics/blueprints.md Copy Chapter

Mechanical Blueprints

Uncased External Module Copy Chapter

Flipper Zero Uncased Ext. Module Drawing.pdf

File: en/content/development/hardware/devboard-stlinkV3.md Copy Chapter

Developer board with ST-Link V3

This is a devboard for advanced developers, who need in-circuit debug. It is based on ST-Link V3 Mini, and differs only in form factor and ease of connection. Some unused ST-Link and Flipper Zero pins are broken out additionally.

!!! warning "You do not need this board to update Flipper Zero"
You can update the firmware, develop and upload your own firmware to Flipper Zero via USB without this devboard! It is only needed for in-circuit debug while firmware is running using GDB/OpenOCD/etc. If you don't know exactly how to use it, you don't need this board.

Specifications Copy Chapter

• ST-Link V3 Mini for firmware flashing and in-circuit debug
• Built-in UART to USB, connected to Flipper Zero's UART (GPIO 13, 14)
• Unused Flipper Zero pins are broken out for debug and prototyping

Schematic and BOM Copy Chapter

{{ altium("0ec64b13-433d-419c-8d70-d2e84bef7532") }}

Altium Designer project sources Copy Chapter

github.com/Flipper-Zero/flipperzero-devboard-stlinkv3

File: en/content/development/hardware/schematic.md Copy Chapter

Circuit Diagrams

These are circuit diagrams of all Flipper Zero PCBs. They could be useful for hardware module developers and for low-level debug. These schematics are for educational purposes only and can't be treated as production documentation.

!!! warning "Schematics are stripped"
All Flipper Zero schematics are published below, but values of some passive components are ommited to complicate device cloning before official release.

Main PCB Copy Chapter

Main blocks overview Copy Section

Every block is shown in detail as a separate document below.
{{ altium("77b5e9f1-7fd1-47b2-879b-42631ccf1aeb") }}

Power Copy Section

Power management system for all components.
{{ altium("a41279af-a514-4eef-b0e6-caffcecea7d5") }}

Periphery Copy Section

{{ altium("1c1704de-b682-4693-88e0-74342e87bb44") }}

MCU STM32WB55 Copy Section

{{ altium("eb69a746-c7bf-4301-9a4b-906995425d9c") }}

LCD Display Copy Section

{{ altium("3ad3a937-2a28-4678-bfc4-36e5a1f72d8b") }}

Sub-1 GHz CC1101 Copy Section

{{ altium("c28de394-dc04-4c0d-8d9a-ba7cc9b5a9d8") }}

Buttons Copy Section

{{ altium("d0bcb592-ee4c-4912-9167-e34b86a9e4f9") }}

iButton PCB Copy Chapter

Piezo speaker and IR are also placed on this PCB.

{{ altium("3d9c4181-e623-4504-b520-bfef6ba96cef") }}

NFC PCB Copy Chapter

This PCB contains RFID 125 KHz and NFC modules.

NFC blocks overview Copy Section

{{ altium("da79a091-8e8b-46df-9398-45f1dfcffa6e") }}

NFC Copy Section

{{ altium("308a6997-56f9-40aa-825d-5b77a3d98f39") }}

RFID PERIPHERY Copy Section

{{ altium("06f61470-8f77-449f-8930-46659635d796") }}

RFID_iBTN Copy Section

{{ altium("bd11bd9a-85e3-4f0d-bd8e-9ed7057658b8") }}

RFID Antenna PCB Copy Chapter

File: en/content/development/firmware/cli.md Copy Chapter

Flipper Zero has its own command line interface, which might be useful for automated testing or remote control.

Connection Copy Chapter

Connect your Flipper Zero to the PC over USB. Your host will detect a virtual COM-port:

This COM-port does not require a special driver and is accessible on most modern operating systems.

You will need any terminal client to open the port: screen, minicom, etc. No additional setup required except choosing the right port.

For example, the port name in macOS starts with /dev/tty.usbmodem:

It is /dev/tty.usbmodem2069315E544E1 in our case.

To connect to the CLI using screen substitute your port name and enter this command in the shell:

screen /dev/tty.usbmodem2069315E544E1

You will see command prompt and firmware build information:

Commands Copy Chapter

Basic Copy Section

Power and Boot Copy Section

User Interface Copy Section

GPIO Copy Section

SD Card Copy Section

NFC Copy Section

Bluetooth Copy Section

Applications Launcher Copy Section

Any app could be launched using a command prefixed with app_, for example app_iButton.

See more in the help command output.

File: en/content/usage/general/first-boot.md Copy Chapter

Flipper Zero comes in transportation mode, meaning it's turned off.

{{ gif("assets/how-to-power-on.mp4") }}

Press and hold :flp-btn-back: for a second to turn it on.

File: en/content/usage/general/flashing-firmware.md Copy Chapter

Download latest firmware Copy Chapter

Click the image to download latest build of full firmware:
{: width="400"}

Enter DFU Mode Copy Chapter

DFU means Device Firmware Update.

{{ gif("assets/how-to-dfu.mp4") }}

To enter DFU Mode:

1. Press and hold :flp-btn-left: + :flp-btn-back:, just like for reboot, then wait a second
2. Release :flp-btn-back:, but keep holding :flp-btn-left: for one more second
3. Release :flp-btn-left:

The display should turn off, and the LED lights up in blue color, meaning you are in DFU Mode.

Connect your Flipper Zero to the PC over USB.

Flash in Windows Copy Chapter

Fix drivers Copy Section

This step has to be done just once.

As you can see, our Flipper Zero appeared as DFU in FS Mode, and we need to install a compatible driver.

Go to Windows Update Centre -> View optional updates.

Find STMicroelectronics in driver updates, select it and press Download and install.

Check that the name of the device in Device Manager has changed to STM Device in DFU Mode.
In some cases, PC reboot is required.

Install DfuSeDemo Copy Section

This step has to be done just once.

DfuSeDemo is required to flash Flipper Zero in Windows.

Click the link, download it for free and install.

The website will ask you to register to download the software, that's okay.

Flashing Copy Section

Launch DfuSeDemo and select STM Device in DFU Mode in the top section of the app.

After that, choose 00 Internal Flash 256 sectors… section in targets table.

Next, click Choose in the bottom of the window and select the firmware file you downloaded on the first step.

Press Upgrade and click “Yes” in pop-up window.

Reboot Flipper Zero after successful upgrade.

Flash in macOS/Linux Copy Chapter

Install dfu-util Copy Section

dfu-util is currently required to flash Flipper Zero firmware via USB-C port.

You can skip this part if you have dfu-util installed.

=== "macOS"
Install Homebrew if you don't have it:
sh /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install `dfu-util`:
``` sh
brew install dfu-util
```

=== "Ubuntu/Debian"
sh sudo apt-get install dfu-util
=== "Fedora"
sh sudo yum install dfu-util
=== "Arch"
sh sudo pacman -Sy dfu-util
=== "Linux Sources"
You can always build dfu-util from sources.

Upload firmware Copy Section

Run this command in the terminal to upload new firmware:

dfu-util -a 0 -D full.dfu

After flashing the firmware, reboot to exit DFU mode.

The USB cable can be unplugged before or after rebooting.

File: en/content/usage/general/rebooting.md Copy Chapter

If your Flipper Zero hangs, you can always restart it with a simple shortcut.

{{ gif("assets/how-to-reboot.mp4") }}

Press and hold :flp-btn-left: + :flp-btn-back: for a second to reboot it.

File: en/content/usage/applications/power.md Copy Chapter

Flipper Zero has a power management system, which mainly consists of fuel gauge and charger ICs.

The main goal of the fuel gauge is to monitor the battery charging level. It works by calculating the incoming and spent energy precisely.

Charger IC controls the charging process, which is very important for battery life and user safety.

Power state application obtains information from these ICs and shows it on display. Let's examine each line of that information.

Review Copy Chapter

=== "Not charging"
{{ screenshot("assets/applications/power-charging-off.png") }}
=== "Charging"
{{ screenshot("assets/applications/power-charging-on.png") }}

Current Copy Section

The first value is current, reported by fuel gauge (consumed by the battery). While Flipper is not charging, the value is negative and shows current consumption.

The second value is the charging current, reported by the charger IC. It goes up as the charging starts.

Voltage Copy Section

This line shows current voltage levels: from the fuel gauge and from the charger respectively.

!!! warning
The voltage level given by the charger is correct only during the charging process.

Charge Copy Section

The current battery level is shown on this line in percentage.

It's calculated by the fuel gauge using the value of energy consumed by the battery during charging, and spent during the device usage.

Capacity Copy Section

The first value on this line shows energy left in the battery, and the second one shows its full capacity.

The remaining energy can be calculated correctly only if the installed battery has the same full capacity value that was set during fuel gauge calibration.

!!! warning
As seen on the screenshot above, some testing units might report that the full capacity is 3000 mAh, which is wrong and leads to battery level miscalculations. The real capacity is 2000 mAh.

Temperature Copy Section

The last line shows the fuel gauge and the battery Celsius temperatures respectively.

The battery temperature is measured using NTC thermistor, which is placed on the battery and connected to the charger IC. It changes its resistance depending on the temperature.

File: en/content/index.md Copy Chapter

template: home.html
hide:
- navigation
- toc

{% for nav_item in config.extra.home %}
  <li>
    <aside>
      {{ '' % nav_item.img }}
    </aside>

    <main>
      <h2>{{ nav_item.title.en }}</h2>
      
      {% for item in nav_item.children %}
        <li>
          [{{ item.title.en }}]({{ item.path }})
        </li>
      {% endfor %}
      
    </main>
  </li>
{% endfor %}