ESP32-S3蓝牙广播控制：在无按键CardPuter上运行Doom游戏

1. 项目缘起：当复古掌机遇上现代无线技术

最近在折腾一个特别有意思的玩意儿，我把它叫做“CardPuter ADV Doom”。简单来说，就是在一台基于ESP32-S3的、长得像游戏卡带的便携式设备上，运行经典的《毁灭战士》（Doom）游戏，并且通过一种非常规的无线方式——ADV（蓝牙广播）——来实现控制。这听起来可能有点绕，但它的魅力恰恰在于这种“混搭”和“破解”的乐趣。如果你对嵌入式开发、复古游戏，或者如何把不同时代的技术“缝合”在一起感兴趣，那这个项目绝对能让你玩上好几个周末。

这个项目的核心硬件是一个叫“CardPuter”的小设备。它本质上是一个集成了ESP32-S3芯片、IPS屏幕、锂电池和TF卡槽的微型开发板，但外形被设计成了一张游戏卡带的样子，非常精致。ESP32-S3本身性能不错，双核240MHz，带Wi-Fi和蓝牙，运行Doom这种级别的游戏理论上绰绰有余。但问题来了，CardPuter本身没有物理按键！它的设计初衷可能是作为一个无线文件传输器或者名片显示器，通过手机APP来控制。那我们要怎么玩需要复杂按键操作的游戏呢？这就是“ADV Doom”这个点子诞生的地方：我们不用传统的蓝牙连接（BLE GATT），而是利用蓝牙广播（Advertising）数据包来传输按键信息。

为什么要用广播模式？这其实是个很“极客”的思路。标准的蓝牙连接（比如连接手柄）需要配对、建立连接、维护链路，虽然稳定，但延迟和功耗对于某些极简应用来说可能不是最优的。而蓝牙广播是单向的，发射端（比如你的手机）定期发送包含自定义数据的小包，接收端（CardPuter）像收音机一样监听这些广播包，解析出里面的数据。这样做的好处是，理论上可以实现极低的延迟（因为没有连接建立的握手过程），并且一个发射端可以同时被无数个接收端监听，非常适合演示或者一些简单的遥控场景。当然，缺点也很明显，数据不可靠、长度受限（一个广播包最多31字节有效载荷）。但用来传输几个按键状态，简直是量身定做。

所以，“CardPuter ADV Doom”项目的全貌就是：在CardPuter上移植一个Doom引擎（比如经典的“PrBoom”移植版），然后编写一个监听蓝牙广播的模块。同时，你需要在手机上（或者另一个ESP32设备上）写一个简单的发射端APP，这个APP不连接CardPuter，只是不断地把当前屏幕上的虚拟按键状态，打包成一个特定的广播包发送出去。CardPuer这边抓到这个包，解析出上下左右、开火、使用等按键指令，然后注入到Doom的游戏逻辑中。这样一来，你就用无线“遥控”的方式，在一台没有按键的卡带设备上，玩起了90年代的经典FPS游戏。这种跨越时空的技术组合，带来的成就感远超单纯地运行一个游戏。

2. 硬件准备与开发环境搭建

工欲善其事，必先利其器。在开始写代码之前，我们需要把硬件和软件环境准备好。这个环节看似基础，但很多坑都埋在这里，一步错可能导致后面步步维艰。

2.1 核心硬件：CardPuer深度解析

首先，你得有一个CardPuer。目前市面上有几个版本，推荐选择搭载ESP32-S3芯片的型号，因为它的性能足够，而且社区支持较好。拿到设备后，别急着上电，先仔细观察一下：

