跳至主要內容

构建配置

fastbee大约 18 分钟

构建配置

本文档详细说明 platformio.ini 中各配置项的含义、功能开关的作用，以及如何根据开发/生产需求调整配置。

目录

配置结构概览

platformio.ini
├── [platformio]              ← 全局默认环境
├── [esp32_base]              ← ESP32 系列公共配置（平台、框架、库依赖）
├── [lite_flags]              ← 精简版功能开关
├── [standard_flags]          ← 标准版功能开关
├── [full_flags]              ← 完整版功能开关
├── [lite_src_filter]         ← 精简版源码过滤（排除不需要的 .cpp）
├── [standard_src_filter]     ← 标准版源码过滤
├── [standard_ota_src_filter] ← 标准版+OTA 源码过滤
├── [esp32_runtime_flags]     ← ESP32 运行时参数（TCP/栈大小）
├── [esp32c3_runtime_flags]   ← ESP32-C3 运行时参数
├── [esp32c6_runtime_flags]   ← ESP32-C6 运行时参数
├── [esp32s3_runtime_flags]   ← ESP32-S3 运行时参数
├── [env:esp32-F4R0]          ← ESP32 4MB Flash, 无 PSRAM
├── [env:esp32-F8R4]          ← ESP32 8MB Flash, 4MB PSRAM
├── [env:esp32c3-F4R0]        ← ESP32-C3 4MB Flash
├── [env:esp32s3-F8R0]        ← ESP32-S3 8MB Flash, 无 PSRAM
├── [env:esp32c6-F4R0]        ← ESP32-C6 4MB Flash
├── [env:esp32s3-F8R4]        ← ESP32-S3 8MB Flash, 4MB PSRAM
├── [env:esp32s3-F16R8]       ← ESP32-S3 16MB Flash, 8MB PSRAM
└── [env:native]              ← 本机单元测试（不烧录硬件）

各 [env:*] 通过 ${xxx.yyy} 语法引用公共段，实现配置复用。

公共基础配置 esp32_base

[esp32_base]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.38/platform-espressif32.zip
framework = arduino
build_type = release
board_build.filesystem = littlefs
board_build.partitions = partitions/fastbee.csv
配置项说明
platformESP-IDF 平台版本，使用 pioarduino 55.03.38 发布版
frameworkArduino 框架
build_typerelease 开启编译器优化（-Os），改为 debug 可启用调试符号
board_build.filesystem使用 LittleFS 作为文件系统
board_build.partitions分区表，默认 4MB 使用 fastbee.csv，8MB/16MB 使用对应分区表

预构建/后构建脚本

extra_scripts =
    pre:scripts/kill-stale-processes.py    ; 构建前清理残留串口进程，防止文件锁
    pre:scripts/fastbee-artifacts.py       ; 构建前准备
    post:scripts/fastbee-artifacts.py      ; 构建后归档固件到 dist/

公共 build_flags

以下开关在所有版本中默认启用：

宏定义默认值说明
FASTBEE_ENABLE_MQTT1MQTT 协议支持
FASTBEE_ENABLE_MDNS1mDNS 域名服务（fastbee.local）
FASTBEE_ENABLE_AP_MODE1WiFi AP 热点模式
FASTBEE_ENABLE_WEB_SERVER1AsyncWebServer Web 服务器
FASTBEE_ENABLE_WEB_STATIC1静态文件服务（LittleFS）
FASTBEE_ENABLE_WEB_API1REST API 路由
FASTBEE_ENABLE_AUTH1用户认证
FASTBEE_ENABLE_SESSION1会话管理
FASTBEE_ENABLE_TASK_MANAGER1任务调度管理
FASTBEE_ENABLE_HEALTH_MONITOR1系统健康监控
FASTBEE_ENABLE_LOGGER1日志系统
FASTBEE_ENABLE_PERIPH_EXEC1外设执行引擎
FASTBEE_ENABLE_GPIO1GPIO 控制
FASTBEE_ENABLE_SENSOR_DRIVER1传感器驱动
FASTBEE_ENABLE_LCD1LCD 显示
FASTBEE_ENABLE_SEVEN_SEGMENT1七段数码管
FASTBEE_ENABLE_DNS1DNS 解析
FASTBEE_LOG_BUFFER_SIZE256单条日志缓冲区大小（字节）
FASTBEE_JSON_DOC_SIZE8192ArduinoJson 文档分配大小（字节）
ASYNCWEBSERVER_REGEX1启用 URL 正则匹配
NDEBUG-关闭标准库 assert（release 模式）

