基于FireBeetle 2 ESP32-C5的游戏搭子

一、项目介绍


经典 NES（任天堂娱乐系统）游戏如《超级玛丽》深受玩家喜爱。本项目拟使用FireBeetle 2 ESP32-C5 开发板制作一个蓝牙游戏手柄，满足《超级玛丽》等经典游戏的操控需求。


二、设计思路


结合《超级玛丽》游戏操控逻辑，明确蓝牙手柄需实现两大核心功能：一是方向控制，通过摇杆实现角色左右移动、上下跳跃（或场景切换）；二是按键触发，通过独立按键补充游戏关键操作（如发射子弹、确认选择）。


以 FireBeetle 2 ESP32-C5 为核心，利用其集成的蓝牙模块实现无线数据传输，同时依托其低功耗特性与 GPIO 引脚资源，满足扩展板供电与信号采集需求；搭配 JoyStick Shield 扩展板，直接获取摇杆模拟信号（X 轴、Y 轴）与按键数字信号。


软件层面分为三部分：一是硬件驱动，通过 Arduino IDE 调用 ESP32 板卡库与 BleGamepad 库，实现开发板对摇杆、按键的信号读取，以及蓝牙手柄的协议适配；二是数据处理，将摇杆采集的 0~4095 模拟值（ESP32 ADC 分辨率）通过map函数转换为模拟器识别的 - 32737~32737 范围值，同时对按键电平信号进行消抖处理（避免接触不良导致的误触发）；三是功能校准，通过软件逻辑配合电脑端校准步骤，记录摇杆极限位置与中心位置，确保方向控制精准度。


三、硬件介绍


1、FireBeetle 2 ESP32-C5 开发板


FireBeetle 2 ESP32-C5 是一款搭载乐鑫 ESP32-C5 模组的低功耗 IoT 开发板，面向智能家居和广泛物联网场景，集高性能计算、多协议支持与智能电源管理于一体，为各种部署需求提供高可靠性、高灵活性与长续航的解决方案。

2、JoyStick Shield扩展板

JoyStick Shield 是专为微控制器设计的摇杆扩展板，无需额外搭建按键与摇杆电路，具备以下优势：一是集成度高，内置 1 个双轴模拟摇杆（输出 X 轴、Y 轴连续模拟信号）与 4 个独立按键（支持数字信号输出）。

四、接线图

五、核心代码及说明


1、代码结构与核心功能

// 1. 引入依赖库：BleGamepad库用于蓝牙手柄功能，Arduino.h为基础库
#include <Arduino.h>
#include <BleGamepad.h>

// 2. 引脚定义：与接线图中GPIO引脚一一对应
#define JOYSTICK_X 2    // X轴（水平方向）引脚
#define JOYSTICK_Y 3    // Y轴（垂直方向）引脚
#define BUTTON_UP 4     // 上键引脚
#define BUTTON_RIGHT 5  // 右键引脚
#define BUTTON_DOWN 6   // 下键引脚
#define BUTTON_LEFT 7   // 左键引脚

// 3. 初始化蓝牙手柄对象：设置手柄名称为“Bluetooth JoyStick”，匹配电脑识别名称
BleGamepad bleGamepad("Bluetooth JoyStick", "ESP32-C5 Controller", 100);
// 定义手柄按键状态变量（初始为未按下）
BleGamepadButton buttons;

void setup() {
  // 初始化串口：波特率9600，用于调试时查看信号值
  Serial.begin(9600);
  // 初始化蓝牙手柄：启动BLE通信，等待电脑连接
  bleGamepad.begin();
  // 设置引脚模式：摇杆为输入（模拟信号），按键为输入并启用内部上拉电阻（默认高电平，按下为低电平）
  pinMode(JOYSTICK_X, INPUT);
  pinMode(JOYSTICK_Y, INPUT);
  pinMode(BUTTON_UP, INPUT_PULLUP);
  pinMode(BUTTON_RIGHT, INPUT_PULLUP);
  pinMode(BUTTON_DOWN, INPUT_PULLUP);
  pinMode(BUTTON_LEFT, INPUT_PULLUP);
  
  Serial.println("Bluetooth JoyStick Ready. Waiting for connection...");
}

