查看: 58|回复: 0

[ESP8266/ESP32] DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现

1. 项目概述

本项目是一套基于 DFRobot FireBeetle 2 ESP32-P4 服务端和 M5Paper 与 ESP32-C3 客户端的智能电子工牌系统。

DFRobot FireBeetle 2 ESP32-P4 是整个系统的核心枢纽，承担 BLE 扫描发现、打卡判定、Web 服务管理、数据持久化、配置下发等全部服务端职责。

本文档重点介绍 DFRobot FireBeetle 2 ESP32-P4 服务端的实现细节，包括 BLE 扫描与打卡逻辑、SQLite 数据库设计、Web API 接口，以及作为 BLE 中心设备与客户端的交互方式。M5Paper 和 ESP32-C3 客户端仅作为交互对象简要说明。

项目的源码可以直接访问 GitHub 仓库 e-badge。

2. 硬件平台

服务端采用 DFRobot FireBeetle 2 ESP32-P4 开发板。
该开发板的主控是 ESP32-P4，采用双核 RISC-V 架构，主频 400MHz。

FireBeetle 2 开发板通过板载的 ESP32-C6 协处理器提供无线连接能力，支持 WiFi 6 和 BLE 5.0。
Flash 容量为 16MB，USB 接口支持 USB-Serial 和 JTAG 调试。

ESP32-P4 本身无内置 WiFi 和 BLE 功能，FireBeetle 2 开发板通过集成的 ESP32-C6 协处理器来提供无线连接能力。
在 Arduino 开发环境中，开发者直接使用标准的 WiFi.h、BLEDevice.h 等库即可，底层由 ESP-IDF 框架自动通过 SPI 或内部总线与 C6 进行通信，无需关心协处理器的具体实现细节。

由于 ESP32-P4 固件体积较大，约 1.5MB，包含了 SQLite 数据库、Web 服务器、BLE 协议栈和 WiFi 驱动，因此必须至少使用 8MB 分区方案。
实际使用的分区方案是 8M with spiffs，其中应用程序空间为 3MB，SPIFFS 文件系统为 1.5MB。
固件实际占用约 44% 的应用程序空间，SPIFFS 则用于 SQLite 数据库的持久化存储。

3. 系统架构

ESP32-P4 在系统中承担四个核心角色。
第一是 BLE 中心设备，持续扫描周围的 BLE 广播以发现 M5Paper 和 ESP32-C3 客户端。
第二是打卡判定引擎，根据 RSSI 信号强度和数据库记录判定是否触发打卡。
第三是 Web 服务器，提供管理页面和 REST API 供浏览器访问。
第四是数据持久化中心，使用 SQLite 数据库存储打卡记录和工牌配置。

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图1

核心运行逻辑：

下图展示了 ESP32-P4 服务端从启动到主循环的完整运行逻辑，包括 BLE 扫描、打卡判定、新设备处理、异步任务调度和 Web 请求处理等核心流程。

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图2

ESP32-P4 上电后的初始化阶段依次完成 SPIFFS 文件系统与 SQLite 双数据库的初始化、WiFi 网络连接、NTP 时间同步、BLE 扫描启动和 Web 服务器启动。

之后进入主循环，主循环是 ESP32-P4 的运行主体，持续执行以下逻辑。

当扫描到以 M5B 或 C3B 开头的 BLE 广播后，提取设备的 deviceId 和 RSSI 信号强度。如果设备在 config.db 中没有配置记录，则发送 CLEAR_CONFIG 通知，每个设备仅发送一次。

对于有配置记录且 RSSI 大于等于负 70dBm 的设备，检查今日是否已打卡。如果未打卡则写入 checkin.db 并通知客户端。已打卡的设备每 10 分钟更新一次 last_detected 字段。

主循环还需要处理异步 BLE 任务，例如配置下发和打卡通知，这些操作需要主动连接设备，而 BLE 扫描和连接不能同时进行。此外还要响应浏览器发来的 Web API 请求。

4. 核心功能模块

ESP32-P4 的核心功能模块包括 BLE 扫描与设备检测、打卡判定逻辑、新设备处理、BLE 客户端连接与配置下发、Web 服务器与 API，以及 SQLite 数据库管理。

BLE 扫描模块以 BLE 中心设备身份持续扫描周围广播，只关注名称前缀为 M5B 或 C3B 的设备。

