Unleashed Firmware 应用目录结构全解析从 debug 到 system 的五大分区与构建系统【免费下载链接】unleashed-firmwareFlipper Zero Unleashed Firmware项目地址: https://gitcode.com/GitHub_Trending/un/unleashed-firmware导读applications/目录是 Flipper Zero Unleashed 固件中所有用户态程序的集合地从工厂测试工具到主菜单应用、后台服务、设置项与隐藏系统工具全部按职责被划分为debug、main、services、settings、system五个分区。本篇指南以仓库中的 applications/ReadMe.md 为骨架结合各分区真实的application.fam清单与fbt构建工具源码讲清每个分区的作用、每个应用的身份定位以及应用清单App Manifest中apptype、appid、entry_point等字段如何决定一个程序在固件中的生命周期。读完你就能在一分钟内判断某个新应用应该放进哪个分区、以哪种类型注册。一、总览五个分区五种职责applications/目录用文件夹划分出五类截然不同的程序它们在固件启动流程与用户界面中的角色各不相同分区一句话职责是否出现在主菜单典型示例debug工厂测试 Flipper 硬件的调试工具否按名称由 loader 启动display_test、keypad_testmain主菜单中的用户应用是nfc、subghz、infraredservices提供系统 API 的后台服务否gui、loader、storagesettings基础固件与服务的配置小应用设置菜单bt_settings_app、power_settings_appsystem其他菜单不可见的工具 预置外部应用否updater、js_app、hid_app这五个分区对应fbt构建工具中FlipperAppType枚举的语义也对应运行时 loader 的调度规则。下面逐区展开。二、debug工厂与硬件自检工具debug分区是工厂测试 Flipper 硬件时使用的调试程序集合正常情况下用户不会在主菜单里看到它们只能由 loader 按应用名显式拉起——applications/services/applications.h中的FLIPPER_DEBUG_APPS数组注释明确写着Debug apps, Can only be spawned by loader by name。各调试工具速查accessor—— Wiegand 服务器用于调试 Wiegand 协议相关硬件链路battery_test_app—— 电池调试应用读取并展示电池状态blink_test—— LED 闪烁测试验证指示灯驱动bt_debug_app—— 蓝牙测试应用需要完整 BT 协议栈已安装display_test—— 各类屏幕显示测试与调整对比度、刷新等file_browser_test—— 文件选择器 UI 的测试入口keypad_test—— 按键矩阵测试lfrfid_debug—— 低频 RFID 调试工具text_box_test—— UI 组件文本框测试uart_echo—— UART 模式回环测试unit_tests—— 固件单元测试框架本体usb_mouse—— USB HID 鼠标模式测试usb_test—— 其他 USB 功能测试vibro_test—— 震动马达测试。从 manifest 看 debug 包的组成applications/debug/application.fam 定义了一个名为debug_apps的METAPACKAGE元包它本身不包含代码而是把blink_test、vibro_test、keypad_test、usb_test、usb_mouse、uart_echo、display_test、text_box_test、file_browser_test、speaker_debug这 10 个应用打包进固件。元包是 fbt 组织固件内容的一种机制provides列表里列出的 appid 会作为构建依赖被一并纳入镜像。单元测试debug 分区里的插件化测试集群unit_tests是 debug 分区里最特殊的一个成员。applications/debug/unit_tests/application.fam 展示了它的完整形态unit_tests本体是FlipperAppType.STARTUP启动钩子entry_pointunit_tests_on_system_start在系统启动时注册测试入口并要求system_settings与cli_subghz作为依赖每个测试主题test_furi、test_storage、test_nfc、test_subghz、test_infrared、test_rpc、test_js等 20 个都是一个独立的FlipperAppType.PLUGIN插件entry_pointget_api通过requires[unit_tests]挂到宿主框架下测试插件按需加载既控制了常驻内存占用也验证了固件的动态加载能力。这种一个宿主 若干测试插件的布局实际上就是整个固件插件机制在测试场景下的缩影。三、main主菜单应用群main分区承载主菜单中的应用是用户日常最常打交道的功能集合。仓库中的 applications/main/application.fam 给出了完整的注册清单appid功能说明gpioGPIO 应用包含 USART 桥接与 GPIO 控制ibuttoniButton 应用one-wire 钥匙等infrared红外应用控制红外设备lfrfid低频 RFID 应用LF 卡读写与模拟nfcNFC 应用HF RFID、EMV 等subghzSub-GHz 应用433MHz 等频段遥控器bad_usbBad USB 应用USB 键盘注入脚本u2fU2F 应用双因素认证令牌archive归档与文件管理器浏览 SD 卡与内部存储clock时钟应用主菜单附加项subghz_remoteSub-GHz 遥控器独立入口此外还有一个main_apps_on_start元包用于承载系统启动钩子如cli可见主菜单应用和启动钩子在构建层面是分开管理的。实例NFC 应用的双层插件架构以 applications/main/nfc/application.fam 为例可以看到现代 Unleashed 固件主应用的典型结构nfc本体是FlipperAppType.MENUEXTERNAL主菜单外部应用iconA_NFC_14、stack_size5 * 1024、order30并通过sources中的!plugins、!cli等排除规则把子模块隔离出去协议支持被拆成大量FlipperAppType.PLUGIN插件nfc_iso14443_3a、nfc_mf_classic、nfc_mf_ultralight、nfc_emv……每个协议插件fal_embeddedTrue意味着它们会嵌入固件镜像而非独立 .fap 文件卡片解析器如troika_parser、saflok_mfc_parser、clipper_parser也是独立插件requires[nfc]声明依赖某些甚至通过cdefines区分同一源码的不同变体如 NDEF 的 UL/MFC/SLIX/T4T 四种变体。这样的设计把主程序框架与可插拔协议彻底解耦协议代码只在插件被加载时才常驻内存这正是仓库注释里Card parsing helpers ... only resident in RAM while that plugin is loaded的含义。实例Sub-GHz 应用的依赖声明applications/main/subghz/application.fam 展示了另一个主应用的 manifest 写法App( appidsubghz, nameSub-GHz, apptypeFlipperAppType.APP, targets[f7], cdefines[APP_SUBGHZ], entry_pointsubghz_app, requires[gui, cli, dialogs], iconA_Sub1ghz_14, stack_size3 * 1024, order1, fap_libs[assets, hwdrivers], )注意requires[gui, cli, dialogs]——它明确声明了运行时依赖的服务targets[f7]表明该应用只构建于 f7 硬件目标同目录下的cli_subghz插件则把 CLI 子命令含subghz_chat对讲工具与 GUI 应用拆开。这解释了同一个功能为什么既有界面入口又有命令行入口——它们本来就是两个独立构建单元。四、services后台服务与系统 APIservices分区存放向应用提供系统 API 的后台服务它们随固件启动而常驻不直接面向用户。服务清单applications.h—— 固件应用列表头文件见下文详解bt—— BLE 服务与应用管理蓝牙协议栈cli—— 控制台服务与 API提供 USB/蓝牙串口命令行crypto—— 加密 CLI 工具desktop—— 桌面服务管理主界面与快捷键dialogs—— 对话框服务为应用提供 GUI 对话框能力dolphin—— Dolphin 服务及配套小应用经验/养成系统gui—— GUI 服务与 API所有界面绘制的基础input—— 输入服务统一分发按键事件loader—— 应用加载器服务负责按名称启动应用notification—— 通知服务LED、声音、振动power—— 电源服务rpc—— RPC 服务与 API供上位机如 qFlipper调用storage—— 存储服务统一管理内部 Flash 与 SD 卡。applications/services/application.fam 中basic_services元包的provides列表与实际目录一一对应cli_vcp、crypto_start、rpc_start、gps_start、network_start、expansion_start、bt、desktop、loader、power、namechanger_srv。可以看到服务既包括常驻守护进程也包括若干*_start启动钩子如gps_start、network_start后者属于FlipperAppType.STARTUP类型。灵魂文件applications.happlications/services/applications.h 是整个固件应用体系的注册总表。它定义了FlipperInternalApplication结构包含FuriThreadCallback app线程入口、name、appid、stack_size栈大小、icon图标与flags标志并对外导出多组由构建系统生成的应用数组FLIPPER_SERVICES/FLIPPER_SERVICES_COUNT—— 开机即启动的服务列表FLIPPER_APPS/FLIPPER_APPS_COUNT—— 由 loader 拉起的主菜单应用FLIPPER_SYSTEM_APPS—— 只能按名称由 loader 启动的系统应用FLIPPER_DEBUG_APPS—— 只能按名称启动的调试应用FLIPPER_SETTINGS_APPS—— 设置应用FLIPPER_EXTERNAL_APPS/FLIPPER_EXTSETTINGS_APPS—— 外部SD 卡 .fap应用与外部设置项。FLIPPER_AUTORUN_APP_NAME用于配置开机自启应用。这套头文件由 fbt 根据各application.fam清单自动生成开发者一般不需要手改——这正是ReadMe.md里services分区同时收录applications.h的原因它是服务与应用之间的编译期契约。五、settings设置小应用settings分区存放为基础固件及其服务提供配置的小应用均以设置项形态出现在系统设置菜单中about—— 显示 Flipper 信息的关于页面bt_settings_app—— 蓝牙选项开关、配对、名称等desktop_settings—— 桌面配置壁纸、快捷方式布局dolphin_passport—— Dolphin 护照应用经验等级展示notification_settings—— LCD 亮度、声音音量等配置power_settings_app—— 基础电源选项storage_settings—— 存储设置格式化、信息统计system—— 系统设置关于、出厂重置等input_settings_app—— 基础输入选项按键灵敏度等。applications/settings/application.fam 中settings_apps元包提供了passport、system_settings、clock_settings、input_settings、about五个 appid。与main分区不同设置应用在applications.h中有专属数组FLIPPER_SETTINGS_APPS由 loader 在设置界面按需拉起因此可以设计得小而轻。六、system隐藏工具与预置应用system分区存放其他菜单中不可见的工具应用以及随固件预置的少量外部应用hid_app—— BLE 与 USB 双模 HID 遥控器滑鼠、演示器等js_app—— JS 引擎运行器用于执行 .js 脚本snake_game—— 贪吃蛇小游戏系统分区中的娱乐性示例storage_move_to_sd—— 内部存储数据迁移工具updater—— 更新服务与应用负责固件升级流程。applications/system/application.fam 的system_apps元包列出了updater_app、js_app、findmy_startup三个 appid注释中archive被显式屏蔽因为归档应用已归入main分区。这些应用虽不出现在普通菜单但通过 loader 名称启动——例如updater通常在收到更新包后由系统引导拉起。七、幕后机制application.fam 与 FlipperAppTypeapplications/ReadMe.md只给出了目录视角要真正理解分区的含义必须看 fbt 如何解释这些目录。在 scripts/fbt/appmanifest.py 中FlipperAppType枚举定义了所有应用类型枚举值字符串含义SERVICEService开机常驻后台服务SYSTEMSystem系统应用仅按名称启动APPApp普通应用由 loader 启动DEBUGDebug调试应用ARCHIVEArchive归档管理器SETTINGSSettings设置应用STARTUPStartupHook启动钩子EXTERNALExternal外部 .fap 应用MENUEXTERNALMenuExternal主菜单外部应用EXTSETTINGSExtSettings外部设置项METAPACKAGEPackage元包无代码聚合依赖PLUGINPlugin插件动态/嵌入加载FlipperApplication数据类同文件 L34-L97给出了每个应用在 manifest 中的可用字段其中几个关键字段直接决定了应用归属哪个分区appid—— 必须匹配^[a-z0-9_]$是全局唯一的应用标识apptype—— 决定上述类型之一entry_point—— 应用入口函数符号如subghz_app、unit_tests_on_system_startstack_size—— 线程栈大小默认 2048插件会被强制置 0因为插件没有自己的常驻线程requires/provides—— 运行时依赖与对外提供的能力order—— 在菜单中的排序权重targets—— 适用的硬件目标默认allNFC/Sub-GHz 限定f7。因此把应用放进哪个分区本质上是为它声明哪种apptype例如工厂自检工具放debug并用DEBUG/SYSTEM类型主菜单应用放main并用APP/MENUEXTERNAL纯配置页放settings并用SETTINGS。目录只是约定俗成的组织方式最终权威是各目录下application.fam中声明的类型与依赖关系。八、开发者实操如何定位一个新应用结合上文当你准备在 Unleashed 固件中新增程序时可以按这个决策路径选择落点判断生命周期需要开机常驻、为其他应用提供 API →applications/services/声明为SERVICE或通过basic_services元包提供只需开机执行一次初始化 →STARTUP启动钩子。判断用户入口出现在主菜单 →applications/main/APP/MENUEXTERNAL出现在设置菜单 →applications/settings/SETTINGS既不进菜单也不做服务 →applications/system/SYSTEM按名称启动。判断用途纯硬件自检 →applications/debug/追加到debug_apps元包的provides中即可随固件编译进镜像。遵循 fbt 构建规则新建application.fam时严格遵守appid命名小写字母、数字、下划线entry_point必须与源码中导出的函数符号一致插件类应用记得声明requires依赖构建脚本会严格校验这些字段见 appmanifest.py 中对 appid 的正则检查。结语applications/的五分区布局是 Unleashed 固件工程组织的核心骨架debug保硬件、main面向用户、services提供能力、settings承载配置、system藏起工具。通过把ReadMe.md的目录说明与各分区真实的application.fam清单、以及applications.h和 fbt 的类型系统对照阅读你不仅能快速定位任何现有功能模块的源码位置也能准确规划新应用的落点与 manifest 声明真正把目录结构文档用成固件应用开发地图。【免费下载链接】unleashed-firmwareFlipper Zero Unleashed Firmware项目地址: https://gitcode.com/GitHub_Trending/un/unleashed-firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考