FreeJoy：不必自己编写固件，也能制作 USB 驾驶舱面板

FreeJoy 能替你完成哪些工作

FreeJoy 是可自由获取、能够配置的游戏控制器固件，可用于自制按钮盒、脚舵、摇杆和油门。对于已经支持的功能，你不必亲自编写程序：在配置工具中分配引脚、选择开关行为、校准控制轴，再把设置写入设备即可。它省去了 USB 报告、输入处理和许多常见控制逻辑的开发工作。

机械结构、正确接线和游戏内命令分配仍然需要你完成，但这些可以分成很小的步骤。先接一个按钮，观察它是否按预期响应，再加入第二个元件。没有编程经验并不妨碍这样开始。如果你需要自己编程的数据显示屏，可以接着阅读 AI 与编程指南。输入控制器和自定义显示项目可以互相补充，但不是同一个数据任务。

先确认开发板与软件版本

原始项目面向 STM32F103C8，常见载板为 Blue Pill。电路板颜色不能证明兼容性：使用 F401/F411 的 Black Pill、ESP32 或 Arduino Uno 不能直接使用同一个固件文件。应检查芯片丝印、原理图、存储器要求和具体固件的目标平台。外观相似的克隆板也不是自动获得验证的替代品。

ST 官方为 F103C8 标注的 Flash 容量是 64 KB。这里仅作为数据检查的 1.7.3b0 发布文件位于该 64 KB 范围内，不需要假设芯片有额外的 128 KB 空间。这仍然不能代替对实际开发板和正确安装流程的检查。

截至 2026 年 10 月 18 日，官方发布页面把固件 v1.7.3b0 和 Qt 配置工具 1.7.3b0 列为最新发布，页面标题为 1.7.3。应搭配使用相匹配的版本。旧配置和旧接线图不能直接照搬，例如发布说明记录过 I²C 引脚位置的改变。微控制器选型比较能帮助你区分型号；更高的处理器频率不能让一份固件自动适配另一颗芯片。

USB HID、DirectInput 与 DX 按钮

HID 是 Human Interface Device，即人机接口设备。安装合适固件后，FreeJoy 会作为 USB 游戏控制器被识别，并使用 Windows 的 HID 基础设施。完成设置后，正常使用输入功能时不需要一直开着配置工具。你可以连接面板、检查设备是否出现，再使用已经保存的模拟器按键配置。

DirectInput 是 Windows 供游戏读取控制器的一种接口。“DX 按钮”只是设备报告的一次摇杆按钮输入，本身并不包含“放下起落架”等完整命令。具体意义由模拟器内的绑定决定。XInput 是另一种接口，只支持 XInput 的游戏不一定识别这个控制器。某些旧模拟器还会限制可用按钮数。因此在制作大型面板之前，要同时检查 Windows 识别情况和目标游戏的实际支持范围。

规划一个容易完成的小面板

示例面板包含四个瞬时按钮、一个保持式开关、一个带按压功能的增量编码器，以及一个 10 kΩ 线性电位器。需求是四条独立命令、某个可用功能的分别开启和关闭、两个调整方向以及一条连续控制轴。先在你使用的飞机或车辆中确认这些命令是否能够分别绑定，再决定面板上的文字标识。

下表是适用于合适 Blue Pill 和新配置的一份引脚规划建议。所有列出的数字输入使用 Button_Gnd，触点闭合时接到共同地线。电位器两端接 3.3 V 和 GND，滑动端接 A0。接线时必须断电，并核对自己板上的丝印和引脚功能。USB、编程接口以及已经用于其他总线的引脚不能因为“看起来空着”就重复分配。这个表是设计示例，不是已在你的硬件上完成的验证。

从空白开发板到第一个输入

如果已有能够工作的控制器，先保存当前配置并记下固件版本。对于空白开发板，项目提供通过 ST-Link 或 USB-UART 进行首次烧录的说明。应按照与你的启动方式、电源连接和文件类型相符的官方步骤操作。仅连接一根 USB 线，不会使空白芯片自动变成 FreeJoy 设备。理解和加载固件介绍了这一过程的基础。

固件运行后，先读取设备配置，只把 B12 设置为 Button_Gnd，再执行“Write Config to Device”。按下第一个按钮，在物理按钮区域找到实际编号，把它映射到普通逻辑按钮，然后再次写入并检查。“Save Config to File”是在电脑上另存备份，不能代替写入设备。拔下再接回 USB，确认设置仍然生效，之后再添加其他接线。每一步都有看得见的结果，就不容易把多个问题混在一起。

区分物理触点和逻辑按钮

物理按钮代表检测到的触点，逻辑按钮代表发送给电脑的信号，两者编号不一定相同。建议记录三列：元件名称、物理输入编号、逻辑输出编号。同一个物理输入可以对应多个逻辑功能。例如保持式开关可用 ToggleSwich_On 在闭合时产生脉冲，用 ToggleSwich_Off 在断开时产生另一脉冲。只有模拟器确实提供独立开、关命令时，才能据此得到明确的两种动作。

Button_normal 跟随触点状态，Button_Toggle 则在每次按下时改变保存的逻辑状态。消抖用于抑制触点抖动，Delay Timer 延迟激活，Press Timer 在适用的模式下决定逻辑按压持续时间。先用默认值，一次只调整一个参数。过长的消抖会忽略很短的有效按压，过长的脉冲可能在游戏中变成长按。还要测试模拟器启动时开关已经处于打开位置的情况，不能只测试启动后的拨动。

扩展功能与输入数量

