codytolene / flipper-zero-development-toolkit Goto Github PK

Flipper Zero - Development Toolkit

Hey there, fellow developer!

Welcome to the repository that houses a comprehensive and user-friendly guide for crafting your very own Flipper Zero application. By simply following along with this curated readme, and customizing it to your preferences along the way, you'll have your app up and published in no time. No need to reinvent the wheel, I've got your back!

Let's build something awesome together! 💪💻

• Previews
• Hardware Requirements
• Hardware Installation
• Firmware Installation
• Software Installation
• Software Guide
• Development Guide
• Flipper Application Catalog
• Contributions
• Special Thanks To

Add in-app screenshot previews in this section or GIF's to demonstrate your application in action. You can use ScreenToGif to record GIF's of your application.

[ Back to top ]

Define hardware requirements to run your application here. For example, if your application requires a Flipper Zero GPIO device, you would add a link to the Flipper Zero GPIO device here.

[ Back to top ]

Add hardware installation instructions here. Useful for when you need to demonstrate GPIO device pinout guides and the like.

[ Back to top ]

Add firmware installation instructions here. As an example this would be useful for when you need a guide for flashing a custom firmware to your Flipper Zero GPIO device. Add firmware files to the "src-firmware/" directory.

[ Back to top ]

Add software installation instructions here.

This repository includes GitHub Actions that lint and compile your application automatically. In the latest GitHub Actions for this repository you will find zip files containing the FAP application compatible with either the "dev" or "release" build of the latest Flipper Zero firmware. To manually install the application (for instance your application is not yet available in the Flipper Application Catalog) you can download those files and manually install them on your Flipper Zero device via USB.

[ Back to top ]

Demonstrate how the application works regarding the Flipper Zero's button layout. You can use this to guide your users on how to use your application more clearly.

🔼 = Up button does __.

🔽 = Down button does __.

◀️ = Left button does __.

▶️ = Right button does __.

⚪ = Center button does __.

↩️ = Go back does __.

[ Back to top ]

1. Make sure you have Git and Visual Studio Code installed on your system.
2. Clone the repository and its submodule dependencies using the following command:

   git clone https://github.com/CodyTolene/Flipper-Zero-Development-Toolkit.git --recurse-submodules

3. Download and install Python.
4. Open a new terminal in the "src-fap" directory of this project.
5. Run py -m pip install --upgrade ufbt to ensure you have the latest uFBT installed.
6. Run ufbt vscode_dist to download the Windows toolchain and set up Visual Studio Code files.
7. Open the project "fap" directory ("src-fap") in Visual Studio Code. Make sure you have "Microsoft C/C++" extension installed and enabled.
8. In Visual Studio Code, open the command palette (CTRL+SHIFT+P) and type "C/C++ Edit Configurations (UI)" to find and open its settings. Add the following directory to the "Include path" option:

   ${workspaceFolder}/../.submodules/**
   

   This includes the Flipper Zero firmware library for your project (you can update it to a custom firmware if needed).
9. If Visual Studio Code shows import errors after saving the above settings from step 8, run the build script (see step 10) to resolve them.
10. It should now be possible perform various tasks within Visual Studio Code using Ctrl+Shift+B or "Terminal -> Run Task." Alternatively, you can use uFBT scripts in the terminal. Here are some useful commands to get started:

    Command	Description
    ufbt cli	Starts a CLI session with the Flipper Zero device.
    ufbt build	Build the application.
    ufbt lint	Lint the application.
    ufbt format	Format the application.
    ufbt launch	Upload and start application over USB.

11. You're now ready to begin programming your application within the directory "src-fap/" with "src-fap/toolkit.c" -> toolkit_app(...) being your entry point.
12. After making changes, linting, testing, etc., please refer to the contributions section for a guide on how to submit your code for review (to make changes to this repo) or forking for your own use.

[ Back to top ]

Use the following flow to verify build requirements for the Flipper Application Catalog:

1. Open a new terminal at the root of this project.
2. Run py -m venv venv to install a virtual environment for use.
3. Activate the virtual environment with the command venv\Scripts\activate.
4. Install the required dependencies by running pip install -r .submodules/flipper-application-catalog/tools/requirements.txt.
5. Ensure that "src-fap\manifest.yml" has the latest commit sha that will be used for submission. Also, verify that the version is correct.
6. Run py .submodules/flipper-application-catalog/tools/bundle.py src-fap/manifest.yml bundle.zip to verify and bundle the application.
7. If the above command succeeds, the application is ready for submission. Otherwise, fix any errors and try again.
8. Use deactivate to exit the virtual environment and return to your normal terminal.

For more information on Flipper Application Catalog contribution requirements, see here.

[ Back to top ]

To create your own variation:

1. Fork the repository.
2. Add your code, push.

To add feedback to this repository:

1. Fork the repository.
2. Create a new branch with a descriptive name: <username>/[<issue-#>]-<feature-or-bug-fix-desc>
3. Refer to the Development Guide to get started. Program, commit changes, and push to your branch.
4. Publish a pull request here for review from your branch.
5. Wait for review and merge. Thank you for your contribution!

[ Back to top ]

• Flipper Devices for providing the Flipper Application Catalog, uFBT, their firmware, and the incredible Flipper Zero hardware itself.
• Derek Jamison for his insightful YouTube videos on Flipper Zero application development.
• GitHub user leedave for helping me learn more about Flipper Zero development by boilerplate example.
• The Unleashed Firmware community and their valuable contributions.
• The Xtreme Firmware community and their remarkable work.
• Cody Tolene for creating the Flipper Zero Development Toolkit. Feel free to remove my name, but I would be thrilled to see and be a part of your work if you found this toolkit useful in any way! 😊 Happy coding! 💻

[ Back to top ]