RYMCU 社区RYMCU 社区

NES蓝牙手柄功能文档

Hugh

Hugh

5 0
NES蓝牙手柄功能文档

功能概述

本文档描述了 NES 游戏模拟器的蓝牙手柄控制功能改造。通过 BluFi 协议，微信小程序可以作为虚拟手柄连接 ESP32 设备，控制 NES 游戏。

主要功能

  • 蓝牙虚拟手柄：通过 BluFi BLE 协议发送按键信号
  • 双玩家支持：支持两个玩家同时游戏
  • 网络自动切换：进入游戏时暂停 WiFi、启动 BluFi；退出时自动恢复
  • 物理按键备用：GPIO10 A 键作为物理输入备用
  • 按键超时保护：断线或超时自动释放按键

架构设计

模块结构

main/game/
├── nes_button_bridge.h/cc      # 按键桥梁：接收蓝牙事件，提供按键状态
├── nes_network_manager.h/cc    # 网络管理：WiFi/BluFi 切换
└── game_manager.h/cc           # 游戏管理：NES 模拟器控制
​
main/boards/common/
└── blufi.cpp                   # BluFi 协议处理：解析 nes_btn 命令
​
main/boards/rymcu-bigsmart/
└── rymcu_bigsmart_nes.cc       # NES 游戏入口：网络切换和按键获取

数据流程

┌─────────────────┐     BluFi BLE      ┌─────────────────┐
│   微信小程序     │ ──────────────→  │    ESP32-S3     │
│  (虚拟手柄UI)   │   nes_btn协议    │                 │
└─────────────────┘                   └────────┬────────┘
                                               │
                                               ▼
┌─────────────────────────────────────────────────────────┐
│                    BluFi 模块                           │
│  ESP_BLUFI_EVENT_RECV_CUSTOM_DATA                      │
│     ↓ 解析 nes_btn 协议                                 │
│     ↓ 调用 NesButtonBridge::HandleButtonEvent()        │
└─────────────────────────────────────────────────────────┘
                                               │
                                               ▼
┌─────────────────────────────────────────────────────────┐
│              NesButtonBridge (按键桥梁)                  │
│  - 维护玩家按键状态 ButtonState[2]                       │
│  - 线程安全的状态管理                                    │
│  - 提供 GetButtonState(player) 接口                     │
└─────────────────────────────────────────────────────────┘
                                               │
                                               ▼
┌─────────────────────────────────────────────────────────┐
│              GameManager (游戏管理)                      │
│  - 获取按键状态，传递给 NES 模拟器                        │
│  - 支持双玩家控制器                                      │
└─────────────────────────────────────────────────────────┘

状态流转

┌──────────────┐     长按Boot 3s      ┌──────────────┐
│              │ ─────────────────→  │              │
│  Idle 状态   │                     │  游戏菜单    │
│  WiFi 连接   │                     │  WiFi 暂停   │
│  BluFi 关闭  │                     │  BluFi 开启  │
│              │ ←─────────────────  │              │
└──────────────┘   Select+Start退出   └──────────────┘

命令示例

nes_btn:1:press:01      # 玩家1 按下 A 键
nes_btn:1:release:01    # 玩家1 松开 A 键
nes_btn:1:state:41      # 玩家1 状态同步 (A + 右键)
nes_btn:2:press:10      # 玩家2 按下 上键
nes_btn:1:press:03      # 玩家1 同时按下 A+B 键
nes_btn:1:release:FF    # 玩家1 松开所有键
nes_btn:2:state:00      # 玩家2 清零所有按键

代码改动说明

新增文件

1. nes_button_bridge.h

按键桥梁头文件，定义了：

  • NesButtonState - 按键状态结构体
  • NesButtonEvent - 按键事件结构体
  • NesButtonEventType - 事件类型枚举
  • NesButtonBridge - 按键桥梁类

2. nes_button_bridge.cc