void loop() {
  // 检查蓝牙是否连接：仅在连接状态下更新手柄数据
  if (bleGamepad.isConnected()) {
    // 4. 读取摇杆模拟值：ESP32 ADC读取范围为0~4095
    int xValue = analogRead(JOYSTICK_X);
    int yValue = analogRead(JOYSTICK_Y);
    
    // 转换摇杆值：将0~4095映射为模拟器识别的-32737~32737
    int mappedX = map(xValue, 0, 4095, -32737, 32737);
    int mappedY = map(yValue, 0, 4095, -32737, 32737);
    
    // 5. 读取按键状态：按下时引脚为低电平（LOW），对应手柄按键“按下”状态
    bool upPressed = !digitalRead(BUTTON_UP);    // 取反：低电平→true（按下）
    bool rightPressed = !digitalRead(BUTTON_RIGHT);
    bool downPressed = !digitalRead(BUTTON_DOWN);
    bool leftPressed = !digitalRead(BUTTON_LEFT);
    
    // 6. 更新手柄数据：设置摇杆轴值与按键状态
    bleGamepad.setAxes(mappedX, mappedY, 0, 0, 0, 0, 0, 0);  // 仅使用X、Y轴，其余轴设为0
    buttons.set(1, upPressed);    // 按键1映射为“上键”
    buttons.set(2, rightPressed); // 按键2映射为“右键”
    buttons.set(3, downPressed);  // 按键3映射为“下键”
    buttons.set(4, leftPressed);  // 按键4映射为“左键”
    bleGamepad.setButtons(buttons);
    
    // 调试输出：串口打印当前摇杆值与按键状态（便于排查问题）
    Serial.print("X: "); Serial.print(mappedX);
    Serial.print(" | Y: "); Serial.print(mappedY);
    Serial.print(" | Up: "); Serial.print(upPressed ? "Pressed" : "Released");
    Serial.print(" | Right: "); Serial.print(rightPressed ? "Pressed" : "Released");
    Serial.print(" | Down: "); Serial.print(downPressed ? "Pressed" : "Released");
    Serial.print(" | Left: "); Serial.println(leftPressed ? "Pressed" : "Released");
  }
  
  // 延时10ms：降低CPU占用率，避免数据发送过于频繁
  delay(10);
}
复制代码

2、关键代码说明

（1）库依赖：BleGamepad.h是实现蓝牙手柄功能的核心库，支持自定义手柄名称、轴数与按键数，兼容 Windows 系统的蓝牙游戏控制器协议；

（2）摇杆值映射：map函数将 ESP32 ADC 的 0~4095 模拟值转换为 - 32737~32737，与电脑端游戏控制器的标准轴值范围一致，确保方向控制精准；

（3）按键电平处理：按键引脚启用INPUT_PULLUP模式，默认输出高电平，按下时为低电平，通过!digitalRead()取反，使 “按下” 状态对应true，符合BleGamepad库的按键状态定义；

（4）蓝牙连接判断：bleGamepad.isConnected()确保仅在手柄与电脑连接时更新数据，避免无效数据发送，降低功耗。

六、项目步骤

1、Arduino IDE 安装

从 Arduino 官网（https://www.arduino.cc/en/software）下载对应操作系统的 Arduino IDE 安装包，双击运行安装程序，按照向导完成安装（默认勾选 “关联.ino 文件”“创建桌面快捷方式”，便于后续操作）。

2、安装ESP32板卡库

“文件→首选项”，在 “附加开发板管理器网址” 输入 “https://jihulab.com/esp-mirror/e ... esp32_index_cn.json”，点击 “确定”；

