flipperdevices/flipperzero-ufbt

Compact tool for building and debugging applications for Flipper Zero.

uFBT - micro Flipper Build Tool

uFBT is a cross-platform tool for building applications for Flipper Zero. It is a simplified version of Flipper Build Tool (FBT).

uFBT has an official GitHub Action. With it, you can automate building and publishing your application using GitHub workflows.

uFBT enables basic development tasks for Flipper Zero, such as building and debugging applications, flashing firmware, creating VSCode development configurations. It uses prebuilt binaries and libraries, so you don't need to build the whole firmware to compile and debug your application for Flipper.

Installation

• Linux & macOS: python3 -m pip install --upgrade ufbt
• Windows: py -m pip install --upgrade ufbt

uFBT uses your system's Python for running bootstrap code. Minimal supported version is Python 3.8. For executing actual build tasks, uFBT will download and use its own Python binaries and a toolchain built for your platform.

On first run, uFBT will download and install required SDK components from release update channel of official firmware. For more information on how to switch to a different version of the SDK, see Managing the SDK section.

Using pyenv

If you are using pyenv to manage python versions, after installation you may need to run pyenv rehash to generate shim for ufbt command.

Usage

Building & running your application

Run ufbt in the root directory of your application (the one with application.fam file in it). It will build your application and place the resulting binary in dist subdirectory.

You can upload and start your application on Flipper attached over USB using ufbt launch.

To see other available commands and options, run ufbt -h.

Debugging

In order to debug your application, you need to be running the firmware distributed alongside with current SDK version. You can flash it to your Flipper using ufbt flash (using a supported SWD probe), ufbt flash_usb (over USB).

For other flashing and debugging options, see ufbt -h.

VSCode integration

uFBT provides a configuration for VSCode that allows you to build and debug your application directly from the IDE. To deploy it, run ufbt vscode_dist in the root directory of your application. Then you can open the project in VSCode (File-Open Folder...) and use the provided launch (ctrl+shift+b) & debugging (ctrl+shift+d) configurations.

Application template

uFBT can create a template for your application. To do this, run ufbt create APPID=<app_id> in the directory where you want to create your application. It will create an application manifest and its main source file. You can then build and debug your application using the instructions above.

Application manifests are explained in the FBT documentation.

Other

• ufbt cli starts a CLI session with the device;
• ufbt lint, ufbt format run clang-format on application's sources;
• You can temporarily add toolchain binaries (compiler, linter, OpenOCD and others) to your PATH. See ufbt --help for more information.

Managing the SDK

To update the SDK, run ufbt update. This will download and install all required SDK components from previously used source.

• To switch to SDK for a different release channel, run ufbt update --channel=[dev|rc|release].
  • uFBT also supports 3rd-party update indexers, following the same schema as official firmware. To use them, run ufbt update --index-url=<url>, where <url> is a URL to the index file, e.g. https://update.flipperzero.one/firmware/directory.json.
• To use SDK for a certain release or a not-yet-merged branch from official repo, run ufbt update --branch=0.81.1 or ufbt update --branch=owner/my-awesome-feature.
  • You can also use branches from other repos, where build artifacts are available from an indexed directory, by specifying --index-url=<url>.
• uFBT can also download and update the SDK from any fixed URL. To do this, run ufbt update --url=<url>.
• To use a local copy of the SDK, run ufbt update --local=<path>. This will use the SDK located in <path> instead of downloading it. Useful for testing local builds of the SDK.

Global and per-project SDK management

By default, uFBT stores its state - SDK and toolchain - in .ufbt subfolder of your home directory. You can override this location by setting UFBT_HOME environment variable.

uFBT also supports dotenv (.env) files, containing environment variable overrides for the project in current directory. Most commonly, you will want to use this to override the default state directory to a local one, so that your project could use a specific version and/or hardware target of the SDK.

You can enable dotenv mode for current directory by running ufbt dotenv_create. This will create .env file in current directory with default values, linking SDK state to .ufbt subfolder in current directory, and creating a symlink for toolchain to .ufbt/toolchain in your home directory. You can then edit .env file to further customize the environment.

You can also specify additional options when creating the .env file. See ufbt dotenv_create --help for more information.