功能版本 Flag 段

项目提供三个功能级别，通过 build_flags 引用切换：

lite_flags（精简版）

适用于 4MB Flash 的小容量设备（ESP32-C3/C6），关闭所有高级功能以节省固件空间。

standard_flags（标准版）

适用于中等容量设备，保留 WiFi、MQTT、Modbus、规则脚本和常用外设，默认关闭 TCP/HTTP/CoAP、OTA、用户/角色管理、BLE、以太网和 4G，优先保证无 PSRAM ESP32 的内部 DRAM 余量。

full_flags（完整版）

适用于 8MB+ Flash + PSRAM 的高端设备，启用 TCP/HTTP/CoAP、OTA、用户管理、以太网、4G 等完整功能。FASTBEE_ENABLE_BLE 在 Full 预设中保留为 1，但当前设备端配网和管理仍以 WiFi AP/Web 为主，未提供完整 BLE 配网页面和处理链路。

版本对比矩阵：

功能litestandardfull
TCP 客户端✗✗✓
HTTP 客户端✗✗✓
CoAP 协议✗✗✓
Modbus RTU✗✓✓
OTA 升级✗✗✓
规则脚本✗✓✓
命令脚本✗✓✓
用户管理✗✗✓
角色管理✗✗✓
文件管理✗✗✓
日志查看器✗✗✓
文件日志✗✗✓
BLE 蓝牙✗✗预留
以太网 W5500✗✗✓
4G 蜂窝✗✗✓
I2C 传感器✗✓✓
RFID✗✓✓
红外遥控✗✓✗¹
NeoPixel✓✓✓
DS1302 RTC✗✗✓
LCD1602 字符液晶✗✗✓
PSRAM✗✗✓
国际化 i18n✗✗✓

¹ ESP32-S3 的 RMT 驱动与 IRremoteESP8266 冲突，S3 环境显式禁用红外。

当前预设策略：标准版关闭以太网、4G 和 BLE；完整版启用以太网、4G，并保留 BLE 编译开关。由于当前源码未提供完整 BLE 配网/通信链路，交付时不要把 BLE 作为可用功能承诺。

运行时参数配置

运行时参数控制 ESP32 内部的 TCP 连接数、任务栈大小等，按芯片型号分四组：

参数ESP32ESP32-C3ESP32-C6ESP32-S3说明
CONFIG_ASYNC_TCP_MAX_CONNECTIONS64614AsyncTCP 最大并发连接数
CONFIG_ASYNC_TCP_QUEUE_SIZE84824TCP 事件队列深度
ARDUINO_LOOP_STACK_SIZE16384122881228816384Arduino loopTask 栈大小（字节）
CONFIG_ASYNC_TCP_TASK_WDT_TIMEOUT10101010AsyncTCP 任务看门狗超时（秒）
SCRIPT_TASK_STACK8192614461448192规则脚本任务栈大小
SIMPLE_TASK_STACK6144409640966144简单定时任务栈大小

S3 参数说明：ESP32-S3 配 8MB+ PSRAM，内部 DRAM 在 WiFi+MQTT+WebServer 全开后仅剩 ~18-35KB。 将 TCP 连接数提升至 14、队列深度提升至 24，可支撑多标签页并发访问（峰值 10-14 PCB）。 配合 PSRAM 阈值（见下文）将 HTTP 缓冲区卸载到 PSRAM，内部 DRAM 专供 lwIP TCP PCB（~172B/个，必须内部 DRAM）。

