本教程基于开源项目 fanatec-ffb-bridge,将带您逐步搭建一套「ProtoPie 原型 → 真实 Fanatec 方向盘力反馈」的演示环境。整个过程无需赛车游戏,也无需 SimHub——搭建完成后,您即可在 ProtoPie Studio 中通过 Send Message 触发器,直接控制方向盘的转向力、震动强度与角度。
在本教程结束时，您将能够：
让方向盘根据 ProtoPie 场景实时产生转向力和震动提示
通过一个连接 Arduino 的物理按钮启动整套演示,增强真实感
排查常见的连接与权限问题
预估时间：30-45 分钟（不包括采购硬件的时间）。
1. 准备工作
在开始之前，请确保您拥有：
一台 Windows 电脑 —— 桥接程序通过 DirectInput 与方向盘通信，因此它仅支持 Windows
一个 Fanatec 基座，已通过 USB 连接并开机
Python 3.9 或更高版本，可从 python.org 获取
ProtoPie Connect，在本地运行并可通过端口
9981访问关闭 FanaLab 和 Fanatec Control Panel —— 这两者都会独占力反馈 (FFB) 锁，从而阻止桥接程序打开方向盘
（可选）一块 Arduino 开发板（Uno、Nano、Leonardo 等）和一个按钮，用于物理按钮触发
2. 第一步：下载并安装桥接程序
克隆或下载代码仓库：
git clone https://github.com/JubzMajulee/fanatec-ffb-bridge.gicd fanatec-ffb-bridge（推荐）创建虚拟环境，以避免影响系统 Python 环境:
python -m venv .venv.venv\Scripts\activate安装依赖项：
pip install -r requirements.txt
3. 第二步：启动方向盘并运行桥接程序
插上并打开您的 Fanatec 方向盘。
启动 ProtoPie Connect 并确认它正在监听
http://localhost:9981。在项目文件夹中运行：
python main.py
如果一切正常，终端将输出以下内容：
=== ProtoPie -> Fanatec FFB Bridge ===ProtoPie Connect: http://localhost:9981Wheel keyword: fanatec
—————————————————————————————
[FFB] 2 joystick(s) detected: [0] Fanatec ... [1] Fanatec ...[FFB] Haptic opened on [1] Fanatec ...[FFB] Constant force armed (signed -1..+1, ramp 1.00/sec)[FFB] Sine vibration armed (0..1, period=50ms)[FFB] Centering wheel (1500ms)...[FFB] Wheel centered[SocketIO] Connected to http://localhost:9981
此时方向盘会先自动回中,随后进入待机状态,等待接收消息。按 Ctrl + C 可随时停止程序。
出现 "No joysticks detected"? 说明 Windows 未识别到方向盘。请检查 USB 连接线与供电情况,并在 Windows 的「设置 USB 游戏控制器」中确认设备是否显示。
出现 "None of the candidates would open for haptic"? 这通常是因为 FanaLab 或 Fanatec Control Panel 占用了力反馈的独占权限,请关闭这两款程序后重试,并确保没有赛车游戏在后台运行。
4. 第三步：从 ProtoPie Studio 发送控制消息
桥接程序运行后，它会持续监听 ProtoPie Connect 广播的消息。在您的 ProtoPie Studio 原型中，添加一个Send Message 触发器，并按下表设置 Message ID 和 Value：
消息 ID (Message ID) | 值范围 (Value Range) | 效果 (Effect) |
|---|---|---|
|
| 将方向盘向左拉（负值）或向右拉（正值）。 |
| 例如 |
|
|
| 基座振动强度，立即生效。 |
| 角度，例如 | 将方向盘停在特定角度并保持在该位置。 |
|
|
|
常见组合示例
模拟系统向右修正：发送
set_ffb = 1.0让修正感更柔和：先发送
set_ffb_speed = 0.3，然后发送set_ffb = 0.0（缓慢飘回中心）模拟紧急切入转弯：先发送
set_ffb_speed = 8.0，然后发送set_ffb = 0.7（几近瞬时）车道偏离振动警报：发送
set_vibration = 0.6，然后发送set_vibration = 0.0停止自动驾驶接管，方向盘旋转至 30° 并锁定：先发送
set_angle = 30，然后发送set_angle_strength = 0.7
只要您的 ProtoPie 原型连接到 ProtoPie Connect，它发送的任何消息都会被桥接程序捕获，并转化为方向盘上的真实力反馈。
5. （可选）第四步：使用 Arduino 连接物理按钮
如果您想让演示更具沉浸感 —— 例如，使用真实的物理按钮启动“自动驾驶接管”场景 —— 您可以按如下方式添加 Arduino。
接线
只需两根线：
Arduino 引脚 | 连接到 |
|---|---|
| 瞬时点动按钮的一端 |
| 按钮的另一端 |
A0 使用芯片内置的上拉电阻,无需额外外接电阻。任何带 USB 串口的 Arduino 开发板均可使用(如 Uno、Nano、Leonardo、Pro Micro 等)。
烧录 Sketch 程式码
安装 Arduino IDE。
打开代码仓库中的
Arduino/pushButtonDemo.ino。Tools → Board——选择您使用的开发板型号。
Tools → Port——选择开发板对应的 COM 端口。
点击「上传」(右箭头图标)。
打开 Tools → Serial Monitor,将波特率设为 9600,按下按钮后应看到按下时输出
Arduino||1、松开时输出Arduino||0。测试完成后请关闭串口监视器,否则会占用该 COM 端口。
接入 ProtoPie Connect
在 ProtoPie Connect 中打开 Add Device → Serial(不同版本的命名可能略有差异)。
选择 Arduino 对应的 COM 端口,并将波特率设为 9600。
在 ProtoPie Studio 原型中添加一个 Receive Message 触发器,将 Message ID 设为
Arduino,并根据消息值(1表示按下,0表示松开)触发您的自动驾驶模拟场景启动。
接入完成后,整个链路如下:按下物理按钮 → Arduino 发送 Arduino||1 → ProtoPie Connect 转发消息 → ProtoPie 原型启动场景 → 场景发送 set_ffb、set_vibration 等消息 → 桥接程序将其转化为方向盘上的真实力反。
6. 调整默认参数
如果默认的手感不符合您演示的需求，可修改 main.py 顶部的配置：
PROTOPIE_URL = "http://localhost:9981" # ProtoPie Connect URLWHEEL_KEYWORD = "fanatec" # 用于匹配方向盘设备名称的子字符串
在 ffb_driver.py 中，FanatecFFB 提供了以下构造函数参数：
force_ramp_rate=1.0——set_ffb的默认过渡速度center_on_start=True—— 启动时是否自动将方向盘回中center_duration_ms=1500—— 回中动作的持续时长（毫秒）wheel_range_deg=900—— 方向盘满打满量的角度范围,该值需与 Fanatec 驱动中的设置一致,否则set_angle的映射将出现偏差
7. 故障排查快速查表
现象 | 可能原因 | 解决方法 |
|---|---|---|
| Windows 未检测到方向盘 | 检查 USB 连接线与供电情况,确认设备在「设置 USB 游戏控制器」中可见 |
| FanaLab / Fanatec Control Panel 占用了独占权限 | 关闭这两个程序，并确保后台没有运行赛车游戏 |
| ProtoPie Connect 未运行，或使用了不同的端口 | 打开 Connect 并确认端口；如果不同，编辑 |
方向盘对消息没有反应 | 消息未到达桥接程序，或者方向盘/驱动程序本身存在问题 | 检查终端是否输出类似 |
识别到错误设备 | 存在多个 Fanatec 设备，或使用了非标准的设备名称 | 将 |
总结
整套方案由三个轻量层组成:Arduino(可选的物理触发)→ ProtoPie(场景逻辑与消息编排)→ 桥接程序(将消息转化为方向盘力反馈)。每一层的实现成本都不高,但组合在一起,足以让评审人员或测试用户在几分钟内直观感受到「自动驾驶接管方向盘」的真实体验——这正是原型阶段最具说服力的部分。
👉 想亲眼看看它是怎么跑起来的？立即预约演示视频，看看真实硬件与原型如何实时联动。