ufbt-bootstrap

Updating the SDK is handled by uFBT component called bootstrap. It has a dedicated entry point, ufbt-bootstrap, with additional options that might be useful in certain scenarios. Run ufbt-bootstrap --help to see them.

Troubleshooting

If something goes wrong and uFBT state becomes corrupted, you can reset it by running ufbt clean. If that doesn't work, you can try removing .ufbt subfolder manually from your home folder.

ufbt-bootstrap and SDK-related ufbt subcommands accept --verbose option that will print additional debug information.

Contributing

uFBT is a small tool and does not contain the actual implementation of build system, project templates or toolchain. It functions as a downloader and manager of SDK components that are packaged alongside with Flipper firmware.

Issues and pull requests regarding ufbt-bootstrap features like SDK management should be reported to this project, and the rest - related to actual application development - to Flipper firmware repo.

flipperzero-ufbt's Issues

debugging with vscode in Windows?

Any extra guidance to be able to debug on vscode?

After using ufbt vscode_dist

In the terminal tab looks like OK:

And debug console:

I can compile and copy the app ok manually, but I wanted to debug it step by step. Anyone had success?

I am using a cheap ST-link v2 clone from aliexpress

Unresolved symbols for sub-library

I can´t seem to compile a FAP with ufbt that has a private library referencing methods from a shared library (mbedtls).

fbt: warning: [...]: app may not be runnable. Symbols not resolved using firmware's API: {'mbedtls_sha1'} (in API, but disabled: {'mbedtls_sha1'})

For research, testing and demonstration I have created a small app with 2 branches.
https://github.com/qistoph/ufbt-lib-lib

master looks like this and has no issues compiling.

template.c: main() --> demo.c: calc_sha1() --> mbedtls/sha1: mbedtls_sha1()

ext_lib looks like this and gives the error I'm running into.

template.c: main() --> lib/demo/demo.c: calc_sha1() --> mbedtls/sha1: mbedtls_sha1()

The application.fam uses these definitions:

    fap_libs=["mbedtls"],
    fap_private_libs=[Lib(name="demo")],

I'm sorry if this is an error on my side and not a limitation of ufbt and this shouldn't have been posted as an issue.

No such file or directory

Navigate to the Applications folder and run ufbt create APPID
Run ufbt

get several errors that no such file or directory exist:

/home/binshift/Code/flipperzero-firmware/applications/debug/battery_test_app/views/battery_info.c:4:10: fatal error: assets_icons.h: No such file or directory
4 | #include <assets_icons.h>

I then try to run ufbt with the --file option <location of .h file>

I then get a different error:

cons: warning: Calling missing SConscript without error is deprecated.
Transition by adding must_exist=False to SConscript calls.
Missing SConscript '/home/binshift/.ufbt/current/scripts/build/f7-firmware-D/assets/compiled/assets_icons.h'
File "", line 88, in _run_code
scons: `.' is up to date.

More than likely I am not doing something right. but cannot find anything in the several docs I have read online.

Running on firmware 0.98.3

Please point me in the correct direction.

Thanks

Flipperdevice Ezekiel

assets_icons.h produces compile time error

Description

When using ufbt to build the FlipperZero application, a compilation error occurs when trying to include <assets_icons.h>. The application compiles and runs without issues when using the full fbt.

The assets library is specified in the manifest like so:
fap_libs=["assets"]

Steps to Reproduce

1. Use ufbt for building the project.
2. Include <assets_icons.h> in the source file.
3. Observe compilation error.

Expected Behavior

Compilation should succeed without errors.

Actual Behavior

Compilation fails with the following error:

/MH-Z19-UART/mh_z19_ui.c:3:10: fatal error: assets_icons.h: No such file or directory
    3 | #include <assets_icons.h>
      |          ^~~~~~~~~~~~~~~~
compilation terminated.

Logs

scons: Entering directory `/Users/<user>/.ufbt/current/scripts/ufbt'
        CC      /MH-Z19-UART/mh_z19_ui.c
        CDB   /MH-Z19-UART/.vscode/compile_commands.json