ESP32-C3/C6 还额外配置 USB 串口模式：

-DARDUINO_USB_MODE=1           ; USB-JTAG 模式
-DARDUINO_USB_CDC_ON_BOOT=1    ; 启用 USB CDC 串口

调优提示：

  • 如遇栈溢出崩溃（Guru Meditation Error: Stack canary watchpoint triggered），可增大对应 *_STACK 值。
  • 增大 CONFIG_ASYNC_TCP_MAX_CONNECTIONS 可支持更多并发 Web 请求，但会占用更多 RAM。
  • S3 有 PSRAM 时建议同步降低 PSRAM 阈值（见 PSRAM 配置段），释放内部 DRAM 供 TCP PCB 使用。

PSRAM 配置

背景

ESP32-S3 内部 DRAM 仅 ~320KB，WiFi 协议栈 + MQTT + AsyncWebServer 全开后，内部 DRAM 可用空间常仅剩 18-35KB。 若 HTTP 请求缓冲区、ArduinoJson 序列化 String 等大分配无法卸载到 PSRAM，会导致 new 失败 → abort()。

阈值配置

通过 heap_caps_malloc_extmem_enable(threshold) 控制分配策略：

// src/main.cpp — setup() 中调用
heap_caps_malloc_extmem_enable(512);  // ≥ 512B 的分配请求优先用 PSRAM
阈值效果适用场景
4096（旧默认）仅 ≥ 4KB 的分配用 PSRAMPSRAM 较小或无 HTTP 并发压力
512（当前）≥ 512B 的分配用 PSRAMESP32-S3 + PSRAM，AsyncWebServer 并发场景

为什么是 512 而不是 4096？

分配类型典型大小能否用 PSRAM
AsyncWebServer HTTP 缓冲区1-2 KB✅ 可以（512 阈值命中，4096 阈值无法命中）
ArduinoJson String 序列化200B - 2KB✅ 可以
lwIP TCP PCB 结构体~172 B❌ 必须内部 DRAM（硬件要求）
FreeRTOS 任务栈2-16 KB⚠️ 可以但延迟略高
WiFi 协议栈缓冲不等❌ 内部 DRAM

PSRAM 延迟：PSRAM 通过 SPI 访问，延迟比内部 DRAM 高约 3x，但对 HTTP/JSON 响应构建无感知影响（瓶颈在网络 I/O）。

构建时启用 PSRAM

esp32-F8R4、esp32s3-F8R4 和 esp32s3-F16R8 环境通过 board_build.psram = enabled 启用 PSRAM；full_flags 同时定义 FASTBEE_USE_PSRAM=1 和 BOARD_HAS_PSRAM：

[full_flags]
build_flags =
    -DFASTBEE_USE_PSRAM=1
    -DBOARD_HAS_PSRAM

; 在 [env:esp32-F8R4] / [env:esp32s3-F8R4] / [env:esp32s3-F16R8] 中
board_build.psram = enabled

无 PSRAM 的环境（esp32s3-F8R0、esp32-F4R0 等）不设置此项，main.cpp 中 #ifdef BOARD_HAS_PSRAM 分支不会编译。

源码过滤器 src_filter

通过 build_src_filter 排除不参与编译的 .cpp 文件，减小固件体积并避免不必要的库依赖扫描：

lite_src_filter（精简版）

排除最多文件：OTA、用户/角色管理、日志、规则脚本、TCP/HTTP/CoAP 协议、4G 蜂窝和以太网适配器。

standard_src_filter（标准版，无 OTA）

排除 OTA、用户/角色管理、日志、TCP/HTTP/CoAP、4G 蜂窝和以太网适配器，但保留 RuleScript。

standard_ota_src_filter（标准版 + OTA）

排除用户/角色管理、日志、TCP/HTTP/CoAP、4G 蜂窝和以太网适配器，保留 OTA 和 RuleScript。

网络适配器排除策略