• 屏幕：通常是1.54英寸或2.0英寸的IPS屏，分辨率在240x240或320x240。驱动芯片一般是ST7789或ILI9341。这决定了我们后续图形驱动的选择。
• 电源：内置锂电池，通过USB-C口充电。这里有个重要提示：有些CardPuer的USB口只负责充电，不包含数据通信（D+/D-引脚未连接）。这意味着你无法通过USB线直接给它烧录程序！这是一个巨大的坑。解决方案是使用其引出的串口引脚（通常是板子上预留的焊盘，如TX、RX、GND），配合一个USB转TTL串口模块进行烧录。在购买或动手前，务必确认你手上的版本是否支持USB直接下载（CDC）。
• 存储：TF卡槽用于存放游戏资源（如Doom的WAD文件），SPI Flash用于存放程序和系统。
• 按键：如之前所说，它本身没有游戏按键。但板上可能会有一个复位按钮和一个Boot按钮（用于进入下载模式）。

我的建议是，先去设备的GitHub仓库或相关论坛找到准确的原理图。搞清楚屏幕型号、引脚分配（SPI屏幕的CLK、MOSI、DC、RST、CS引脚分别接到了ESP32-S3的哪个GPIO上）、以及串口下载引脚的位置。这将为后续的驱动编写和下载操作奠定基础。

2.2 软件开发环境：ESP-IDF与VS Code

我们将使用乐鑫官方的ESP-IDF框架进行开发。虽然Arduino框架更简单，但对于这种需要深度定制蓝牙协议和图形性能的项目，ESP-IDF提供了更底层、更灵活的控制。

1. 安装ESP-IDF：最推荐的方法是使用乐鑫的离线安装包或者通过VS Code的Espressif IDF插件进行安装。插件方式非常方便，它会帮你管理IDF版本和工具链。确保安装的IDF版本在v5.0以上，以获得对ESP32-S3的完善支持。
2. 创建项目：打开VS Code，使用IDF插件创建一个新项目。模板可以选择“hello_world”，我们会在其上大刀阔斧地修改。
3. 配置项目：项目创建后，首先运行idf.py set-target esp32s3来设置目标芯片。然后，使用idf.py menuconfig打开配置菜单。这里有几个关键配置：
   • Component config -> Bluetooth -> Bluetooth controller -> Bluetooth controller mode：选择BLE only。因为我们只用蓝牙低功耗，关闭经典蓝牙可以节省资源。
   • Component config -> Bluetooth -> Host -> Bluetooth advertising：确保启用。
   • Component config -> ESP32S3-specific：根据你的CardPuer硬件，正确配置PSRAM（如果板载了的话）和Flash大小。
   • 如果你的屏幕驱动需要特定的SPI引脚或时钟频率，可能需要在Hardware Settings或驱动组件配置中修改。

环境搭建好后，建议先编译并下载一个最简单的“hello_world”程序，通过串口查看输出，确保你的开发环境和下载方式（USB或串口）是通的。这是保证后续复杂调试能进行下去的第一步。

3. 图形引擎移植与显示驱动适配

让Doom在CardPuer上跑起来，第一步是解决显示问题。我们需要一个能在ESP32上运行的Doom引擎，并让它把画面输出到我们的SPI IPS屏幕上。

3.1 Doom引擎的选择：PrBoom vs. FastDoom

在嵌入式平台，常见的Doom移植有：

• PrBoom：一个高度可移植、功能丰富的Doom引擎。它的代码结构清晰，社区移植案例多，是安全稳妥的选择。但相对而言，它对计算资源的要求也高一些。
• FastDoom：如其名，追求极致的速度，进行了一些算法优化和简化。在资源紧张的设备上表现可能更好。

对于ESP32-S3来说，双核240MHz加上可能有的PSRAM，运行PrBoom的移植版已经足够。我选择了基于PrBoom的某个ESP32移植版本作为起点。你可以在GitHub上搜索“esp32 doom”找到不少开源项目。关键不是照搬，而是理解其图形输出机制。通常，这些移植版会实现一个“帧缓冲区”（framebuffer），引擎将每一帧游戏画面渲染到这个缓冲区中，然后你需要自己编写一个“显示驱动”，负责将这个缓冲区里的数据搬运到实际的屏幕上。

3.2 SPI屏幕驱动编写与优化

这是最考验耐心和细节的部分。CardPuer的屏幕通常通过SPI接口驱动。你需要：

