Momentum App Framework

A complete, beginner-friendly starter repository for building JavaScript scripts and C-language .fap apps for the Flipper Zero running Momentum Firmware.

Phone-only friendly! You can develop, edit, and deploy JavaScript scripts using only your phone + the Flipper Mobile App. C apps need a computer (or GitHub Codespaces).

---

Table of Contents

1. Why two paths?
2. Quick Start - JavaScript (phone-only)
3. Quick Start - C .fap apps
4. Folder Structure
5. Deploying to your Flipper
6. Examples
7. Troubleshooting
8. Useful Links
9. License

---

Why two paths?

Feature	JavaScript (/JS-Apps)	C .fap (/C-Apps)
Difficulty	Easy	Advanced
Needs computer?	No (phone works)	Yes (uFBT)
Compile step	None	Required
Best for	Sub-GHz remotes, GUIs, automation	Drivers, performance-critical apps
Hot reload	Yes (just re-copy file)	Re-compile + copy
Recommended for new users	YES	Only if you need it

Most custom apps - especially Sub-GHz remotes like the included Balkon-Markise example - should be written in JavaScript. You only need C for things like new chip drivers or low-level hardware integration.

---

Quick Start - JavaScript (phone-only)

What you need

• A Flipper Zero running Momentum firmware
• The Flipper Mobile App on your phone
• Any text editor app on your phone (e.g. Acode, Quoda, even GitHub's web editor)

Steps

1. Pick a template from JS-Apps/templates/:

   • basic-script.js - simplest "Hello World" script
   • subghz-remote-template.js - multi-button Sub-GHz remote (loads .sub files)
   • gui-example.js - GUI dialog and submenu demo

2. Copy the template into a new file (e.g. my_remote.js). On your phone, you can do this from GitHub's web UI:

   • Open the file in this repo
   • Tap the pencil icon to edit
   • Save it to a fork or use "Raw" -> "Download" / copy/paste into a text editor app

3. Edit it in any text editor on your phone. Change button labels, file paths, frequencies, etc.

4. Transfer to your Flipper:

   • Open the Flipper Mobile App
   • Connect to your Flipper via Bluetooth
   • Open File Manager (or "Storage" / "Browse")
   • Navigate to: SD Card -> apps -> Scripts/ (Create the Scripts folder if it does not exist)
   • Upload your .js file there

5. Run it on the Flipper:

   • On the Flipper, go to: Apps -> Scripts -> [your_script.js]
   • Press OK to launch

That's it! No compilation, no toolchain, no computer required.

Tip: Want even faster iteration? Use qFlipper on a desktop to drag-and-drop, but the mobile app works perfectly fine.

---

Quick Start - C .fap apps

C apps require uFBT (Micro Flipper Build Tool). This needs a computer with Python 3.

One-time setup (computer required)

# 1. Install uFBT
pip install --upgrade ufbt

# 2. Bootstrap uFBT for Momentum firmware
ufbt update --index-url=https://up.momentum-fw.dev/firmware/directory.json --channel=release

No computer? Use GitHub Codespaces! Click the green Code button on this repo -> Codespaces -> Create codespace on main. Everything is preinstalled.

Build the example app

cd C-Apps/templates/hello-world
ufbt

The compiled .fap will be at dist/hello_world.fap. Copy it to your Flipper at: SD Card -> apps -> Examples/hello_world.fap

For more details, see C-Apps/ufbt-config.md.

Design a GUI visually (optional)

Prefer not to hand-write Canvas draw calls? Flipper GUI Studio is a browser-based visual editor for the 128×64 screen. Drag widgets, wire buttons to screens, and export a build-ready C app that unzips straight into C-Apps/<your-app>/ and builds with ufbt:

1. Design your screens and fill in App settings (name, namespace, category, launcher icon).
2. Export the C app bundle and unzip it into C-Apps/.
3. cd C-Apps/<your-app> && ufbt.

The generated application.fam already passes this repo's npm run validate. See docs/gui-tool-integration.md for the full walkthrough, and C-Apps/templates/gui-studio/ for an example of the exact output.

The tool's Preview export is a browser canvas preview only — not a deployable script. Pixel GUI designs map to the C path; the JS path uses view factories instead (see docs/JS-API-Reference.md).

---

Folder Structure

momentum-app-framework/
├── README.md                       <- You are here
├── LICENSE
├── .gitignore
├── JS-Apps/                        <- JavaScript scripts (recommended path)
│   ├── package.json                <- @next-flip/fz-sdk-mntm + dev deps
│   ├── tsconfig.json               <- TS / IntelliSense for the SDK
│   ├── .env.example
│   ├── templates/
│   │   ├── basic-script.js
│   │   ├── subghz-remote-template.js
│   │   └── gui-example.js
│   └── examples/
│       └── balkon-markise-remote.js
├── C-Apps/                         <- Native .fap apps (advanced)
│   ├── ufbt-config.md
│   └── templates/
│       ├── hello-world/            <- minimal hand-written skeleton
│       │   ├── application.fam
│       │   ├── hello_world.c
│       │   └── README.md
│       └── gui-studio/             <- example Flipper GUI Studio export
├── docs/
│   ├── JS-API-Reference.md
│   ├── deployment.md
│   └── gui-tool-integration.md     <- visual GUI builder workflow
└── .github/workflows/
    ├── ci.yml                      <- PR sanity gate: prettier, typecheck, validate, build
    ├── release-please.yml          <- Conventional-commit driven version + CHANGELOG PR
    ├── release-artifacts.yml       <- Builds & attaches .fap/.js on release published
    └── momentum-sync.yml           <- Weekly Momentum SDK upgrade PR

---

Deploying to your Flipper

App type	Destination on SD card
JavaScript script (.js)	/ext/apps/Scripts/
C .fap app	/ext/apps/<Category>/ (e.g. Examples, Tools, GPIO)
Sub-GHz files (.sub)	/ext/subghz/

Three ways to copy files:

1. Mobile App - Bluetooth, phone-friendly. Best for .js scripts.
2. qFlipper - USB or Bluetooth, desktop. Best for .fap apps.
3. microSD card reader - Pull the SD card out, mount on phone/computer. Bulk copies.

See docs/deployment.md for a deep-dive.

---

Examples

JS-Apps/examples/balkon-markise-remote.js - A polished multi-button Sub-GHz remote. Shows a 3-button menu (REIN, RAUS, STOP) and transmits the corresponding .sub file from /ext/subghz/. Perfect base for any garage door, awning, or rolling shutter remote.

To use it:

1. Record your .sub files using Sub-GHz -> Read on your Flipper.
2. Save them as Balkon_markise_rein.sub, Balkon_markise_raus.sub, Balkon_markise_stop.sub in /ext/subghz/.
3. Copy balkon-markise-remote.js to /ext/apps/Scripts/.
4. Run from Apps -> Scripts.

---

Troubleshooting

Problem	Solution
Script not found on Flipper	Make sure file is in /ext/apps/Scripts/ and ends in .js
module not found: @flipperdevices/...	You are on stock firmware. This framework needs Momentum.
Sub-GHz file fails to transmit	Check the file is in /ext/subghz/ and the .sub was recorded on the same frequency/protocol your remote uses
ufbt: command not found	Run pip install --upgrade ufbt and ensure your Python ~/.local/bin is in PATH
.fap crashes on launch	Make sure it was built with ufbt against the Momentum SDK (not stock)
No Scripts folder visible	Create it manually via the Mobile App File Manager: apps -> [+] -> New folder -> Scripts

---

Useful Links

• Momentum Firmware: https://github.com/Next-Flip/Momentum-Firmware
• Momentum website / OTA: https://momentum-fw.dev
• Momentum Discord: https://discord.gg/momentum
• Momentum JS docs: https://docs.flipper.net/development/js (with Momentum extensions)
• uFBT: https://github.com/flipperdevices/flipperzero-ufbt
• JS SDK package: https://www.npmjs.com/package/@next-flip/fz-sdk-mntm
• Flipper Mobile App: https://flipperzero.one/app

---

License

MIT - see LICENSE. Use freely, contributions welcome.