按键桥梁实现：

  • Initialize() - 初始化互斥锁
  • HandleButtonEvent() - 处理蓝牙按键事件
  • GetButtonState() - 获取指定玩家按键状态
  • ClearAllButtons() - 清零所有按键（BLE断开时调用）
  • CheckButtonTimeout() - 检查按键超时

3. nes_network_manager.h

网络管理器头文件，定义了：

  • NesNetworkManager - 游戏网络管理类
  • NesNetworkModeCallback - 网络模式变化回调

4. nes_network_manager.cc

网络管理器实现：

  • EnterGameNetworkMode() - 进入游戏网络模式（暂停WiFi，启动BluFi）
  • ExitGameNetworkMode() - 退出游戏网络模式（关闭BluFi，恢复WiFi）
  • PauseWifi() / ResumeWifi() - WiFi 控制
  • StartBlufi() / StopBlufi() - BluFi 控制

修改文件

1. blufi.cpp

改动内容：

  • 添加头文件引用 nes_button_bridge.h 和 nes_network_manager.h
  • 在 ESP_BLUFI_EVENT_RECV_CUSTOM_DATA 中添加 nes_btn 协议解析
  • 在 ESP_BLUFI_EVENT_BLE_DISCONNECT 中清零按键状态

2. rymcu_bigsmart_nes.cc

改动内容：

  • 添加头文件引用 nes_button_bridge.h 和 nes_network_manager.h
  • TryEnterGameMode() 调用 NesNetworkManager::EnterGameNetworkMode()
  • NesGameTask() 从 NesButtonBridge 获取按键状态
  • 退出时调用 NesNetworkManager::ExitGameNetworkMode()

3. game_manager.h

改动内容：

  • 添加 HandleButtonInput(int player, const ButtonState& state) 重载方法
  • 修改 ProcessGameInput 签名支持玩家参数

4. game_manager.cc

改动内容：

  • 实现 HandleButtonInput(int player, ...) 多玩家版本
  • ProcessGameInput 支持设置不同玩家的控制器

5. CMakeLists.txt

改动内容：

  • 添加 game/nes_button_bridge.cc
  • 添加 game/nes_network_manager.cc

使用方法

进入游戏模式

  1. 设备处于 Idle 待机状态
  2. 长按 Boot 按钮 3 秒
  3. 设备自动：
  • 暂停 WiFi 连接
  • 启动 BluFi BLE 广播
  • 显示游戏 ROM 选择菜单

小程序连接

  1. 微信小程序扫描蓝牙设备
  2. 连接设备（设备名包含 "Xiaozhi" 或 "BLUFI"）
  3. 连接成功后即可发送按键命令

退出游戏模式

  1. 在游戏菜单中按 Select + Start
  2. 设备自动：
  • 关闭 BluFi
  • 恢复 WiFi 连接
  • 返回主界面

容错机制

按键超时

  • 超时时间：1 秒
  • 触发条件：超过 1 秒无按键更新
  • 处理方式：自动清零所有按键状态
  • 配置方法：NesButtonBridge::SetButtonTimeout(ms)

蓝牙断开

  • 触发事件：ESP_BLUFI_EVENT_BLE_DISCONNECT
  • 处理方式：自动清零所有玩家按键状态
  • 用户体验：游戏暂停，显示"手柄已断开"

网络恢复

  • 退出游戏时自动恢复 WiFi
  • 如果恢复失败，设备进入 Idle 状态
  • WiFi 连接信息在进入游戏前保存

日志关键词

# 正常流程
"NesNetworkMgr: Entering game network mode"
"NesNetworkMgr: WiFi paused"
"NesNetworkMgr: BluFi started"
"BLUFI_CLASS: NES button: player=1, event=press, btn=0x01"
​
# 异常情况
"NesNetworkMgr: Failed to start BluFi"
"NesBtnBridge: Player 1 button timeout, clearing"

版本信息

  • 改造日期：2026-04-13
  • ESP-IDF 版本：5.5.1
  • 目标芯片：ESP32-S3
  • 依赖组件：BluFi, WifiManager, GameManager

相关文章

