flipperzero-cli-bridge在 Flipper Zero 上用 GUI 无绳操作 CLI 的命令行桥接应用完整指南【免费下载链接】FlipperPlayground (and dump) of stuff I make or modify for the Flipper Zero项目地址: https://gitcode.com/GitHub_Trending/fl/Flipper导读flipperzero-cli-bridge应用名CLI-GUI Bridge是一个运行在 Flipper Zero 上的第三方外部应用FAP它把设备原本只对 USB 虚拟串口开放的 CLI 会话搬到了设备自带的图形界面上让你在不连接电脑、不依赖 qFlipper 的情况下直接在屏幕上输入并执行subghz chat、系统诊断等 CLI 命令。本文以本仓库中该应用的 README.md 为主体结合其 C 语言源码 逐层拆解安装、按键操作、退出语义与底层实现原理读完你将能独立完成部署并理解GUI 输入 → CLI 会话 → 输出回显的完整数据通路。一、应用概览它解决了什么问题Flipper Zero 的 CLI 通常通过 USBqFlipper / 串口终端访问一旦设备离线命令行能力就够不着了。flipperzero-cli-bridge的核心价值在于无绳化untethered在设备本机屏幕上提供命令输入框与输出窗口摆脱 USB 线缆依赖会话保活支持退出应用但保持内部终端会话的持久模式特别适合subghz chat这类需要长时间在线监听的场景低侵入作为 EXTERNAL 类型的 FAP 应用不修改固件即可安装从源码结构看它通过复用固件 CLI 子系统cli_session_open/cli_session_close实现了会话接管。二、安装与部署2.1 方式一直接使用预编译 .fap推荐从项目的releases 页面下载对应最新固件版本的预编译.fap文件然后用 qFlipper 将其拷贝到 SD 卡的apps/Tools/目录下。官方 README 特别强调安装前务必将 Flipper Zero 固件升级到最新版本。预编译包与固件版本强绑定版本不匹配可能导致无法加载或运行异常。2.2 方式二从源码构建fbt构建依赖 Flipper Zero 官方固件仓库原文档给出的完整流程如下Windows 下大概率无法直接运行建议使用 WSL 或 Linux 虚拟机git clone https://github.com/flipperdevices/flipperzero-firmware cd ./flipperzero-firmware git clone https://github.com/ranchordo/flipperzero-cli-bridge ./applications_user/flipperzero-cli-bridge/ ./fbt fap_dist APPSRCapplications_user/flipperzero-cli-bridge # 如果一切顺利构建出的 .fap 文件位于 ./dist/f7-D/apps/apps/Tools/cli_gui.fap要点说明applications_user/是固件为第三方用户应用预留的外部目录把仓库整体克隆进去后fbt fap_dist APPSRC...会只构建该目录下的应用输出的.fap文件名是cli_gui.fap由应用的appid决定见下文输出路径中的目录层级随固件版本的菜单归类不同而可能变化README 所述apps/Tools/对应当时固件的归类。2.3 应用清单application.fam解析本仓库副本中的 application.fam 定义了应用的元数据字段值说明appidcli_gui应用唯一 ID也是产物cli_gui.fap的文件名来源nameCLI-GUI Bridge菜单中显示的应用名apptypeFlipperAppType.EXTERNAL外部 FAP 应用可独立分发entry_pointcligui_main应用入口函数定义在 cligui_main.crequires[gui,cli]依赖 GUI 与 CLI 两个系统服务这是本应用的技术基础stack_size8 * 1024应用线程栈 8 KBfap_iconcligui.png菜单图标fap_categoryMisc_Extra菜单归类本仓库副本声明为 Misc_ExtraREADME 所述 Tools 目录为旧版固件表现实际菜单位置以当前固件为准三、使用手册在 GUI 里操作命令行启动应用后会进入Applications → Tools或 Misc_Extra下的 CLI-GUI Bridge。主界面是一个文本输入框即命令行提示符。3.1 输入命令直接输入命令文本例如subghz chat [频率单位 Hz如 310000000]输入空格快速按一下返回键Back即可输入一个空格在文本输入界面中长按键盘上的_键同样会输入空格源码实现见 text_input.c短按 Back 时向输入缓冲区末尾追加一个空格字符。3.2 执行与查看输出输入完成后导航并按下SAVEOK键应用切换到命令窗口控制台输出视图。此时用Up / Down上下滚动查看输出按Left 或 CenterOK回到文本输入框可以继续输入下一条命令在查看输出时快速点按一次返回键会向控制台发送Ctrl-C0x03中断当前命令在文本输入状态下长按 Left 或 Right可以不执行当前输入而直接跳回控制台输出视图。3.3 按键映射总表操作场景按键效果源码位置文本输入短按 Back输入一个空格text_input.c文本输入长按 Left / Right返回控制台输出视图不执行text_input.c文本输入OKSAVE提交命令并切换到输出视图cligui_main.c控制台输出短按 OK / Left回到文本输入框console_output.c控制台输出短按 Back发送 Ctrl-C 中断console_output.c控制台输出Up / Down滚动查看输出README 说明任意界面长按 Back正常退出应用cligui_main.c控制台输出长按 OK持久退出保留会话cligui_main.c四、两种退出模式普通退出 vs 持久退出这是本应用最有特色的设计README 用两个段落详细说明此处完整保留4.1 正常退出长按返回键约 1 秒按住再松开返回键长按至少 1 秒会正常退出应用此时内部终端会发送Ctrl-C 并关闭任何正在进行的会话都会被断开。4.2 持久退出在控制台输出界面长按 OK 键约 1 秒在聚焦控制台输出界面时长按 OK 键至少 1 秒会退出应用但保持终端会话开启。下次启动应用时终端输出会被清空但之前运行的命令或会话会继续恢复执行。这对subghz chat特别有用持久退出不会让你退出聊天频道而且即使应用已关闭Flipper 依然会在收到新消息时短暂振动提示。两种模式的差异从源码中可精确对应cli_control.c持久退出persist true不发送 Ctrl-C而是把 VCP 会话的is_connected回调替换为调试用函数furi_hal_version_do_i_belong_here使 USB 侧认为连接仍然存在从而保持 CLI 会话线程不被清理正常退出persist false向rx_stream写入字节0x03Ctrl-C中断并关闭内部终端。该开关由输入包装回调 cligui_main.c 维护长按 Back 时persistent_exit false长按 OK且当前为输出视图时persistent_exit true随后停止视图分发器退出清理阶段再把这个标志传给unlatch_tx_handler()。五、源码级原理CLI 是如何被桥接到 GUI 的整个应用由 7 个源文件构成cli-bridge 目录模块职责清晰文件职责cligui_main.c应用主流程视图分发器、事件循环、输入包装cligui_main_i.h应用数据结构、视图枚举、缓冲区尺寸定义cli_control.cCLI 会话接管/释放双向流缓冲与重定向cli_control.h桥接控制对外接口声明text_input.c命令输入处理空格、返回输出视图、提交console_output.c控制台输出视图的按键处理返回输入、Ctrl-Cinternal_defs.h固件内部结构体镜像用于绕过公开 API 做底层操作5.1 主流程cligui_main与视图调度入口函数 cligui_main 的执行链路接管 CLI调用latch_tx_handler()见 5.2建立数据流映射app_tx rx_streamGUI 输入写入 CLI 接收流、app_rx tx_streamCLI 输出从发送流读取初始化 GUI打开RECORD_GUI分配视图分发器并用自定义input_callback_wrapper覆盖 ViewPort 的输入回调以便在系统处理按键前拦截长按事件cligui_main.c注册两个视图ViewConsoleOutputTextBox 模块与ViewTextInputTextInput 模块其中文本框缓冲区预留TEXT_BOX_STORE_SIZE 4096字节、输入缓冲区为TEXT_INPUT_STORE_SIZE 512字节定义见 cligui_main_i.h启动初始切换到文本输入视图view_dispatcher_run进入事件循环清理退出循环后释放视图与缓冲区调用unlatch_tx_handler(persistent_exit)归还 CLI 会话关闭 GUI 记录。5.2 CLI 会话接管cli_control.c这是全应用最核心的部分。latch_tx_handler()cli_control.c做了几件越界的事打开全局RECORD_CLI通过内部结构从命令树中取出help命令的context作为CLI 线程句柄该命令是 CLI 初始化时注册的常驻命令其上下文恰好是 CLI 线程本身分配两个128 字节的流缓冲rx_stream/tx_stream作为 GUI 与 CLI 之间的管道构造一个自定义CliSessiontx回调把 CLI 线程的 stdout 重定向到tx_streamrx回调从rx_stream读取 GUI 送入的输入随后cli_session_closecli_session_open将当前会话替换为自己的会话直接清零Loader_internal-lock_count解除加载器对应用持有的锁避免退出时被系统拦截。unlatch_tx_handler(persist)cli_control.c则是逆向操作把 CLI 线程句柄存回help命令上下文、按持久标志决定发送 Ctrl-C 或保留连接、恢复cli_vcpUSB 虚拟串口会话与 stdout 回调并写入一个_字节解除阻塞的接收方后释放流缓冲。5.3 双向数据流全链路把输入与输出串起来看一次完整命令的旅程是文本输入框 → text_input_result_callback转小写 追加 \r\n → app_tx即 rx_stream→ CLI 会话 rx 回调 → CLI 命令执行 → CLI 线程 stdout → tx_handler_stdout → tx_stream即 app_rx → cligui_tick_event_cb 每 100ms 轮询读取 → text_box_store → TextBox 显示值得注意的实现细节提交处理text_input.c提交前会把所有大写字母ASCII0x41–0x5A转为小写0x20再连同\r\n一起写入app_tx流模拟终端回车换行输出刷新cligui_main.ctick 事件回调每 100 ms 轮询一次app_rx流中可读字节逐个取字节追加到text_box_store并刷新文本框同时反向计算最后一行文本作为输入框的提示头中断信号控制台视图短按 Back 时发送的正是 Ctrl-C 字符0x03console_output.c与终端语义完全一致。5.4 内部结构镜像internal_defs.h由于会话接管需要触碰固件不公开的内部状态internal_defs.h 以结构体镜像的方式重定义了FuriThread_internal、ViewDispatcher_internal、ViewPort_internal、Loader_internal、Cli_internal等内部类型字段布局与固件头文件保持一致通过强转指针实现对 CLI 命令树、线程 stdout 回调、ViewPort 输入回调、Loader 锁计数等底层字段的直接读写。这也是本应用侵入性的来源因此它要求与特定固件版本配套使用。六、注意事项与已知限制USB 功能可能暂时失效运行本应用后尤其是未关闭内部终端就退出的情况qFlipper 与普通 USB CLI 可能无法正常工作。只需重启 Flipper所有 USB 功能即可恢复正常README 原说明。固件版本强相关安装前必须升级到最新固件内部结构体镜像与固件内部实现耦合版本差异可能导致崩溃或功能异常预编译.fap只适配特定固件版本。构建环境源码构建在 Windows 上大概率不可行请使用 WSL 或 Linux 虚拟机。会话语义普通退出会强制断开会话发送 Ctrl-C需要保持subghz chat等会话请使用持久退出模式。七、结语flipperzero-cli-bridge用约 7 个源文件实现了GUI 输入 CLI 会话 输出回显的完整桥接其核心技巧在于通过固件内部结构镜像接管全局 CLI 会话并用两个流缓冲完成双向数据搬运。对于想要在设备本机直接使用subghz chat、查看系统诊断信息或开发类似嵌入式终端类应用的开发者本仓库的 cli_control.c 与 cligui_main.c 是极佳的学习样本前者展示了如何在应用层安全地替换系统会话后者展示了 ViewDispatcher 输入包装与轮询刷新的标准写法。【免费下载链接】FlipperPlayground (and dump) of stuff I make or modify for the Flipper Zero项目地址: https://gitcode.com/GitHub_Trending/fl/Flipper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考