扫描间隔和扫描窗口分别设置为 100 毫秒和 99 毫秒，几乎相等的数值意味着 ESP32-P4 几乎处于持续扫描状态，确保不会遗漏任何设备的广播。

扫描回调中只执行两项轻量操作，一是更新内存中的检测记录，二是触发打卡逻辑判断。所有耗时操作例如 BLE 连接和数据库写入都采用异步方式处理，避免阻塞扫描循环。

打卡判定模块是核心业务逻辑。

当检测到设备广播后，首先提取设备 ID 和 RSSI 值，然后查询数据库判断该设备是否有工牌配置。如果没有配置记录，则发送 CLEAR_CONFIG 通知给新设备，并标记已发送以避免重复。如果有配置记录，进一步判断 RSSI 是否大于等于负 70dBm，不满足条件则仅记录检测不触发打卡。

满足 RSSI 条件后，再查询今日是否已打卡。如果当日首次打卡，将记录写入 checkin.db 数据库并发送 CHECKIN 通知到客户端。如果今日已打卡过，则每 10 分钟更新一次 last_detected 时间戳以减少数据库写入操作。

新设备处理模块负责当检测到无配置记录的设备时，通知该设备清空本地配置并进入等待配置状态。

ESP32-P4 扫描到 M5B 或 C3B 开头的广播名称后，查询 config.db 发现无该设备的工牌配置记录。

接着检查内存检测记录中的 clearConfigSent 标志，确认是否已发送过清空配置通知。如果未发送，设置异步标志 pendingClearConfig。
在主循环中检测到该标志后，先停止 BLE 扫描，然后连接目标设备，发送 CLEAR_CONFIG 消息，断开连接，最后恢复扫描。

通过 clearConfigSent 标志确保只发送一次清空配置通知，这样即使设备持续在扫描范围内广播，也只会收到一次 CLEAR_CONFIG 消息。

BLE 客户端连接模块负责主动连接客户端来发送通知或配置。

连接前必须先停止 BLE 扫描，因为扫描和连接不能同时进行。同时尝试 PUBLIC 和 RANDOM 两种 BLE 地址类型以提高连接成功率。连接后等待回调确认，最长 10 秒超时。最多重试 3 次连接。

连接成功后向 BLE 特征值写入数据，写入主数据后如有额外数据如时间同步信息，则延迟 200 毫秒后写入。最后延迟 500 毫秒后断开连接，确保数据已完整传输。

BLE 客户端支持三种消息发送方式，分别是发送配置 JSON 字符串和当前日期用于 Web 端下发工牌配置、发送 CHECKIN 消息和当前日期用于打卡通知、发送 CLEAR_CONFIG 消息用于新设备清空配置。

所有消息都附带 TIME 前缀加 YYYY-MM-DD 格式的日期作为额外数据，实现客户端的时间同步。

Web 服务器模块内置 WebServer 监听 80 端口，提供管理页面和 REST API。

根路径返回管理页面，该页面包含四个标签页分别是打卡记录、检测记录、工牌信息和工牌配置。

api 前缀的 badge_list 路径返回 30 分钟内检测到的在线设备列表。
checkin_list 路径从 SQLite 查询打卡记录 JSON 数据，最多返回 50 条。
detection_list 路径返回内存中的蓝牙检测记录 JSON。
stats 路径返回今日打卡数、在线设备数和当前日期。
config 路径接收 POST 请求，提交工牌配置并下发到设备。
badge_configs 路径返回所有已保存的工牌配置列表。
badge_config 路径根据 deviceId 参数查询单个工牌配置。
delete_config 路径接收 POST 请求删除指定设备的工牌配置。
debug 路径返回系统调试信息包括运行时间、内存使用和设备数量。

SQLite 数据库模块使用双数据库文件方案持久化存储数据。

checkin.db 存储打卡记录，config.db 存储工牌配置。采用双文件方案的原因是单文件多表在 SPIFFS 上容易出现输入输出错误，例如文件系统碎片和写入冲突等，将两个表拆分到独立文件可以提高系统稳定性。

Database 类封装了所有数据库操作，包括初始化 SPIFFS 文件系统和 sqlite3 库并创建数据表、打卡记录的新增和更新、工牌配置的保存查询和删除等。
SPIFFS 初始化时会先尝试挂载，如果失败则格式化后重新挂载，然后分别打开两个数据库文件并创建对应的表结构。

5. Web 管理界面