所有非 full 环境（lite / standard / standard+OTA）的 FASTBEE_ENABLE_CELLULAR=0 和 FASTBEE_ENABLE_ETHERNET=0，因此将 CellularAdapter.cpp 和 EthernetAdapter.cpp 从 build_src_filter 中排除。这样可以：

  1. 避免 LDF 拉入不必要的库依赖：排除 CellularAdapter.cpp 后，PlatformIO 的 LDF（库依赖查找器）不会扫描该文件，从而不会强制拉入 TinyGSM 和 SSLClient 等仅 4G 场景需要的第三方库。
  2. 减少编译时间：跳过大文件编译，尤其是包含 TinyGSM 模板头文件的 CellularAdapter.cpp。
  3. 不影响 MQTTS 功能：ESP32 标准版的 MQTTS 使用内置 WiFiClientSecure（即 NetworkClientSecure），不依赖 SSLClient。SSLClient 仅是为 4G 模块（EC801E-CN）提供软件 TLS 的包装器。

full 环境（FASTBEE_ENABLE_CELLULAR=1、FASTBEE_ENABLE_ETHERNET=1）没有 build_src_filter，所有源文件均参与编译。

注意：build_src_filter 仅排除 .cpp 源文件。对应的头文件 .h 仍会被包含（通过 #if 宏控制跳过实现），因此排除源文件时对应的功能宏必须设为 0。

构建环境 env

每个 [env:*] 代表一个具体的目标硬件配置：

命名规则

env:{芯片}-{Flash大小}{PSRAM大小}

  • F4 = 4MB Flash，F8 = 8MB，F16 = 16MB
  • R0 = 无 PSRAM，R4 = 4MB PSRAM，R8 = 8MB PSRAM

环境列表

环境芯片FlashPSRAM功能版本分区表
esp32-F4R0ESP324MB无standardfastbee.csv
esp32-F8R4ESP328MB4MBfullfastbee-8MB.csv
esp32c3-F4R0ESP32-C34MB无litefastbee.csv
esp32s3-F8R0ESP32-S38MB无standard+OTAfastbee-8MB.csv
esp32c6-F4R0ESP32-C64MB无litefastbee.csv
esp32s3-F8R4ESP32-S38MB4MBfullfastbee-8MB.csv
esp32s3-F16R8ESP32-S316MB8MBfullfastbee-16MB.csv
native本机--单元测试-

native 环境

本机单元测试环境，不烧录硬件：

[env:native]
platform = native
test_framework = unity
test_build_src = no           ; 不自动编译 src/，由测试手动引入

功能开关速查表

所有 FASTBEE_ENABLE_* 宏取值为 0（禁用）或 1（启用）。

网络与协议

宏定义说明依赖库
FASTBEE_ENABLE_MQTTMQTT 客户端PubSubClient
FASTBEE_ENABLE_MDNSmDNS 服务ESPmDNS
FASTBEE_ENABLE_AP_MODEWiFi AP 热点-
FASTBEE_ENABLE_DNSDNS 解析-
FASTBEE_ENABLE_TCP原生 TCP 客户端-
FASTBEE_ENABLE_HTTPHTTP 客户端-
FASTBEE_ENABLE_COAPCoAP 协议-
FASTBEE_ENABLE_MODBUSModbus RTU 主站-
FASTBEE_MODBUS_SLAVE_ENABLEModbus RTU 从站-
FASTBEE_ENABLE_ETHERNETW5500 以太网-
FASTBEE_ENABLE_CELLULAREC801E 4G 蜂窝TinyGSM

Web 服务

宏定义说明
FASTBEE_ENABLE_WEB_SERVERAsyncWebServer 服务器
FASTBEE_ENABLE_WEB_STATICLittleFS 静态文件服务
FASTBEE_ENABLE_WEB_APIREST API 路由注册
FASTBEE_ENABLE_AUTHJWT/Session 用户认证
FASTBEE_ENABLE_SESSION会话管理
FASTBEE_WEB_START_EARLY网络就绪前启动 Web（调试用）