1. 初始化SPI总线：在ESP-IDF中配置SPI主机（HSPI或VSPI），设置正确的时钟频率（比如40MHz或80MHz）。时钟频率直接影响刷屏速度，是性能瓶颈之一。
2. 编写屏幕初始化序列：根据屏幕数据手册（datasheet），通过发送一系列命令（Command）和数据（Data）来初始化屏幕，包括设置分辨率、颜色格式（RGB565）、扫描方向、打开显示等。这部分代码通常又长又枯燥，但必须精确。一个命令错了，可能屏幕就白屏或者花屏。
3. 实现画点/画块函数：Doom引擎最终会调用一个类似于draw_pixel(x, y, color)或draw_frame_buffer(fb_addr)的函数。你需要实现它。
   • 全屏刷新：最简单粗暴的方式是每一帧都把整个帧缓冲区通过SPI发送到屏幕。但对于240x240x2（RGB565）的屏幕，一帧数据就是115200字节，即使SPI时钟很快，传输也需要几十毫秒，很难达到流畅的30fps。
   • 差异化更新（Dirty Rectangle）：这是关键优化。Doom引擎在渲染时，可以只重画屏幕上发生变化的部分（矩形区域）。你需要修改引擎或适配层，让它能提供这些“脏矩形”的坐标，然后你的驱动只发送这些矩形区域的数据。这能极大减少SPI传输量。在PrBoom的移植中，通常需要关注I_FinishUpdate这类函数，并修改其内部的实现。

我的实操心得：一开始我采用了全屏刷新，帧率只有10fps左右，动作拖慢。后来实现了脏矩形更新，但发现SPI传输本身还是慢。进一步优化包括：

• 使用DMA（直接内存访问）：ESP-IDF的SPI主机驱动支持DMA。配置DMA后，CPU在启动SPI传输后就可以去处理其他任务（比如下一帧的游戏逻辑计算），传输由DMA控制器在后台完成，极大提高了效率。
• 双缓冲（Double Buffering）：在内存中开辟两个帧缓冲区。Doom引擎渲染到“后台缓冲区”，渲染完成后，通过DMA将后台缓冲区数据发送到屏幕，同时引擎可以开始渲染下一帧到另一个“前台缓冲区”。这避免了渲染等待传输完成的时间，能有效提升帧率。
• 调整SPI时钟和模式：在屏幕能接受的范围内，尽可能提高SPI时钟。同时，确认屏幕的数据传输模式（是3线SPI还是4线SPI带D/C引脚）。CardPuer通常是4线模式（MOSI, CLK, DC, CS），DC引脚用来区分发送的是命令还是数据，这个时序要搞对。

经过这些优化，我的CardPuer最终能在大部分场景下以稳定的30fps以上运行Doom，画面流畅。这个过程需要反复调试、看逻辑分析仪（如果有的话）的波形、以及不断地打日志分析性能瓶颈。

4. 蓝牙广播（ADV）控制协议设计与实现

图形部分跑通后，接下来就是项目的灵魂——如何用蓝牙广播来控制游戏。这完全是一个自定义的通信协议，设计得好坏直接影响到操控体验。

4.1 协议设计：简单、高效、容错

蓝牙广播包有严格限制：一个广播包最大31字节有效载荷。我们需要在这31字节内编码所有必要的控制信息。设计协议时我遵循了几个原则：

1. 状态同步，而非事件触发：不要发送“A键按下”、“A键释放”这样的事件。而是每隔一段时间（比如每秒30次）发送一个包含当前所有按键状态的数据包。例如，用一个字节（8位）的每一位来代表一个按键是否被按下（1为按下，0为释放）。这样即使丢失一两个包，也不会导致按键“卡住”，因为下一个包会刷新状态。这是对抗广播不可靠性的关键。
2. 包含序列号和时间戳：在数据包中加入一个自增的序列号，这样接收端可以判断是否丢包。加入一个粗略的时间戳（比如毫秒级），可以帮助接收端估算延迟，或者用于简单的滤波。
3. 预留校验和：虽然广播包本身有CRC校验，但我们在应用层再加一个简单的校验和（比如所有字节求和取低8位），可以多一层保障，防止数据在解析前被错误处理。
4. 考虑扩展性：预留几个字节作为未来扩展，比如可以加入摇杆的模拟量（需要两个字节来表示X/Y轴）、触摸屏坐标等。