打开 “工具→开发板管理器”，搜索 “ESP32”，安装 “esp32 by Espressif Systems”（版本3.3-alpha1-cn），安装完成后重启 Arduino IDE）。

3、BleGamepad 库安装

打开 Arduino IDE，点击 “项目→加载库→管理库”，在 “库管理器” 搜索框输入 “ble Gamepad”，找到 “ESP32-BLE-Gamepad by lemmingDev”，点击 “安装”，等待安装完成。

4、编译及上传程序

“工具→开发板→ESP32→ESP32C5 Dev Module”

用 USB 数据线连接 FireBeetle 2 ESP32-C5 与电脑，“工具→端口→COM5”，以实际显示为准。

5、蓝牙游戏手柄安装

（1）添加蓝牙游戏手柄：电脑进入 “设置→蓝牙和其他设备→添加设备→蓝牙”，此时电脑会搜索附近蓝牙设备，找到 “Bluetooth JoyStick”，点击连接，等待连接成功；

（2）游戏控制器设置校准：进入电脑 “控制面板→设备和打印机”，找到 “Bluetooth JoyStick”（图标为游戏手柄形状）；右键点击该设备，选择 “游戏控制器设置→属性”；

进入 “设置” 选项卡，点击 “校准→下一步”；按照向导提示，将 JoyStick Shield 的摇杆推至最左、最右、最上、最下极限位置（每个位置停留 1~2 秒，确保信号被识别），再归位到中心，向导自动记录信号范围；点击 “下一步→完成”，校准完成；

（3）功能测试：按下 Shield 上的 4 个按键，观察 “按钮 1~4” 是否同步点亮（按下时点亮，松开时熄灭），无延迟、无误触发则校准通过。

6、模拟器的使用

（1）启动游戏模拟器：双击 “NNNesterJ.exe” 启动模拟器，界面显示 NES 模拟器主窗口；

（2）加载游戏 ROM：点击 “文件→打开 ROM”，在文件浏览器中选中《超级玛丽》ROM 文件（格式通常为.nes），点击 “打开”；模拟器自动加载 ROM，几秒后显示《超级玛丽》启动画面（如任天堂 LOGO、游戏标题），加载成功；

（3）NNNesterJ 控制器设置：1. 打开 NNNesterJ，点击 “选项→控制器设置”，弹出 “控制器配置” 窗口；2. 在 “控制器 1” 选项卡中，选择需配置的 NES 按键（如 “上、下、左、右”）；点击 “上” 对应的输入框，此时输入框处于 “等待输入” 状态（通常显示 “Press a key”），按下 JoyStick Shield 的 “按键 1”（BUTTON_UP），输入框显示 “按钮 1”；重复操作，将 NES “下”“左”“右” 分别映射到 Shield 的 “按键 3”“按键 4”“按键 2”；若需用摇杆控制角色移动，模拟器会自动识别摇杆 X 轴（左右）、Y 轴（上下）信号，无需额外映射，移动摇杆即可控制角色方向；所有按键映射完成后，点击 “确定” 保存配置；

回到游戏画面，测试操控：按下 “上” 键角色跳跃、移动摇杆角色前进 / 后退，无延迟、无错位则设置完成。

七、项目总结

本项目通过 FireBeetle 2 ESP32-C5 与 JoyStick Shield 的组合，简化了蓝牙游戏手柄的硬件搭建流程，避免了独立元件接线复杂、调试困难的问题，仅需8 根杜邦线即可完成硬件连接。

项目仍有优化空间：一是功能扩展，利用 JoyStick Shield 的额外按键（部分型号含 6~8 个按键）扩展 NES 游戏的 “开始”“选择”“A”“B” 键，满足更多游戏操控需求；二是供电优化，增加 3.7V 锂电池模块与充电电路，替换 USB 有线供电，实现手柄便携使用。

附件：
蓝牙游戏手柄.zip