优先推荐同专题、同标签和同作者内容，补足热门文章。

ESP32工程中文和音频映射方法
同作者内容123 浏览

ESP32工程中文和音频映射方法

这份代码是 ​ESP-IDF 工程中自动生成的多语言资源头文件​（中文 zh-CN 为主，英文 en-US 兜底），核心作用是把「静态字符串（如 “已连接”）」和「二进制音效文件（OGG）」封装成 C++ 命名空间常量，让业务代码可以直接引用。下面从整体结构、核心特性、关键语法、使用场景 四个维度逐行解析：一、整体功能总结这份代码的核心是 ​**“资源硬编码”**​（区别于你之前问的 JSON 动

Hugh
0 赞1 评
ESP32的PSRAM 和 SPIRAM命名和使用原则
同作者内容118 浏览

ESP32的PSRAM 和 SPIRAM命名和使用原则

PSRAM 和 SPIRAM 本质上指的是​同一个硬件​（外置 / 片内串行 RAM），只是命名视角不同，实际使用中不会混淆 —— 核心是记住 “ESP-IDF 中统一用 SPIRAM 作为配置 / API 标识，行业内通用 PSRAM 称呼”，下面拆解清楚：一、PSRAM 和 SPIRAM 的命名溯源（为什么看起来像两个名字）两者是 “全称缩写” 和 “功能简称” 的关系，指向完全相同的硬件：名

Hugh
0 赞0 评
ESP32中CONFIG_SPIRAM开关对工程影响分析
同作者内容95 浏览

ESP32中CONFIG_SPIRAM开关对工程影响分析

​如果未启用 CONFIG_SPIRAM，ESP32-S3-WROOM-1-N8R2 模组中集成的 2MB 片内 PSRAM 在工程运行期间会完全闲置，不会被系统或应用代码使用​。下面从「底层机制」「代码影响」「例外场景」三个维度讲清楚：一、核心机制：CONFIG_SPIRAM 是 PSRAM 的 “总开关”ESP-IDF 中，CONFIG_SPIRAM 控制的是​PSRAM 的初始化和系统整合​

Hugh
0 赞0 评
ESP32模组存储配置解析
同作者内容120 浏览

ESP32模组存储配置解析

ESP32-S3-WROOM-1-N8R2 模组的存储配置和硬件形态可以明确拆解为：一、核心结论存储类型容量硬件形态（是否独立芯片）备注Flash8MB模组内独立的 SPI Flash 芯片标注的 “N8” 对应 8MB FlashSPIRAM（PSRAM）2MB集成在​ESP32-S3 芯片内部​（片上）标注的 “R2” 对应 2MB PSRAM二、逐点拆解1. 8MB Flash：模组内独立芯

Hugh
0 赞0 评
ESP32 WIFI事件处理方式剖析
同作者内容37 浏览

ESP32 WIFI事件处理方式剖析

这段代码的核心是​**两层事件的 “桥接关联”**​：把 WifiManager 层的 WifiEvent（WiFi 专属事件）转换为更上层的 NetworkEvent（通用网络事件），最终通过 OnNetworkEvent 统一处理。下面从「关联逻辑」「技术实现」「调用链路」三个维度讲清楚事件是如何关联处理的：一、先理清核心概念：两层事件的分工事件类型定义方作用WifiEventWifiMana

Hugh
0 赞0 评
类成员变量和结构成员变量访问权限问题
同作者内容21 浏览

类成员变量和结构成员变量访问权限问题

C++ 中类（class）和结构体（struct）本质上几乎等价，能否 “不创建对象就用成员”，只取决于成员是否被声明为 static（静态），和它是类还是结构体无关。下面从「本质区别」「语法细节」「C 语言溯源」三个维度彻底讲清楚：一、核心结论：类 / 结构体的 “静态成员” 才是关键C++ 中，无论是 class 还是 struct，都支持两种成员：成员类型是否需要创建对象才能使用归属（类 /

Hugh
0 赞0 评

评论 0

登录 后参与评论

评论

成为第一个评论的人