一个简单的协议帧结构可以设计如下：

[帧头：1字节，固定值如0xAA] [序列号：1字节] [按键状态位图：2字节] [预留扩展：4字节] [校验和：1字节]

总共9个字节，远小于31字节限制，留出了充足空间。按键状态位图可以这样定义：Bit0: 上，Bit1: 下，Bit2: 左，Bit3: 右，Bit4: 开火，Bit5: 使用，Bit6: 跑步，Bit7: 武器切换…… 第二个字节可以定义更多功能键。

4.2 发射端实现（以Android为例）

发射端是一个运行在手机上的APP。它的核心功能是：

1. 在屏幕上绘制一个虚拟手柄或几个按钮。
2. 监听触摸事件，更新内部的按键状态位图。
3. 以固定的时间间隔（如33ms，对应30Hz）将当前状态位图打包成上述协议格式。
4. 使用手机蓝牙API，将这个数据包设置为扫描响应数据（Scan Response Data）或直接放在广播数据中进行广播。

这里的关键点是，手机APP不需要与CardPuer建立蓝牙连接。它只是作为一个广播者（Advertiser）存在。在Android开发中，你需要用到BluetoothLeAdvertiser类。你需要创建一个AdvertiseData对象，将你的自定义数据通过setManufacturerData或addServiceData方法添加进去。我推荐使用setManufacturerData，因为它允许你自定义一个制造商ID（可以随便选一个未注册的，比如0xFEED）和对应的数据，比较灵活。

注意事项：Android系统对后台广播有严格限制，为了保持APP在后台也能持续广播，你可能需要创建一个前台服务（Foreground Service），并显示一个持续的通知。同时，广播频率不宜过高，否则耗电会非常快。

4.3 接收端实现（CardPuer端）

在CardPuer的ESP-IDF项目中，我们需要实现蓝牙扫描（Scan）功能，并过滤出我们需要的广播包。

1. 初始化蓝牙并配置扫描参数：设置扫描模式为主动扫描（ESP_BT_SCAN_MODE_ACTIVE），扫描间隔和窗口可以设短一些以减少延迟。
2. 注册扫描回调函数：当收到广播包时，这个函数会被调用。在回调函数里，你需要解析广播包的数据结构。
3. 过滤与解析：首先检查广播包中是否包含制造商特定数据（Manufacturer Specific Data），并且制造商ID是否是我们约定的（如0xFEED）。如果是，则提取后面的数据载荷。然后按照我们设计的协议进行解析：检查帧头、校验和，提取序列号和按键状态位图。
4. 状态注入：将解析出的按键状态，映射到Doom引擎的输入系统。这通常需要修改Doom的输入处理函数（例如I_GetEvent或类似的函数）。你需要维护一个当前按键状态表，当收到新的广播包时更新这个表。Doom引擎在每一帧查询输入时，就从你这个表里读取状态。

抗干扰与平滑处理：广播环境复杂，丢包和干扰是常态。我增加了两个处理逻辑：

• 超时重置：如果超过一定时间（比如200ms）没有收到任何有效的广播包，就认为连接已断开，将所有按键状态重置为“释放”。防止因为信号突然中断导致角色一直朝一个方向走。
• 状态保持与滤波：不是一收到新包就立刻完全覆盖旧状态。对于方向键，可以做一个简单的软件去抖动或短时保持，避免因单个丢包导致动作卡顿。例如，如果上一帧是“前进”，这一帧因为丢包没收到信号，可以暂时保持“前进”状态一小段时间（比如50ms），如果之后还是没信号，再判定为停止。

5. 系统整合、性能调优与实测体验