/MH-Z19-UART/mh_z19_ui.c:3:10: fatal error: assets_icons.h: No such file or directory
    3 | #include <assets_icons.h>
      |          ^~~~~~~~~~~~~~~~
compilation terminated.
scons: *** [/Users/<user>/.ufbt/build/mh_z19_uart/mh_z19_ui.o] Error 1

Environment

• OS: macOS 13.4.1 (c) (22F770820d)

scons: *** [phony_launch] More than one app is runnable: . Please specify an app with APPID=...

Hi!

I'm currently trying to run the built-in nfc app:

After running ufbt, ufbt launch asks to specify the APPID=. Doing so does not work:

This is probably a small thing I'm missing

ufbt fails to build app on M2 MacBook Air (Sonoma 14.3.1)

Hi,
I am working on a M2 MacBook Air with MacOS Sonoma 14.3.1 and set up ufbt following the instructions in the README. VSCode was configured with ufbt vscode_dist.
From what I can gather, ufbt is configures correctly:

22:24:35.026 [I] uFBT version    0.2.5
22:24:35.026 [I] State dir       /Users/fb/.ufbt
22:24:35.026 [I] Download dir    /Users/fb/.ufbt/download
22:24:35.026 [I] SDK dir         /Users/fb/.ufbt/current
22:24:35.026 [I] Toolchain dir   /Users/fb/.ufbt/toolchain
22:24:35.026 [I] Target          f7
22:24:35.026 [I] Mode            channel
22:24:35.026 [I] Version         0.99.1
22:24:35.026 [I] Details         {'hw_target': 'f7', 'mode': 'channel', 'channel': 'release', 'json_index': 'https://update.flipperzero.one/firmware/directory.json', 'version': '0.99.1'}`

I created a new boilerplate app with ufbt create APPID=flipper_app. Trying to build the app fails with the following output:

scons: Entering directory `/Users/fb/.ufbt/current/scripts/ufbt'
        LINK    /Users/fb/.ufbt/build/flipper_app_d.elf
        CDB     /Users/fb/Documents/Projekte/flipper_app/.vscode/compile_commands.json
/Users/fb/.ufbt/toolchain/arm64-darwin/bin/../lib/gcc/arm-none-eabi/12.3.1/../../../../arm-none-eabi/bin/ld:/Users/fb/Documents/Projekte/flipper_app/flipper_app.code-workspace: file format not recognized; treating as linker script
/Users/fb/.ufbt/toolchain/arm64-darwin/bin/../lib/gcc/arm-none-eabi/12.3.1/../../../../arm-none-eabi/bin/ld:/Users/fb/Documents/Projekte/flipper_app/flipper_app.code-workspace:1: syntax error
collect2: error: ld returned 1 exit status
scons: *** [/Users/fb/.ufbt/build/flipper_app_d.elf] Error 1

It appears, that the linker does not find what it needs. The elf file does not seem to be created. The build folder only contains:

• flipper_app.o
• flipper_app_icons.c
• flipper_app_icons.h
• flipper_app_icons.o

Can someone point me in the right direction to resolve this issue? Searching the web does not give me any meaningful hints.
Thanks a lot.

FlipperZero-ufbt .github

ufbt vscode_dist - SSL certificate problem: self-signed certificate in certificate chain

ufbt vscode_dist
Checking for tar..yes
Checking if downloaded toolchain tgz exists..no
Checking curl..yes
Downloading toolchain:
curl: (60) SSL certificate problem: self-signed certificate in certificate chain
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

How to define header files in Application.fam

Sorry not a bug, I am trying to use UFBT to build subghz so I can debug. I am reading the AppManifests.md on how to setup the inclusion of header files ".h"

UFBT is now throwing errors about not finding several header files.

I have tried the parameter sdk_headers in one of the app() functions but UFBT is still throwing errors.

Here is my application.fam function. I have tried several different apptypes, but cannot get the app to build.

App(
appid="subghz_start",
targets=["f7"],
apptype=FlipperAppType.STARTUP,
entry_point="subghz_on_system_start",
sources=["./scenes/subghz_cli.c", "helpers/subghz_chat.c"],
order=40,
sdk_headers=["./scenes/subghz_scene.h","./protocol_items.h"]
)