系统管理

宏定义说明
FASTBEE_ENABLE_OTAOTA 空中升级
FASTBEE_ENABLE_OTA_FSOTA 文件系统更新
FASTBEE_ENABLE_FILE_MANAGERWeb 文件管理器
FASTBEE_ENABLE_CONFIG_TRANSFER配置导入/导出
FASTBEE_ENABLE_LOG_VIEWERWeb 日志查看器
FASTBEE_ENABLE_FILE_LOGGING日志写入文件
FASTBEE_ENABLE_USER_ADMIN多用户管理
FASTBEE_ENABLE_ROLE_ADMIN角色权限管理
FASTBEE_SINGLE_ADMIN_MODE单管理员模式（简化认证）

外设与传感器

宏定义说明
FASTBEE_ENABLE_GPIOGPIO 输入/输出控制
FASTBEE_ENABLE_PERIPH_EXEC外设执行引擎
FASTBEE_ENABLE_SENSOR_DRIVER传感器驱动框架
FASTBEE_ENABLE_I2C_SENSORSI2C 传感器（BMP280/MPU6050）
FASTBEE_ENABLE_DS18B20DS18B20 温度传感器
FASTBEE_ENABLE_RFIDMFRC522 RFID 读卡器
FASTBEE_ENABLE_IR_REMOTE红外遥控
FASTBEE_ENABLE_LCDLCD 显示屏
FASTBEE_ENABLE_LED_SCREENLED 点阵屏
FASTBEE_ENABLE_SEVEN_SEGMENT七段数码管
FASTBEE_ENABLE_NEOPIXELWS2812 NeoPixel LED
FASTBEE_ENABLE_DS1302DS1302 实时时钟（3线）
FASTBEE_ENABLE_LCD1602LCD1602 I2C 字符液晶
FASTBEE_ENABLE_BLEBLE 蓝牙（NimBLE）

脚本引擎

宏定义说明
FASTBEE_ENABLE_RULE_SCRIPT规则脚本引擎
FASTBEE_ENABLE_COMMAND_SCRIPT命令脚本引擎

系统基础

宏定义说明
FASTBEE_ENABLE_LOGGER日志系统
FASTBEE_ENABLE_TASK_MANAGER任务调度器
FASTBEE_ENABLE_HEALTH_MONITOR系统健康监控
FASTBEE_ENABLE_STORAGE_CACHE存储缓存层
FASTBEE_USE_PSRAM启用 PSRAM 外部 RAM
FASTBEE_ENABLE_I18N国际化多语言

按需编译策略

按需编译通过 FASTBEE_ENABLE_* 宏控制各驱动/功能是否编译进固件，实现 Flash/RAM 资源按需分配。

设计原则

  1. 资源有限：ESP32 系列 Flash 为 4-16MB，RAM 仅 320KB-8MB，不是每个设备都需要所有功能
  2. 编译隔离：禁用的功能不编译，节省 Flash 空间；对应驱动实例不创建，节省 RAM
  3. 配置灵活：在 platformio.ini 的 build_flags 中通过 -DFASTBEE_ENABLE_XXX=1 启用
  4. 默认值分层：基础功能（GPIO/传感器）默认启用；外设驱动按需启用

开关使用规则

功能开关的原则是：设备实际不用的外设、驱动、协议和管理功能就关闭；设备确实接了硬件、业务流程确实依赖时再打开。这样可以减少编译进固件的代码、全局对象、任务栈、协议缓冲区和第三方库依赖，直接节省 Flash 和运行时 RAM，降低长期运行时内存碎片、堆不足和任务栈紧张的风险。

场景建议配置说明
没有接对应硬件-DFASTBEE_ENABLE_XXX=0不编译对应驱动，不创建运行时对象，节省 RAM/Flash
硬件只是预留，当前版本不用-DFASTBEE_ENABLE_XXX=0预留硬件不等于软件必须启用，量产默认应关闭
已接硬件且业务要使用-DFASTBEE_ENABLE_XXX=1同时确认依赖库、引脚、UI/API 和配置项可用
仅开发调试使用开发环境开，生产环境关例如文件管理、日志查看器、详细日志、OTA 等
RAM 占用高的通信模块默认关闭，按项目打开例如 BLE、4G、以太网、TCP/HTTP/CoAP

