企业官网建设流程全解析

F´ Ref 参考应用实战指南：在 Linux/macOS 上构建、运行与验证 F Prime 完整部署

【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址: https://gitcode.com/GitHub_Trending/fpr/fprime

F´（F Prime，即 Ref 参考应用）是 NASA 开源飞行软件框架自带的"完整组装演示"部署，用于在嵌入式硬件就绪之前，于 Linux 与 macOS 上快速体验一个包含指挥（Commanding）、事件（Event）、遥测通道（Channels）与参数（Parameters）的航天器软件系统。本文将带你完整走通从克隆源码、创建 Python 环境、生成构建目录、编译部署，到启动浏览器地面站（GDS）并验证遥测与命令收发的全流程，并结合仓库源码剖析 Ref 应用的拓扑结构、速率组调度与命令行参数机制。

1. Ref 参考应用是什么

Ref（Reference）是 F´ 框架自带的一个参考部署（Deployment），其目的正如 TestDeploymentsProject/Ref/README.md 所述：演示一个完全组装好的、可直接运行在 Linux 和 macOS 上的 F´ 应用。它让使用者无需等待嵌入式硬件即可：

• 快速上手 F´ 的工程流程（生成、构建、运行）；
• 验证 F´ 安装是否成功；
• 在纯软件环境里提前熟悉 F´ 的组件、端口与拓扑组织方式。

Ref 应用通过 Ref/docs/sdd.md 被描述为一颗"参考航天器"，集成了三类组件：

示例应用组件（部署特有）

可复用服务组件（来自 F´ 框架，可跨项目复用）

提示：若需要为真实嵌入式平台做交叉编译，README 建议参考 F´ 官方的 LED 闪烁（LED Blinker）教程；本文以 Linux/macOS 本机直接运行为主线。

2. 构建前的准备：安装 F´ 与创建虚拟环境

2.1 前置条件

理解 Ref 应用只需少量前提，最重要的是先完成 F´ 的安装，请按 安装指南 操作。安装完成后，fprime-util与fprime-gds等命令行工具即可用。

2.2 获取源码并进入部署目录

获取 F´ 仓库源码（例如git clone本仓库）后，进入 Ref 部署所在的工程目录：

git clone <F´ 仓库地址> # 例如克隆本 fprime 仓库 cd fprime/TestDeploymentsProject

注意：README 中的克隆地址为公开的 nasa/fprime 仓库；在本文所述场景下，你当前所在的仓库即为其源码本体，进入TestDeploymentsProject目录即可。

2.3 创建 Python 虚拟环境并安装依赖

F´ 的构建与地面站工具链依赖 Python 包，建议在独立虚拟环境中安装：

python3 -m venv fprime-venv . fprime-venv/bin/activate pip install -r ../requirements.txt

• 虚拟环境目录fprime-venv创建于TestDeploymentsProject之下；
• ../requirements.txt指向仓库根目录的依赖清单（即 requirements.txt），其中包含fprime-tools、fprime-gds等核心工具包。

2.4 工程配置文件说明

TestDeploymentsProject/settings.ini 是 F´ 工程级配置的示例，它声明：

[fprime] framework_path: .. project_root: . default_cmake_options: FPRIME_ENABLE_FRAMEWORK_UTS=OFF FPRIME_ENABLE_AUTOCODER_UTS=OFF

• framework_path指向上一级目录（即框架本体）；
• project_root指向当前工程；
• default_cmake_options默认关闭框架单元测试（UT）与自动代码生成器单元测试，以加快部署构建——这与 README 中"快速构建"的定位一致。

3. 生成构建目录并编译 Ref 应用

F´ 底层使用 CMake，需要一个构建目录来工作。fprime-util是 CMake 的封装工具，用于精简标准 F´ 流程。

3.1 生成构建目录

fprime-util generate

执行后会在工程内生成build-artifacts/<平台>/目录树。除非构建目录被删除，否则无需再次运行generate。

3.2 构建部署二进制

fprime-util build

该命令会针对当前系统（Linux 或 macOS）完成编译，产出可在本机直接运行的二进制。构建完成后，可执行文件位于build-artifacts/<平台>/bin/下（其中<平台>如default或linux-x86_64之类）。

3.3 构建定义与编译选项

Ref 的构建定义位于 TestDeploymentsProject/Ref/CMakeLists.txt，它通过add_fprime_subdirectory依次引入 PingReceiver、RecvBuffApp、SendBuffApp、SignalGen、TypeDemo、DpDemo、BlockDriver、Top 等子目录，再以register_fprime_deployment把 Main.cpp 注册为部署可执行文件，并依赖自动生成的_Top拓扑模块。

该文件还为部署二进制启用了严格告警并视告警为错误：

target_compile_options("${PROJECT_NAME}" PUBLIC -Wall -Wextra -Werror -pedantic) target_compile_options("${PROJECT_NAME}" PUBLIC -Wshadow -Wconversion -Wsign-conversion -Wformat-security -Wnon-virtual-dtor -Wold-style-cast -Woverloaded-virtual -Wundef)

