先说句实在话FreeJoy 这东西最近在飞行模拟、赛车模拟和自定义工控面板圈子里越来越火。它的本质是一套跑在 STM32F103 上的开源 USB 游戏控制器固件能把单片机变成标准手柄、XInput 手柄甚至 HID 键盘鼠标。做模拟飞行油门面板、赛车踏板、自定义按钮盒FreeJoy 基本是绕不开的方案。我前前后后用 FreeJoy 做了两套飞行模拟油门台和一套赛车踏板中间在 Windows 11 上折腾 joy.cpl 不显示问题花的时间比焊板子还长。这篇文章就把从 STM32 烧录到 Windows 11 识别、再到 joy.cpl 正常显示的完整流程整理出来给正在踩坑的朋友一个参考。1. 先搞懂 FreeJoy 是什么为什么 STM32 方案这么流行1.1 FreeJoy 的核心能力FreeJoy 是社区开发者维护的开源项目早期从 STM32 的 USB HID 库发展而来现在已经相当成熟。它支持 STM32F103C8T6 和 STM32F103CBT6 这两颗最常见的芯片简单的说就是淘宝上几十块钱的“蓝板”基本都能跑。配置器是 Windows 图形界面不需要写代码画几个按钮、拖几条轴点一下烧录就能变成游戏控制器。它支持的功能包括最高 32 个按钮标准 HID 模式、模拟轴输入电位器、旋转编码器轴、按键去抖、LED 输出、PWM 输出甚至还能模拟鼠标和键盘。协议方面可以配置成 DirectInput 标准手柄也就是 joy.cpl 里能看到的“游戏控制器”、XInput模拟 Xbox 360 手柄、HID 键盘鼠标等。1.2 为什么选 FreeJoy 而不是 MMJoy2 或其他方案圈子里还有一个常见的类似方案叫 MMJoy2早期用的人也很多。但我个人对比下来FreeJoy 的优势主要有三点配置器界面更友好实时读取和写入配置改完不用反复重新烧录整个固件。固件带 Bootloader可以直接通过 USB 升级固件不需要每次拆机插 ST-Link。社区更新活跃支持 XInput、自定义 VID/PID、旋转编码器等功能适配模拟飞行这类复杂外设比 MMJoy2 更顺手。1.3 适合谁用如果你是模拟飞行玩家想要一套自定义油门、配平轮、紧急按钮面板或者赛车模拟玩家想做一套独立手刹、旋钮面板又或者你想把淘汰的 STM32 开发板做成一个生产工具FreeJoy 都是很合适的方案。需要的技能门槛是会基本接线、会用 ST-Link 下载器、有耐心查驱动问题。2. 烧录前的准备硬件、固件、下载器一次配齐2.1 硬件选型STM32F103C8T6 还是 CBT6淘宝上最常见的“STM32F103C8T6 最小系统板”就能用Flash 是 64KB对于大多数按钮盒和油门面板足够。如果功能特别多或者你想用步进电机、复杂的编码器组合建议选 STM32F103CBT6Flash 128KB编译大固件时不用抠门。选板子的时候有一个关键点要检查USB 数据引脚 PA11USB_D-和 PA12USB_D是否引到了 USB 座子上。很多蓝板上的 USB 座只是供电用的数据脚没接出来需要自己飞线到 USB 座或者排针。另外USB D 需要 1.5k 上拉到 3.3V部分板子有部分没有买之前看图最稳。2.2 固件下载Bootloader 版和全量版别搞混去 FreeJoy 的 GitHub Release 页面下载固件一般会看到两个文件夹Bootloader 和 App。Bootloader 文件是负责 USB 升级的小程序App 才是真正跑游戏手柄逻辑的固件。我的建议很直接如果手里有 ST-Link就直接下全量固件通常叫 FreeJoy_Bootloader_App 之类的名字一次烧进去Bootloader 和 App 都有了以后升级固件再也不用拆机。如果手里的板子已经有人帮你烧好过 Bootloader那后面就可以直接走 USB 升级流程。2.3 下载器与烧录工具烧录 STM32F103 最常用的是 ST-Link V2十几块钱的兼容版就能用。软件方面建议用 STM32CubeProgrammer这是 ST 官方工具Windows 10/11 都能跑。驱动方面ST-Link 插上后 Windows 11 一般会自动装驱动如果没装去 ST 官网装 STSW-LINK009 驱动即可。提示烧录之前先确认 ST-Link 和电脑连接正常在设备管理器里能看到 ST-Link 对应的调试接口。不然到了烧录那一步才发现连不上芯片排查起来会很痛苦。3. STM32 烧录 FreeJoy 固件实操从接线到写入一次说清3.1 ST-Link 接线与启动模式把 ST-Link 和 STM32 最小系统板用杜邦线连接只需 4 根线3.3V 接 3.3VGND 接 GNDSWDIO 接 PA13SWCLK 接 PA14。如果板子的复位引脚不好触发可以再接一根 RST 到 ST-Link 的 NRST但不接一般也能烧。这里有两个容易踩的坑不要同时用 ST-Link 的 3.3V 和 USB 线给板子供电两个电源打架容易烧芯片。要么只插 ST-Link要么只插 USB。板子上的 BOOT0 引脚要拉低接 GND 或不接让芯片从主 Flash 启动。如果 BOOT0 拉高芯片会进入系统引导程序SWD 烧录虽然也能连上但烧完程序可能不会按预期运行。3.2 用 STM32CubeProgrammer 烧全量固件打开 STM32CubeProgrammer右上角选择 ST-LINK然后点 Connect。正常情况下右下角会显示芯片型号 STM32F103C8 或 CB并读出 Flash 大小。烧录步骤很简单点击左侧的 Erase Programming 页面。File 选择下载好的全量固件比如FreeJoy_Bootloader_App.hex。地址保持默认即可hex 文件自带地址信息。勾选 Verify After Programming点 Start Programming。烧完后点 Disconnect再按一下板子上的复位键。如果只是刷 App 而不想动 Bootloader那就单独选 App 固件。不过要注意烧录地址不能乱填如果烧到错误地址设备可能变成“未知 USB 设备”到时候还得重来。3.3 带 Bootloader 的优势以后升级不用拆机全量固件烧好之后把板子通过 USB 线插到电脑按住板子上的 BOOT0 按键再插 USB不同板子进入 Bootloader 的方式不同如果枚举出来一个 FreeJoy Bootloader 设备说明 Bootloader 工作正常。之后直接用 FreeJoy 配置器的固件更新功能从 USB 刷入新版本 App再也不用拆机插 ST-Link。从我个人经验来看烧录这部分最容易出的问题不是焊接而是供电不稳定。STM32F103 的 USB 对电源比较敏感如果电脑 USB 口供电纹波大或者线又长又细枚举时很容易变成“设备描述符请求失败”。遇到这种问题先换线、换口再考虑飞线问题。4. FreeJoy 配置器把单片机变成“手柄”的关键一步4.1 安装 FreeJoy 配置器固件烧好只是第一步真正决定设备行为的是 FreeJoy Configuration Utility。这个配置器从 FreeJoy 官网或者 GitHub 下载绿色软件解压就能跑。打开后插上设备界面会提示检测到 FreeJoy Device。第一次插上设备时Windows 11 可能会弹窗提示驱动未安装或设备识别异常先别慌第 5 部分会专门讲驱动的事。4.2 按钮与轴的引脚映射配置器的界面不算复杂核心是 Pins 页面。在这里你可以把芯片的每个引脚映射成按钮、轴输入、LED 输出等。按钮设置非常简单选中某个引脚在右边功能里选 Button填写按钮编号1-32然后 Write 到设备。轴就稍微复杂点FreeJoy 支持很多轴类型ADC 轴接电位器适合油门、踏板这类模拟量输入12 位分辨率校准后线性度很好。编码器轴接 AB 两相旋转编码器适合做配平轮、音量旋钮脉冲数可以自己设置。数字轴用开关切换某个轴的 0/100% 输出适合襟翼档位选择。给新手一个建议一开始别贪多先在板上接一个按钮、一个电位器验证整条链路通顺了再扩展其他引脚和轴。不然几十根线接完万一 joy.cpl 里没反应排查起来会怀疑人生。4.3 设备类型与 USB 描述符设置这是最能决定 joy.cpl 能不能显示设备的地方也是最容易被忽略的坑。在配置器的 Firmware Settings 页面里有一个 Device Type 选项。如果选的是 Joystick标准 HID 游戏控制器那么 Windows 会把它识别为“游戏控制器”在 joy.cpl 中能看到。如果选的是 Generic HID 或者 Keyboard/Mouse那它就是一个 HID 输入设备不会出现在游戏控制器列表里。还有一个关键是 VID/PID。FreeJoy 默认的 VID/PID 大多数情况下没问题但如果系统里装了别的驱动抢占了或者之前装过其他手柄驱动可能需要改成不冲突的数值。改完 VID/PID 之后需要重新 Write 一下配置并重新插拔 USB。注意如果你选择了 XInput 模式设备会被识别成 Xbox 360 控制器这是很多人搞不懂的地方——XInput 设备不会在 joy.cpl 里显示它通过另一个体系被系统识别游戏里能识别但传统面板列表里就是没有。想确认 XInput 设备是否正常工作可以用支持 XInput 测试的工具或者直接进游戏看手柄映射。4.4 写配置与验证所有引脚和参数设置完后点 Write Configuration to Device配置器会把数据写入芯片。然后重新插拔 USB再看设备管理器这时候一般会多出一个 HID 兼容的游戏控制器。在 FreeJoy 配置器的 Test 页面你可以直接看到按钮按下时引脚状态是否翻转、轴值是否跟着电位器变化。这是我最喜欢的一步不用开游戏就能确认物理接线和配置是否正确。5. Windows 11 驱动与 joy.cpl 显示问题全排查5.1 正常情况下的 Windows 11 识别流程如果你的 FreeJoy 配置成标准 HID Joystick插入 Windows 11 后系统通常会自动装上“HID 兼容的游戏控制器”驱动打开 joy.cpl按 WinR 输入 joy.cpl 回车就能看到设备。整个过程不需要手动装任何驱动。但现实往往没那么顺利Windows 11 对驱动签名和 USB 枚举的要求比 Win10 更严格经常出现设备管理器能看到、joy.cpl 看不到或者干脆设备管理器里就是个带黄叹号的未知设备。下面按现象分情况排查。5.2 joy.cpl 不显示的六种典型原因我把这段时间大家反馈最多的问题整理成一个速查表按顺序排查基本都能解决现象可能原因解决方法设备管理器里完全没有设备USB 线/供电/固件没烧对换线、换 USB 口检查烧录是否成功设备管理器里有“未知 USB 设备设备描述符请求失败”USB 上拉/飞线问题或 Bootloader 和 App 冲突检查 D/D- 接线重新烧全量固件有“FreeJoy Device”但黄叹号驱动未正确安装手动更新驱动选 WinUSB 或 HID 驱动人体学输入设备里有 FreeJoy但 joy.cpl 没有设备类型配成了 Generic HID 或 XInput回配置器改成 Joystick重新写配置joy.cpl 里能看到设备但按钮和轴没反应引脚映射没写进去重新 Write 配置用 Test 页面验证游戏里识别正常但 joy.cpl 里就是没有设备处于 XInput 模式这是正常现象改用 XInput 测试工具确认5.3 Windows 11 独有的坑驱动签名与 WinUSBFreeJoy 设备在 Bootloader 模式或者需要配置器直接通信时可能要用到 WinUSB 驱动。Windows 11 默认对未签名驱动卡得很严上手就装失败是常有的事。我自己最常用的方案是 Zadig。打开 Zadig 后选 Options 里的 List All Devices找到 FreeJoy Device注意别选成别的 USB 设备尤其别选 ST-Link 的调试接口不然 ST-Link 也会被废掉目标驱动选 WinUSB然后点 Install Driver 或 Replace Driver。装完再插拔一次设备管理器里一般就是正常的 FreeJoy Device。如果 Zadig 也装不上就要临时禁用 Windows 11 的驱动程序强制签名打开 设置 - 系统 - 恢复 - 高级启动 - 立即重新启动。重启后选择 疑难解答 - 高级选项 - 启动设置 - 重启。重启后按数字键 7 或 F7选择“禁用驱动程序强制签名”。在这种模式下把驱动装好然后正常重启即可。这个方法只影响当前启动过程下次重启签名强制会自动恢复不需要额外操作。不建议长期开启测试签名模式纯属给自己找麻烦。5.4 从“设备描述符请求失败”到救砖的实际复盘我第一次用 FreeJoy 时遇到过一个很典型的问题板子是蓝板USB 座竟然只接了电源PA11/PA12 根本没引到座子上。我一开始没检查烧录完固件插上电脑设备管理器直接报“设备描述符请求失败”。排查了很久最后用万用表测了 USB 座的 D/D- 对地电压才发现根本没信号出来。后来飞线把 PA11、PA12 接出来D 加上 1.5k 上拉到 3.3V再插电脑就正常枚举了。关键教训是蓝板虽然便宜但 USB 电路不一定完整买回来先查 USB 座四根针是不是都连到主芯片省得后面反复折腾。另外一个复盘经验是刷完新固件后如果设备变成未知设备不要马上怀疑硬件坏了优先检查 Bootloader 是否还活着。FreeJoy 的 Bootloader 在 USB 枚举时会有独立的设备名如果插上 USB 出现的不是 FreeJoy Device而是 FreeJoy Bootloader说明 App 没跑起来。这时候重新用配置器刷 App或者回到 STM32CubeProgrammer 烧全量固件就能救回来。5.5 排查流程建议从简单到复杂给你一条我实际用的排查顺序遇到问题照着走效率最高看设备管理器里有没有设备。没有就先换线、换 USB 口插到主板上后置 USB 2.0 口测试。如果有黄叹号右键设备看属性记录错误码。代码 10 通常是驱动问题代码 43 通常是 USB 硬件枚举问题。确认设备是不是处于 Bootloader 模式。如果是重新刷 App。回到 FreeJoy 配置器Read Configuration看看固件里 Device Type 到底设置成了什么。把配置改成标准 Joystick 模式VID/PID 恢复默认Write 后重新插拔。打开 joy.cpl按 F5 刷新。如果还是看不到重启一次电脑再试。这些都试过还不行再考虑驱动签名和 WinUSB 的问题。6. 实操心得与后续扩展建议这套流程跑通之后后面再做新的外设就很顺了。我个人的体会是FreeJoy 的上手曲线其实很平滑最大的障碍集中在“USB 枚举”和“协议类型”这两个环节。只要明白标准 HID Joystick 才进 joy.cpl、XInput 不进 joy.cpl以及 Bootloader 模式和运行模式是两套 USB 行为大部分问题都能定位到具体环节。最后再分享一个实用小技巧每次改完配置并 Write 到设备后不要急着拔线先在配置器的 Test 页面把所有按钮和轴都过一遍。这样能在系统层面出问题之前先确认硬件和固件是否正常。我后来几乎不用 joy.cpl 验证接线都是直接在这个页面里看信号状态省时间也省心。如果后续你想把设备做得更专业还可以试试 FreeJoy 的扩展功能用旋转编码器做配平轮用 PWM 输出控制背光 LED或者用 XInput 模式让现代游戏直接识别成 Xbox 手柄。这些都是基于同一套固件量变到质变的玩法等基础链路跑通了自然会找到下一个想做的功能。