ESP32-P4 提供完整的 Web 管理页面，用户通过手机或电脑浏览器访问 ESP32-P4 的 IP 地址即可使用。

页面采用四标签设计，所有数据通过 AJAX 异步加载。

打卡记录标签从 checkin_list API 获取数据，显示历史打卡记录，包含姓名、部门、打卡时间和 RSSI 信号强度。
检测记录标签从 detection_list API 获取数据，显示蓝牙实时检测到的设备列表。
工牌信息标签从 badge_configs API 获取数据，显示已保存的所有工牌配置，并支持删除操作。
工牌配置标签从 badge_list API 获取数据，用于选择在线设备并填写信息下发到客户端。

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图3

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图4

工牌配置流程如下。
点击工牌配置标签后，页面自动调用 badge_list API 获取当前在线设备列表。设备以标签形式展示，点击即可选择目标设备。点击设备名称后，自动调用 badge_config API 并传入 deviceId 参数，加载已有配置填充表单。如果该设备之前已配置过，表单会自动填入历史数据。

填写或修改姓名、部门、职位、工号等信息后，点击发送配置到设备按钮，页面将数据 POST 到 config API。ESP32-P4 先将配置保存到数据库，然后通过 BLE 下发配置到目标设备，客户端收到配置后自动重启。

客户端重启后 ESP32-P4 重新检测到该设备，由于已有配置且满足 RSSI 条件，自动完成首次打卡。

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图5

工牌信息标签页展示所有已配置的设备，每条记录右侧有删除按钮。点击删除后调用 delete_config API 并传入 deviceId 参数。删除成功后页面自动刷新列表。
删除操作仅移除数据库中的配置记录，不影响客户端本地的存储内容，客户端仍会显示旧工牌信息，直到收到新的 CLEAR_CONFIG 通知或新配置下发。

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图6

6. BLE 通信协议

ESP32-P4 与客户端通过 BLE GATT 通信，基于自定义 UUID 的服务和特征值：
服务 UUID 为 0000ABCD-0000-1000-8000-00805F9B34FB，
特征值 UUID 为 00001234-0000-1000-8000-00805F9B34FB。

消息协议包含五种类型：

广播名称由客户端发送到 ESP32-P4，格式为 M5B 或 C3B 前缀加上 8 位十六进制设备 ID，这是 BLE 设备名称的一部分。
工牌配置由 ESP32-P4 发送到客户端，格式为 JSON 字符串，包含姓名、部门、职位和工号字段。
打卡通知由 ESP32-P4 发送到客户端，格式为 CHECKIN 前缀加上 HH 冒号 MM 冒号 SS 时间字符串，表示当日首次打卡。
时间同步由 ESP32-P4 发送到客户端，格式为 TIME 前缀加上 YYYY-MM-DD 日期字符串，通常附带在其他消息中一起发送。
清空配置由 ESP32-P4 发送到客户端，格式为 CLEAR_CONFIG 纯文本，用于清空本地配置并进入等待状态。

ESP32-P4 同时支持两种客户端。

M5Paper 的广播前缀是 M5B，特点是带 4.7 寸墨水屏，可以显示工牌信息。
ESP32-C3 的广播前缀是 C3B，特点是无屏幕，通过串口输出设备状态。

两种客户端在打卡逻辑和配置流程上完全一致，ESP32-P4 通过广播名称前缀来区分设备类型。

7. M5Paper 与 ESP32-C3 客户端

客户端作为 BLE 外围设备，职责相对简单。持续广播设备名称，格式为 M5B 或 C3B 前缀加 8 位十六进制设备 ID。通过 GATT 特征值接收配置 JSON 并保存到 ESP32 的 Preferences 存储中。收到 CHECKIN 消息后更新显示或串口输出打卡状态。收到 TIME 消息后判断日期是否跨天，如果是则清除打卡状态。收到新配置后延迟 2 秒自动重启，让 ESP32-P4 重新检测并完成自动打卡。

M5Paper 额外负责墨水屏的 UI 展示，包括工牌信息页面、打卡状态显示和等待配置界面。ESP32-C3 则通过串口以 115200 波特率输出所有状态信息。

M5Paper 墨水屏在不同状态下的显示效果如下。

等待配置界面在首次启动或配置被清空后显示。

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图7

工牌展示界面在已配置并打卡后显示，包含姓名、部门、职位、工号等信息，以及底部的打卡时间。

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图8