这说明 Ref 不仅是功能参考，也是 F´ 推荐的编译规范参考；注释中说明这些严格选项仅作用于部署可执行文件，以免在核心框架代码中触发冗余告警。

3.4 小技巧：单独构建组件

fprime-util build同样支持构建单个组件，例如只需编译 SignalGen 时可以指定其目录，详见第 7 节"快速提示"。

4. 运行 F´ 地面系统与 Ref 应用

F´ 自带一个基于浏览器的测试地面系统（GDS），用于帮助开发者低开销地快速测试 F´ 代码。

4.1 一键启动：GDS + Ref 应用

在运行 GDS 之前，请确保已经完成上述fprime-util build构建。然后执行：

cd fprime/TestDeploymentsProject fprime-gds

fprime-gds会自动同时启动 Ref 应用二进制，实现开箱即用的快速测试，这正是 Linux/macOS 上的典型体验。启动后浏览器会打开 GDS 界面，你可以在以下标签页观察 F´ 的实际运行：

• Commanding（命令）：向 Ref 应用发送命令；
• Event（事件）：查看应用上报的事件流；
• Channels（通道）：查看遥测通道的实时数值与曲线；
• Logs（日志）：查看运行日志，其中Logs -> Ref.log展示 Ref 应用的标准输出，出错时可在此排查。

4.2 只启动 GDS，不启动 Ref 应用

cd fprime/TestDeploymentsProject fprime-gds --no-app

随后可手动从构建产物目录独立运行 Ref 应用：

cd fprime/TestDeploymentsProject/build-artifacts/<platform>/bin/ ./Ref -a 127.0.0.1 -p 50000

4.3 命令行参数解析原理

./Ref支持的-a与-p参数解析逻辑在 TestDeploymentsProject/Ref/Main.cpp 中，使用getopt实现：