项目文档列出最多 128 个数字输入、8 条轴、4 个 POV 帽开关和 5 个 Shift 修饰键。这些是功能上限，并不意味着任意组合都能同时避开引脚和资源冲突。Radio 分组保持选中的逻辑功能，顺序模式通过反复按压轮换分配项，Shift 可以增加一层按键用途。应在面板上明确标记这些层，避免飞行中猜测当前功能。

输入可以直接接引脚，也可以通过矩阵或受支持的移位寄存器扩展。矩阵需要按照项目接线图安排正确的行、列和二极管，尤其要测试多个按钮同时按下。74HC165 和 CD4021 的 Clock、Data、Latch 必须按对应芯片配置，文档建议使用 3.3 V。74HC595 是另一类用途的器件，不能当作相同输入扩展器替换。关于按钮和开关本身的机械选择，可阅读操作元件指南。

其他已记录功能包括四路用于照明的 PWM，以及最多 24 颗独立或矩阵连接的 LED。1.7.3 版本加入 WS2812b/PL9823 可寻址 LED、按钮触发、单色 LED 计时器，以及通过 USB HID 和配置工具进行外部控制。项目列出的可寻址 LED 上限为 50 颗。UART TX 报告还可以向外部设备提供数据。但这些功能本身不会自动生成所需的模拟器遥测，也不代表已经验证了 Cockpit Suite 集成。

编码器：旋转和按压是两回事

增量编码器输出两路有相位差的信号，FreeJoy 根据它们判断旋转方向，再生成两个逻辑按钮或者改变轴值。编码器上的按压开关是单独的触点。Wiki 区分最多 15 个普通编码器和一个高速编码器；Fast_Encoder 使用 A8、A9，不能随便换成其他空闲引脚。此处示例使用普通编码器，A/B 两路接 B6/B7，按压开关接 B8。

按照说明分配 Encoder_A、Encoder_B。先向每个方向慢慢转十个定位格，再提高速度，比较实际触发次数。方向反了、一次产生两步、快速旋转漏步，对应的检查点不同：通道顺序、编码器类型、接触质量和时间参数。Wiki 给出的编码器脉冲默认值是 10 ms，并建议小于 50 ms；这不代表所有模拟器的最佳数值。根据能够重复的测试调整，而不是一次改动所有设置。

模拟轴：从传感器到有效行程

把 A0 设置为电位器的模拟来源，再映射到一条逻辑轴，例如 X。关闭没有使用的轴。FreeJoy 还记录了 AS5600、特定 TLE501x 型号等数字传感器，以及 ADS1115、MCP3201/02/04/08 等外部 ADC。准确型号、总线、通道以及配置版本都很重要。支持这些器件不代表任意霍尔模块或任意 I²C 模块都能直接使用。

先观察原始数值，确认机械移动时数值能够连续、合理地增加或减少。开始校准后，把机构移到实际可达到的两端，再保存结果。自回中的控制器还需要记录静止中点；油门杆通常不需要人为添加中心位置。内部模拟输入的分辨率为 12 位。USB 输出范围里更大的数字并不会凭空增加传感器精度，也不会消除轴承间隙和机械松动。

合理设置死区、滤波与曲线

中心死区忽略中点附近的小幅波动，动态死区处理当前值附近的小变化。两者都有可能隐藏你希望保留的细微操作，因此应从较小设置开始。七级滤波能平滑读数，但会增加延迟；项目不建议对响应时间敏感的轴使用高于 Level 3 的设置。滤波再强也不能修复接触不良或松脱的线。

反向设置改变轴的方向，曲线则改变不同位置的灵敏度。Prescaler 缩放、组合轴、用按钮增减或居中和复位、把轴区间转换成按钮，都是文档中的其他工具。先建立可靠的线性响应，再加入真正需要的功能，并保留修改前的配置作为比较。FreeJoy 和模拟器中的曲线会叠加；如果两边同时调整，很难判断是哪一个设置改变了手感。不要把所有可选功能都当成必须启用的步骤。

在模拟器中验证并定位故障

在 Windows 中打开 joy.cpl，进入游戏控制器属性。先检查编号较小的按钮和示例轴。传统属性窗口可能无法显示一个大型控制器的全部按钮，超出其显示范围没有指示，不等于设备坏了。随后只绑定一个模拟器功能，测试按下、保持、松开、重新连接和重启。每个动作都应符合计划，而且不应误触相邻输入。

原始接点没有变化，先看接线和引脚模式；物理输入正确而逻辑输出没有变化，检查映射、Shift 条件和计时器；Windows 有反应而游戏没有，检查设备选择、按钮数量限制和重复绑定。若要在 LED 或 OLED 上显示真实起落架状态，还需要单独的返回遥测路径。已记录的 LED 输出和主机控制也不能代替合适的模拟器集成。可继续阅读 USB 输入与系统排错。

和社区一起推进你的项目

每完成一个阶段，就保存配置、引脚表和简短测试记录，装入外壳前给已标记的连接拍照。这样的提问更容易得到帮助：“B12 的物理输入会变化，但逻辑按钮 1 不动；固件和配置工具都是 1.7.3b0；Shift 已关闭。”在 Cockpit Suite 论坛中，我们也帮助讨论 3D 打印外壳、CNC 龙门铣床加工面板以及使用 LightBurn 的激光制作问题。

Cockpit Suite 是一个年轻项目，已经提供适用于受支持模拟器和设备的软件。我们的目标是共同的软件环境，以及适合组合下尽可能简单的设置过程；这并不是未经验证的 FreeJoy 集成承诺。遇到问题时，我们希望和你一起找到下一步，并争取尽可能当天回复，太晚提交的问题可能稍后处理。欧洲社区以及其他地区用户的实际经验能推动说明和支持流程继续改进。即使只是第一个有清楚记录的按钮，也能帮助下一位初学者。

继续下一步制作