8. 完整使用流程

DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图9

第一步是 ESP32-P4 启动。
上电后依次初始化 SPIFFS 文件系统和 SQLite 数据库，连接 WiFi 网络，同步 NTP 时间，启动 BLE 扫描和 Web 服务器，然后持续扫描周围 M5B 和 C3B 开头的广播。

第二步是客户端首次启动。
M5Paper 或 ESP32-C3 上电后检查本地 Preferences 是否有工牌配置。如果没有配置，M5Paper 显示等待配置页面，ESP32-C3 通过串口输出等待配置信息，然后开始 BLE 广播。

第三步是 ESP32-P4 检测新设备。
扫描到新的客户端广播后查询数据库，发现无该设备的工牌配置记录，于是发送 CLEAR_CONFIG 到客户端。客户端收到后清空本地配置，进入等待配置状态。

第四步是 Web 端配置。
用户通过浏览器访问 ESP32-P4 管理页面，点击工牌配置标签，在在线设备列表中选择目标设备，点击设备名称自动加载已有配置，填写姓名、部门、职位、工号，然后点击发送配置到设备按钮。

第五步是 ESP32-P4 下发配置。
收到配置请求后先将配置保存到 SQLite 的 config.db 中，然后从内存检测数组查找设备的 BLE 地址，连接设备后发送配置 JSON 和当前日期。客户端收到配置后保存到本地并自动重启。

第六步是自动打卡。
客户端重启后重新开始广播，ESP32-P4 再次检测到该设备。查询数据库确认有工牌配置且今日未打卡，RSSI 满足条件后将打卡记录写入 checkin.db，然后发送 CHECKIN 通知到客户端。客户端显示或输出打卡状态。

9. 代码与编译烧录

9.1 代码说明

ESP32-P4 的源代码位于 esp32-p4 目录下。
esp32-p4.ino 是系统入口文件，负责初始化 WiFi、NTP、数据库、BLE 和 Web 服务器，以及主循环调度。
config.h 集中管理所有可配置常量。
index_html.h 是单页 Web 应用的 HTML、CSS 和 JavaScript 代码，通过 PROGMEM 存储在 Flash 中。
database.cpp 封装了 SQLite 双数据库的所有操作，所有 SQL 语句使用预编译方式防止注入攻击。
ble_scanner.cpp 实现了 BLE 扫描回调、打卡逻辑、新设备检测和内存记录管理。
ble_client.cpp 实现了 BLE GATT 连接、数据写入和重试机制。
slave 目录包含 ESP32-C6 协处理器的预置固件，通常不需要修改。

9.2 配置参数

config.h 文件中定义了以下可调参数。
WIFI_SSID 和 WIFI_PASSWORD 分别设置 WiFi 网络名称和密码。
NTP_SERVER 设置 NTP 服务器地址，默认使用 pool.ntp.org。
NTP_TIME_OFFSET 设置时区偏移量，28800 秒对应北京时间 UTC 加 8。
BLE_RSSI_THRESHOLD 设置打卡 RSSI 阈值为负 70dBm。
BLE_SCAN_INTERVAL 和 BLE_SCAN_WINDOW 分别设置 BLE 扫描间隔和窗口为 100 毫秒和 99 毫秒。
DEVICE_NAME_PREFIX 和 DEVICE_NAME_PREFIX_C3 分别设置 M5Paper 和 ESP32-C3 的广播名称前缀为 M5B 和 C3B。
WEB_PORT 设置 Web 服务器端口为 80。
SERVICE_UUID 和 CHARACTERISTIC_UUID 设置 BLE 服务和特征值的 UUID。

9.3 编译烧录

可以使用Arduino IDE打开对应的代码文件来编译和上传，也可以使用命令行工具arduino-cli来编译和上传。

如果使用arduino-cli，则编译命令为进入 esp32-p4 目录后执行 arduino-cli compile，指定 FireBeetle 2 ESP32-P4 板型和 8MB 分区方案。烧录命令为 arduino-cli upload，指定串口设备路径和相同的板型及分区方案参数。

需要注意：必须指定至少 8MB 分区方案，否则约 1.4MB 的固件将超过 1.2MB 的限制导致编译失败。

完整文档(完整的格式，代码解析)： DFRobot FireBeetle 2 ESP32-P4 电子工牌服务端实现图9

电子工牌, ESP32-P4