Sorry I know you are busy, but cannot find any info or examples on how to include .h files.

Thanks

Joe

Issues with STlink debugging

machinehum@walkers-macbook-pro flipper-blackhat-app % ufbt SWD_TRANSPORT=stlink flash
scons: Entering directory `/Users/machinehum/.ufbt/current/scripts/ufbt'
python3 /Users/machinehum/.ufbt/current/scripts/fwflash.py --interface=stlink --serial=auto /Users/machinehum/.ufbt/current/firmware.elf
2024-03-06 10:28:09,280 [INFO] Using stlink
2024-03-06 10:28:09,281 [INFO] Flashing /Users/machinehum/.ufbt/current/firmware.elf
.
2024-03-06 10:28:09,541 [ERROR] OpenOCD failed to flash
2024-03-06 10:28:09,542 [ERROR] xPack OpenOCD x86_64 Open On-Chip Debugger 0.11.0+dev (2021-12-07-19:33)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
hla_swd
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
Info : DEPRECATED target event trace-config; use TPIU events {pre,post}-{enable,disable}
Info : clock speed 500 kHz
Info : STLINK V2J24S4 (API v2) VID:PID 0483:3748
Info : Target voltage: 3.283794
Error: init mode failed (unable to connect to the target)
2024-03-06 10:28:09,542 [ERROR] Failed to flash via stlink
scons: *** [/Users/machinehum/.ufbt/flash] Error 1
machinehum@walkers-macbook-pro flipper-blackhat-app % 

compile_commands.json wont get created by ufbt vscode_dist

Summary:

The compile_commands.json file is not being generated as expected when using ufbt vscode_dist.

Actual Behavior:

The compile_commands.json file is not created despite running the ufbt vscode_dist command. This can result in a lack of proper code navigation and IntelliSense functionality in Visual Studio Code.

Additional Information:

UFBT Version:  0.2.4.3
OS: MacOS 14
UFBT Status: 
12:56:10.148 [I] uFBT version    0.2.4.3
12:56:10.149 [I] State dir       /Users/antonstadie/.ufbt
12:56:10.149 [I] Download dir    /Users/antonstadie/.ufbt/download
12:56:10.149 [I] SDK dir         /Users/antonstadie/.ufbt/current
12:56:10.149 [I] Toolchain dir   /Users/antonstadie/.ufbt/toolchain
12:56:10.149 [I] Target          f7
12:56:10.149 [I] Mode            channel
12:56:10.149 [I] Version         0.94.1
12:56:10.149 [I] Details         {'hw_target': 'f7', 'mode': 'channel', 'channel': 'release',      'json_index': 'https://update.flipperzero.one/firmware/directory.json', 'version': '0.94.1'}

Screenshots:

Navigating source and errors when loading in VSCode

How do I find by reference, definition, etc in vscode when modifying the source code? I installed the clangd extension but it just shows me nonstop errors, so I'm guessing it needs a config file or not the right extension. I already ran ./fbt vscode_dist before opening in vscode after git clone.

Received invalid error message: "We only provide toolchain for x86_64 CPUs, sorry..."

Received invalid error message on my system stating, "We only provide toolchain for x86_64 CPUs, sorry...", when my system is x86_64. The error is believed to be caused by the script not recognizing my Unix operating system, which is of the BSD variety.

Assistance would be great, until then I will have to look for a solution at a later time.

ufbt assumes Python is installed

ufbt should not assume there is a working copy of Python currently installed, particularly on Windows, especially when it's going to download the toolchain that contains its own copy of Python.

[Feature request] Upload to flipper via UFBT

I'm currently building an application, and using qFlipper to upload each new build is getting real old real fast.

It'd be cool if UFBT could automatically upload the .fap to my flipper - even if I have to specify the file i actually want to upload, the path it's supposed to be stored at and the serial port my flipper is connected to.

Alternatives I've considered:
making a script to upload it through the serial console, but that fails because I can't get the Ctrl+C to register with the flipper.

ARM64 toolchain support

Currently the tool installs a macOS x86_64 toolchain instead of an arm64 toolchain on macOS with Apple Silicon. (into lang/c/flipperzero-firmware in the workspace root)

Add support for Apple Silicon

It would be really great if you could add native support for Apple Silicon chips (ARM) so we can use ufbt without Rosetta2.

user@MacBook-M3-Pro ~ % ufbt
20:03:59.133 [I] Deploying SDK for f7
20:03:59.133 [I] Fetching version info for UpdateChannel.RELEASE from https://update.flipperzero.one/firmware/directory.json
20:03:59.419 [I] Using version: 0.98.3
20:03:59.419 [I] uFBT SDK dir: /Users/zigad/.ufbt/current
20:04:00.530 [I] Deploying SDK
20:04:00.651 [I] SDK deployed.
Flipper Zero Toolchain needs Rosetta2 to run under Apple Silicon
Please install it by typing 'softwareupdate --install-rosetta --agree-to-license'

Cannot open files in .ufbt if the folder path contains spaces

Please see issue #2

This issue exists in the most recent version of ufbt, whenever running ufbt launch it attempts to open runfap.py, but if the folder path to .ufbt contains spaces, it will give an error and fail

I updated the SDK but I still get this.

C:\Users\pizca>ufbt
SDK is missing scripts distribution!
You might be trying to use an SDK in an outdated format.
Run ufbt update -h for more information on how to update.

Windows. Spaces in path to flipperzero-ufbt-dev folder

If you unpack the contents of this repository into a folder in the path of which there are spaces, then an error occurs on any call to ufbt.cmd. The error is related to the fact that in some script you need to quote the path, but I did not find where

scons: *** [phony_launch] Error 4

On windows, I'm getting this error on app launch.

PS C:\flipperzero-ufbt\app> ufbt launch
scons: Entering directory `C:\flipperzero-ufbt'
python ".ufbt\current\scripts/runfap.py" ".ufbt\build\showers.fap" --fap_dst_dir "/ext/apps/Misc"
APPCHK .ufbt\build\showers.fap
Target: 7, API: 20.0
2023-03-29 11:42:27,985 [INFO] Using FLIP_LICPRIX on COM4
2023-03-29 11:42:28,065 [ERROR] Error: list index out of range
scons: *** [phony_launch] Error 4