建议先选择最接近硬件资源的预设：

  • 4MB、无 PSRAM、功能少：优先 lite_flags
  • ESP32 4MB/8MB、无 PSRAM、常规网关：优先 standard_flags
  • ESP32-S3/ESP32 带 PSRAM、需要完整联网能力：优先 full_flags

然后只在具体 [env:*] 里覆盖少量差异。不要因为“以后可能会用”提前打开模块；后续需要时再把对应宏改为 1 重新编译即可。

资源配置影响分析

驱动Flash 占用RAM 占用默认值建议
MQTT~15KB~2KB1基础功能，保持启用
Modbus RTU~20KB~1KB1工业场景常用，保持启用
mDNS~5KB~200B1基础网络功能，保持启用
GPIO~3KB~100B1基础功能，保持启用
传感器驱动~8KB~200B1基础功能，保持启用
Web 服务器~25KB~2KB1基础功能，保持启用
认证/会话~8KB~500B1安全基础，保持启用
健康监控~4KB~200B1稳定性基础，保持启用
NeoPixel~12KB~300B1²可改为 0，多数设备不需要
DS1302 RTC~2KB~100B0按需启用（有 NTP 可替代）
LCD1602~3KB~100B0按需启用（有 OLED 可替代）
LCD/OLED~20KB~1.2KB0按需启用（需 U8g2 库）
七段数码管~3KB~32B/实例0按需启用
LED 点阵屏~10KB~500B0按需启用
RFID MFRC522~12KB~200B0按需启用
红外遥控~8KB~300B0按需启用
I2C 传感器~15KB~500B0按需启用
BLE 蓝牙~80KB~20-30KBFull 预留当前无完整 BLE 配网页面和处理链路，交付默认不要依赖
以太网 W5500~8KB~8KB0标准版关闭；仅 Full/实际硬件需要时启用
4G 蜂窝~15KB~10-15KB0标准版关闭；RAM 占用高，仅 Full/实际硬件需要时启用
TCP 客户端~10KB~500B0按需启用
HTTP 客户端~8KB~300B0按需启用
CoAP 协议~12KB~500B0按需启用
规则脚本~8KB~2KB0按需启用
命令脚本~4KB~500B0按需启用
用户管理~4KB~200B0按需启用
文件管理~3KB~200B0按需启用
日志查看器~2KB~100B0按需启用
文件日志~2KB~200B0按需启用

该表的“默认值”是保守基准；具体预设以 lite_flags / standard_flags / full_flags 为准。当前标准版关闭 Ethernet/Cellular/BLE，完整版开启 Ethernet/Cellular；BLE 仅保留开关，不作为当前可用配网功能。更细的 RAM/Flash 预算、典型裁剪方案和检查清单见 资源占用与功能裁剪。

² NEOPIXEL 优化建议：NeoPixel LED 驱动占用 ~12KB Flash，在 lite 精简版本中也是默认启用的。 如果设备不使用 WS2812/NeoPixel 灯带，可在 lite_flags 中设置为 0 节省空间：

-DFASTBEE_ENABLE_NEOPIXEL=0

资源节省效果

Lite 版本（ESP32-C3/C6 4MB） 按需编译后，仅保留基础功能：

类别启用模块Flash 占用
协议MQTT~15KB
网络mDNS + DNS + AP~10KB
WebServer + Static + API~25KB
安全Auth + Session~8KB
系统Logger + Task + Health + Exec~17KB
外设GPIO + Sensor~11KB
合计基础~86KB

如启用全部可选驱动，Flash 增加约 75KB（NeoPixel 12KB + LCD 20KB + RFID 12KB + 红外 8KB + I2C 传感器 15KB + 其他 ~8KB）。