当图形、蓝牙、游戏引擎三个模块都准备好后，就需要把它们整合成一个稳定、流畅的系统。这是从“能跑”到“好用”的关键一步。

5.1 任务划分与优先级管理

在一个没有操作系统的环境中（ESP-IDF基于FreeRTOS），我们需要合理规划任务（Task）。

• Doom游戏主循环任务：这是核心，优先级应设为较高（如configMAX_PRIORITIES-1）。它负责运行游戏逻辑、渲染。这个任务大部分时间在忙等垂直同步或进行大量计算。
• 蓝牙扫描任务：优先级可以设为中等。它持续进行蓝牙扫描，收到包后解析，并更新一个全局的按键状态结构体。这个任务应该被设计为事件驱动型，大部分时间在阻塞等待扫描结果，不占用过多CPU。
• 显示刷新任务（如果使用DMA双缓冲）：优先级可以设为高。当后台缓冲区渲染完成，该任务负责启动DMA传输。它可以由游戏主循环任务通过队列（Queue）或信号量（Semaphore）来触发。

任务间的通信必须通过线程安全的机制，如队列、信号量、互斥锁（Mutex）来保护共享的按键状态数据和帧缓冲区数据。避免在中断服务程序（ISR）或蓝牙回调函数中直接进行复杂操作，应该尽快将数据推送到队列，让高优先级的任务去处理。

5.2 内存与性能优化

ESP32-S3的内存（尤其是如果没用PSRAM）是宝贵资源。

• 帧缓冲区：两个240x240的RGB565缓冲区就需要约115KB * 2 = 230KB。如果内部RAM不够，必须使用PSRAM。在menuconfig中务必正确配置PSRAM，并在代码中使用heap_caps_malloc(size, MALLOC_CAP_SPIRAM)来在PSRAM中分配帧缓冲区。
• Doom的WAD文件：Doom的游戏数据（WAD文件）很大（几MB）。必须将它放在TF卡上，并通过FatFS文件系统进行读取。需要优化文件读取，比如在关卡加载时预读资源，避免在游戏运行时频繁进行小文件I/O操作，否则会造成卡顿。
• CPU占用率监控：使用FreeRTOS的vTaskList函数可以查看各个任务的运行时间和栈使用情况。确保没有任务出现“饿死”或栈溢出。蓝牙任务和显示任务的栈空间可以适当给大一些。

5.3 实测体验与操控优化

将所有代码编译烧录后，就是激动人心的实测环节。打开手机APP，启动广播，CardPuer上电运行Doom。

• 延迟感知：这是最重要的体验指标。理想情况下，从按下手机屏幕到CardPuer上角色移动，延迟应该控制在50ms以内。你可以用高速摄像机拍摄，或者通过让角色快速左右移动观察“影子”来主观感受。如果延迟明显，需要检查几个点：手机APP的广播间隔是否足够短（建议20-33ms）、CardPuer的扫描间隔是否太宽、任务优先级是否导致输入处理被阻塞。
• 抗干扰能力测试：在复杂的无线环境（如办公室、有多台蓝牙设备的房间）中测试。观察是否会出现按键失灵、角色“抽筋”式移动。这考验的是协议中状态同步和超时重置机制的有效性。必要时可以增加信号强度（RSSI）过滤，只处理信号较强的广播包。
• 续航测试：CardPuer运行Doom+蓝牙扫描，功耗不小。实测我的设备满电可以连续运行约2-3小时。主要耗电大户是屏幕和CPU。可以考虑在游戏中增加一个“自动熄屏”或“低功耗模式”的选项，当一段时间无操作时，降低屏幕亮度或暂停游戏逻辑。

经过多轮调试和优化，最终我实现了在CardPuer上流畅运行Doom，并通过手机蓝牙广播进行稳定、低延迟的控制。这个项目不仅仅是为了玩一个游戏，更是一次对嵌入式系统开发、无线通信协议、实时图形渲染和性能调优的综合性实践。它证明了，即使是用看似不匹配的硬件和非常规的技术路径，通过精心的设计和优化，也能实现有趣且可用的产品原型。