while ((option = getopt(argc, argv, "hp:a:")) != -1) { switch (option) { case 'a': hostname = optarg; break; // -a：主机名/IP 地址 case 'p': port_number = static_cast<U16>(atoi(optarg)); break; // -p：端口号 case 'h': default: print_usage(argv[0]); return (option == 'h') ? 0 : 1; } }

参数被存入Ref::TopologyState inputs后传入Ref::setupTopology(inputs)：

• 若hostname与port均有效，RefTopology.cpp 会调用comDriver.configure(hostname, port)配置 TCP 客户端，并启动名为ReceiveTask的接收线程（优先级 34）；
• 主程序随后调用Ref::startRateGroups(Fw::TimeInterval(1, 0))以1Hz 周期驱动系统循环，并注册SIGINT/SIGTERM信号处理：按下Ctrl-C时通过Ref::stopRateGroups()停止速率组，再执行Ref::teardownTopology完成资源回收后正常退出。

4.4 GDS 帧格式配置

TestDeploymentsProject/Ref/fprime-gds.yml 指定了 GDS 的链路层帧格式：

command-line-options: framing-selection: space-packet-space-data-link

即选用"空间数据链路 + 空间包"（CCSDS 风格）的组帧方式，与 Ref 部署中 Ccsds 子拓扑使用的编解码器相匹配。

5. 深入源码：Ref 应用的拓扑与运行机制

5.1 拓扑总览：四类连接视图

Ref 的拓扑定义在 TestDeploymentsProject/Ref/Top/topology.fpp，其内部模块连接图（IBD）由 Ref/docs/sdd.md 按功能维度拆分讲解，核心视图包括：

• Commanding（指挥）：组件注册命令、命令分发与执行状态回传的连接；
• Telemetry（遥测）：组件向TlmChan更新遥测通道的连接；
• Logging（日志）：组件向EventManager发送事件的连接；
• Parameters（参数）：组件从PrmDb读取/更新参数的连接；
• Time（时间）：组件获取时间戳用于事件与遥测时间标签的连接；
• Health（健康）：Health组件 ping 活动组件验证线程存活的连接；
• Rate Groups（速率组）：组件以不同频率被执行的连接；
• Ground（地面）：通过 TCP/IP 套接字与地面系统通信的连接；
• Drivers（驱动）：示例"驱动"收发数据包并为RateGroupDriver提供节拍（tick）的连接。

^{速率组视图：展示 Ref 拓扑中三个 ActiveRateGroup 如何将组件按不同速率调度执行（图片来自 Ref/docs/sdd.md）。}

^{地面视图：C&DH 组件通过 TCP/IP 套接字与地面系统收发命令与遥测（图片来自 Ref/docs/sdd.md）。}

5.2 组件实例与 Base ID 规划

TestDeploymentsProject/Ref/Top/instances.fpp 定义了 Ref 的全部组件实例及其 Base ID，遵循0xDSSCCxxx八位十六进制约定：

• D= 部署位（1-F）；
• SS= 子拓扑位（00 为主拓扑）；
• CC= 组件位；
• xxx= 组件内部条目（事件、命令、遥测）预留。

示例：blockDrv的 base id 为0x10000000，rateGroup1Comp为0x10001000，comDriver为0x10025000。活动组件（如blockDrv、三个ActiveRateGroup）还配置了队列大小（默认QUEUE_SIZE = 10）、栈大小（默认STACK_SIZE = 64 * 1024）与线程优先级（如blockDrv优先级 47、rateGroup1Comp43、cmdSeq20）。

5.3 1Hz 时钟驱动的三级速率组

Ref 拓扑在connections RateGroups中把linuxTimer.CycleOut接到rateGroupDriverComp.CycleIn，并由RateGroupDriver分频驱动三个速率组。其分频器配置在 RefTopology.cpp：

Svc::RateGroupDriver::DividerSet rateGroupDivisorsSet{{{1, 0}, {2, 0}, {4, 0}}};

即以1Hz 时钟为基准，分频出 1Hz、1/2Hz、1/4Hz三条节拍（偏置均为 0），分别对应三个 ActiveRateGroup。每个速率组的成员槽位在 topology.fpp 中分配，例如：

• rateGroup1（1Hz）：调度 SG1、SG2、遥测发送（tlmSendRun）、文件下传、系统资源采样、命令队列、命令分发等；
• rateGroup2（1/2Hz）：调度命令序列器、SendBuffApp、SG3/SG4、DpDemo、文件管理、WASM 序列器定时；
• rateGroup3（1/4Hz）：调度健康检查、SG5、BlockDriver、缓冲区管理、数据产品（Dp）相关组件与事件处理。

被调度组件的schedIn即由这些速率组周期调用。该机制保证遥测、健康监控、文件传输等任务以确定性的节拍运转。

5.4 启动与拆除流程

RefTopology.cpp 中setupTopology依次执行自动生成的初始化（initComponents、setBaseIds、connectComponents、configComponents、regCommands、参数装载、startTasks），随后做项目特定配置：

rateGroupDriverComp.configure(rateGroupDivisorsSet); rateGroup1Comp.configure(rateGroup1Context); // ... cmdSeq.allocateBuffer(0, mallocator, 5 * 1024); // 命令序列缓冲 5 KiB FileHandling::fileUplink.configure("."); FileHandling::fileDownlink.configure("."); FileHandling::prmDb.configureSandbox("."); // 文件访问沙箱限定在工作目录

teardownTopology则负责停止任务、回收命令序列缓冲并拆除组件，保证 Ctrl-C 退出时资源释放干净。

6. 用集成测试验证 Ref 应用

Ref 部署附带了一套可复用的集成测试参考实现，位于 TestDeploymentsProject/Ref/test/int/ref_integration_test.py，演示了 F´ 集成测试的标准写法：

• test_is_streaming：在 10 秒内断言收到至少 5 条遥测更新，并验证Ref.sendBuffComp.SendState通道的值为SEND_IDLE——这是"飞行软件在正常流式输出"的快速冒烟检查；
• test_send_command：通过send_and_assert发送一对 NO-OP 命令，验证命令的发送、分发与回执全链路；
• 事件过滤：通过CdhCore.events.SET_EVENT_FILTER命令按严重级别（COMMAND、ACTIVITY_LO/HI、WARNING_LO/HI、DIAGNOSTIC）启用或禁用事件上报，测试EventManager的过滤能力。

配套的还有 test_cmd_parameter.py、序列文件 test_seq.seq 与 int_config.json 等，可作为你自己的部署工程编写集成测试的模板。

7. 快速提示与下一步学习

原文档总结了三条高频实用提示：

• GDS 默认端口为 50000。更多参数可执行fprime-gds --help查看（例如自定义端口、串口/回环地址等）；
• fprime-util build可以只构建单个组件，适合在大型部署中仅重编译所修改的组件以节省时间；
• fprime-util generate可附带工具链参数，用于快速生成交叉编译目录，例如fprime-util generate raspberrypi即生成树莓派交叉编译目标（需已配置对应工具链）。

进一步熟悉 F´ 的工程化开发流程，可以继续阅读 HelloWorld 教程；若想深入理解 Ref 部署每一张拓扑连接图（指挥、遥测、日志、参数、时间、健康、速率组、地面、驱动）的细节，可直接研读 Ref 部署 SDD 文档 及其配套的 TestCases.txt。

8. 小结

通过本文，你已经掌握了在 Linux/macOS 上以"零嵌入式硬件"方式运行 F´ 参考应用的完整链路：clone → venv → pip install → fprime-util generate → fprime-util build → fprime-gds，也理解了 Ref 应用背后由组件实例、Base ID、三级速率组与 TCP/IP 地面通信构成的拓扑骨架，以及Main.cpp中-a/-p参数与 Ctrl-C 优雅退出的实现细节。Ref 不仅是快速验证 F´ 安装的试验台，更是一份可直接参照的部署工程范例——从 CMakeLists.txt 的构建规范，到 ref_integration_test.py 的测试范式，都值得在真实 F´ 项目中复用。

【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址: https://gitcode.com/GitHub_Trending/fpr/fprime