启用/关闭功能的方法

在 platformio.ini 对应环境段添加或覆盖 build_flags。启用使用 1，关闭使用 0：

[env:esp32s3-F16R8]
build_flags =
    ${esp32_base.build_flags}
    ${esp32s3_runtime_flags.build_flags}
    ${full_flags.build_flags}
    -DFASTBEE_ENABLE_DS1302=1    ; 启用 DS1302 实时时钟
    -DFASTBEE_ENABLE_LCD1602=1   ; 启用 LCD1602 字符液晶
    -DFASTBEE_ENABLE_CELLULAR=0  ; 未接 4G 模块则关闭，节省 RAM
    -DFASTBEE_ENABLE_ETHERNET=0  ; 未接 W5500 则关闭，节省 RAM
    -DFASTBEE_ENABLE_FILE_MANAGER=0 ; 生产环境不需要文件管理则关闭

也可以在 [lite_flags]、[standard_flags]、[full_flags] 中统一调整某个版本的默认值。直接修改 FeatureFlags.h 会影响所有未显式覆盖的环境，建议只用于定义全局兜底默认值。

注意：关闭宏主要影响编译和运行时对象创建；设备上已保存的历史配置数据可能仍在 LittleFS/NVS 中，但对应功能关闭后不会再创建驱动实例或执行相关逻辑。需要彻底清理配置时，再配合配置迁移或恢复出厂设置处理。

日志等级配置

日志系统有编译时和运行时两层控制。

编译时控制

宏定义值说明
FASTBEE_STRIP_INFO_LOGS0保留 INFO 日志（开发）
FASTBEE_STRIP_INFO_LOGS1编译时移除 INFO 日志（生产，节省 Flash）
FASTBEE_DEBUG_LOG0移除 DEBUG/VERBOSE 日志（默认）
FASTBEE_DEBUG_LOG1启用 DEBUG/VERBOSE 日志（开发）
CORE_DEBUG_LEVEL0-5ESP-IDF 内核日志级别

CORE_DEBUG_LEVEL 可选值：

值级别输出内容
0None无输出
1Error仅错误（默认）
2Warn警告 + 错误
3Info信息 + 警告 + 错误
4Debug调试 + 以上所有
5Verbose最详细输出

日志层级关系

LOG_VERBOSE → LOG_DEBUG → LOG_INFO → LOG_WARNING → LOG_ERROR → LOG_FATAL
   ↑ DEBUG_LOG=1 时生效    ↑ STRIP_INFO=0 时生效     ↑ 始终输出

开发调试配置

在对应 [xxx_flags] 段修改：

; 开启全部应用日志
-DFASTBEE_STRIP_INFO_LOGS=0
-DFASTBEE_DEBUG_LOG=1

; 开启 ESP-IDF 内核调试日志
-DCORE_DEBUG_LEVEL=4

生产发布配置

; 移除 INFO 和 DEBUG 日志，节省 Flash
-DFASTBEE_STRIP_INFO_LOGS=1
-DFASTBEE_DEBUG_LOG=0
-DCORE_DEBUG_LEVEL=1

库依赖说明

核心依赖（所有环境）

库名版本用途
ArduinoJson7.4.2JSON 序列化/反序列化
PubSubClient^2.8MQTT 客户端
ESPAsyncWebServer^3.6.0异步 Web 服务器
AsyncTCP^3.3.2异步 TCP（ESPAsyncWebServer 底层）
U8g2^2.35.9LCD/OLED 显示驱动
Adafruit NeoPixel^1.12.0WS2812 LED 控制
DHT sensor library^1.4.6DHT11/22 温湿度传感器
Adafruit Unified Sensor^1.1.14传感器统一接口
OneWire^2.3.8单总线协议（DS18B20）
DallasTemperature^3.9.0DS18B20 温度传感器

当前核心依赖中不包含 NimBLE-Arduino。Full 预设虽然保留 FASTBEE_ENABLE_BLE=1，但设备端尚未提供完整 BLE 配网/通信链路；如需真正启用 BLE，需要补齐依赖、源码入口、Web/API 能力和资源验证。