********** FBT ERRORS **********
phony_launch: Error 4

How can i fix this?

includePath property from c_cpp_properties.json

Problem Description:
I'm encountering an issue where ufbt nor intellisense neither recognizes nor utilizes the includePath property specified in the c_cpp_properties.json file. Due to this, the build process encounters errors related to missing includes.
Any suggestions, guidance, or insights to rectify this problem would be immensely appreciated. Thank you for your assistance!

Expected Behavior:
IntelliSense should accurately provide code suggestions, error checking, and code navigation based on the includePath specified in c_cpp_properties.json.
ufbt should consider and utilize the includePath property from c_cpp_properties.json to locate header files and dependencies required during the build process.

Screenshots:

No way to exit from "ufbt cli"

Not sure if it's an issue in firmware or ufbt itself, but after running "ufbt cli" there's no way to exit it except rebooting flipper.

There are no commands like "exit" or "quit", ctrl-D does not work.
There's also no such command in the list of commands (pressing "help" or "?").

Killing ufbt process ("sudo killall ufbt") also does not help - it's not possible to run "sudo ufbt launch" after it because it prints:

2024-04-28 14:55:13,663 [ERROR] Error: device reports readiness to read but returned no data (device disconnected or multiple access on port?)
scons: *** [phony_launch] Error 4

After flipper reboot everything is OK.

Is there any way to safely exit from "ufbt cli". If so, could this be added to documentation?

Synchronize builtin help

It's outdated now. Say should be "create" instead of "app_template", "launch" is not mentioned among tasks etc.

Failed to download https://update.flipperzero.one/builds/toolchain/gcc-arm-none-eabi-12.3-armv7l-linux-flipper-33.tar.gz

Hi i'm just trying to build a .fap, because i want to install an app on my flipper zero, which can't be installed from the app store, because i'm running custom firmware - I'm trying to build the app on a Raspberry Pi 2B, and from my very noob perspective, this maybe has something to do with the fact that the ARM7 my raspberry pi runs, isn't supported? Thanks!