扩展依赖（按环境声明，功能仍受宏控制）

库名版本用途
Adafruit BMP280^2.6.8气压/温度传感器
Adafruit MPU6050^2.2.6六轴姿态传感器
MFRC522^1.4.11RFID 读卡器
IRremoteESP8266^2.8.6红外遥控（ESP32 原生）
TinyGSM^0.11.74G 蜂窝模块驱动；仅 full 环境声明
SSLClient1.3.24G 软件 TLS（EC801E MQTTS）；仅 full 环境声明

TinyGSM / SSLClient 依赖优化：非 full 环境（esp32-F4R0、esp32s3-F8R0、esp32c3-F4R0、esp32c6-F4R0）的 FASTBEE_ENABLE_CELLULAR=0，已从 lib_deps 中移除 TinyGSM 和 SSLClient。标准版 MQTTS 使用 ESP32 内置的 WiFiClientSecure（NetworkClientSecure），无需 SSLClient。该优化配合 build_src_filter 排除 CellularAdapter.cpp，避免 LDF 扫描拉入未使用的库。

单元测试依赖（native 环境）

库名版本用途
ArduinoJson7.4.2JSON 处理
Unity^2.6.0单元测试框架

lib_ignore

部分环境排除不兼容的库：

环境排除的库原因
esp32-F4R0NimBLE-Arduino4MB 标准版不启用 BLE
esp32c3-F4R0NimBLE-ArduinoLite 不启用 BLE
esp32c6-F4R0NimBLE-Arduino, OneWire, DallasTemperatureLite 不启用 BLE；C6 当前关闭 DS18B20
esp32s3-F8R4/F16R8IRremoteESP8266ESP32-S3 RMT 驱动冲突

常用构建命令

编译与清理

# 编译默认环境（esp32-F4R0）
pio run

# 编译指定环境
pio run -e esp32s3-F16R8

# 编译并输出详细信息
pio run -e esp32s3-F16R8 -v

# 清理指定环境的构建产物
pio run -e esp32s3-F16R8 --target clean

烧录与监控

# 编译并烧录固件
pio run -e esp32s3-F16R8 -t upload

# 指定串口烧录
pio run -e esp32s3-F16R8 -t upload --upload-port COM3

# 编译、烧录并自动打开串口监控
pio run -e esp32s3-F16R8 -t upload -t monitor

# 烧录文件系统（Web 静态资源）
pio run -e esp32s3-F16R8 -t uploadfs

# 指定串口上传文件系统
pio run -e esp32s3-F16R8 -t uploadfs --upload-port COM3

# 串口监视器
pio device monitor -e esp32s3-F16R8

# 指定端口和波特率
pio device monitor --port COM3 --baud 115200

uploadfs 会覆盖开发板上的整个 LittleFS 分区。上传前确认 data/ 目录包含当前环境需要的 Web 静态资源和默认配置。

测试、依赖与项目信息

# 运行本机单元测试
pio test -e native

# 运行指定测试用例
pio test -e native -f test_modbus

# 安装所有环境的依赖
pio pkg install

# 安装指定环境的依赖
pio pkg install -e esp32s3-F16R8

# 更新依赖到最新兼容版本
pio pkg update

# 列出可用串口设备
pio device list

# 查看所有构建环境
pio project config

# 查看指定环境配置
pio project config -e esp32s3-F16R8

# 查看环境变量和构建标志
pio run -e esp32s3-F16R8 --target envdump

构建产物

编译完成后固件归档到 dist/ 目录：

dist/business/firmware/{env}/
├── factory.bin     ← 完整固件（含 bootloader + 分区表）
├── firmware.bin    ← 应用固件
└── partitions.bin  ← 分区表

相关文档

上次编辑于:
贡献者: kerwincui
蜂信物联 | 曲靖蜂信科技有限公司
Copyright © 2026 fastbee