Resource Usage and Feature Trimming
This document determines "which features go into firmware, which should be disabled". Build sections, environment lists and macro definition locations: Build Configuration; this page only covers resource budgets, trimming strategies and pre-delivery checklists to avoid duplicate maintenance of full platformio.ini descriptions.
ESP32 Memory Background
| Resource | ESP32 | ESP32-S3 | ESP32-C3 | ESP32-C6 |
|---|---|---|---|---|
| Internal SRAM | ~320KB | ~512KB | ~400KB | ~512KB |
| Available Heap (after boot) | ~220KB | ~310KB | ~140KB | ~220KB |
| PSRAM | Up to 8MB in the release matrix | Up to 8MB in the release matrix | None | None |
| Flash | 4MB or 8MB | 8MB or 16MB | 4MB | 4MB or 8MB |
Key constraints:
- WiFi, lwIP, FreeRTOS, TLS handshakes still require internal DRAM and cannot fully rely on PSRAM.
- PSRAM is suitable for HTTP/JSON buffers and larger temporary objects, not for high-real-time or hardware-required internal DRAM structures.
- ESP32-C3/C6 no-PSRAM environments should keep unused displays, network adapters and advanced peripherals disabled at runtime; compile-time trimming is a last resort when Flash is tight.
- For long-term operation, largest contiguous heap block matters more than total free heap; with 35KB total free but only 8KB max contiguous block, large object allocation may still fail.
Feature Flag Method
Feature flags are set through build_flags in platformio.ini:
ini
build_flags =
-DFASTBEE_ENABLE_XXX=1 ; Enable
-DFASTBEE_ENABLE_XXX=0 ; DisableDefault values are defined in include/core/FeatureFlags.h; unified_flags in platformio.ini provides the release baseline, and each [env:*] section applies only hardware- or partition-specific overrides.
A feature is active only when it is compiled, user-enabled, accepted by the startup budget, and not temporarily runtime-disabled. HealthMonitor may runtime-disable file logging, Modbus, scripts, peripheral execution or MQTTS under sustained memory pressure without overwriting the user's feature choices.
Runtime Memory Degradation
The firmware prioritizes the Web core during memory pressure, but it does not guarantee that Web requests always succeed. At very low internal DRAM, requests may return 503 or time out, and the firmware may perform a controlled reboot.
- At SEVERE pressure, it closes SSE clients, can downgrade MQTTS to MQTT, stops Modbus and pauses peripheral execution or optional peripherals.
- At a chip-specific CRITICAL threshold, 30 seconds of sustained pressure disables MQTT in
protocol.json; 90 seconds schedules a controlled reboot, subject to the boot-loop guard. - Below 4KB internal DRAM, EMERGENCY recovery runs immediately; if it remains below 4KB for 5 seconds after the startup protection window, a controlled reboot is scheduled.
- When memory returns to NORMAL, restorable services retry recovery. MQTT that was persistently disabled still requires the user to re-enable it.
Trimming Priority Order
| Priority | Module | Recommendation |
|---|---|---|
| 1 | BLE | Not in the current release path; do not enable until provisioning, dependencies and resource tests are complete |
| 2 | 4G / Ethernet | Not compiled in esp32-F4R0, esp32c3-F4R0, esp32c6-F4R0 or esp32c6-F8R0; keep runtime-disabled in other environments unless matching hardware is present |
| 3 | OTA / Custom File APIs / File Logging / User Roles | Enable based on maintenance needs for delivery; do not enable OTA by default on 4MB environments |
| 4 | LCD/OLED, NeoPixel, LED Matrix, RFID, IR, I2C Advanced Sensors | Disable if modules not connected; do not enable for reserved hardware in production configs |
| 5 | Rule Script / Command Script | Enable when field automation and scripting is needed; prefer fixed actions in low-memory environments |
The TCP client, HTTP client and CoAP protocol modules were removed from the codebase (MQTT and Modbus RTU retained) and no longer participate in trimming decisions.
Module Resource Budget
These are estimates for selection and trimming decisions; actual usage is determined by current build output and runtime /api/system/info.
Peripherals & Display
| Flag Macro | RAM | Flash | Preset | Notes |
|---|---|---|---|---|
FASTBEE_ENABLE_LCD | ~1.2KB | ~20KB | Unified baseline | OLED/LCD, depends on U8g2 |
FASTBEE_ENABLE_NEOPIXEL | ~2KB + 3B/pixel | ~12KB | Enabled by default | WS2812 LED strip; use FASTBEE_NEOPIXEL_MAX_LEDS to lower cap |
FASTBEE_ENABLE_LED_SCREEN | Dynamic allocation | ~10KB | Unified baseline | WS2812B LED matrix; runtime-gated |
FASTBEE_ENABLE_I2C_SENSORS | ~500B | ~15KB | Unified baseline | BMP280, MPU6050, SHT31, BH1750, AHT20 etc. |
FASTBEE_ENABLE_RFID | ~200B | ~12KB | Unified baseline | MFRC522 |
FASTBEE_ENABLE_IR_REMOTE | ~300B | ~8KB | Environment override | Disabled on esp32s3-F8R8; verify RMT/library compatibility |
FASTBEE_ENABLE_SENSOR_DRIVER | ~200B | ~8KB | Enabled by default | DHT, DS18B20 and other basic sensors |
FASTBEE_ENABLE_SEVEN_SEGMENT | ~32B/instance | ~3KB | Enabled by default | TM1637 digital tube |
FASTBEE_ENABLE_DS1302 | ~100B | ~2KB | Disabled by default | Usually unnecessary when NTP is available |
FASTBEE_ENABLE_LCD1602 | ~100B | ~3KB | Disabled by default | LCD1602/LCD2004 I2C character display |
Network & Protocol
| Flag Macro | RAM | Flash | Preset | Notes |
|---|---|---|---|---|
FASTBEE_ENABLE_MQTT | ~4-8KB | ~15KB | Enabled by default | Core cloud link; MQTTS temporarily needs substantially more internal DRAM |
FASTBEE_ENABLE_MODBUS | ~3-5KB | ~20KB | Unified baseline | Modbus RTU master; enable at runtime only when used |
FASTBEE_MODBUS_SLAVE_ENABLE | ~440B | ~10KB | Disabled in release builds | Slave mode is not exposed as a current release capability |
FASTBEE_ENABLE_ETHERNET | ~8KB | ~8KB | Environment-dependent | W5500; keep runtime-disabled without hardware |
FASTBEE_ENABLE_CELLULAR | ~10-15KB | ~15KB | Environment-dependent | EC801E-CN; keep runtime-disabled without hardware |
FASTBEE_ENABLE_BLE | ~20-30KB | ~80KB | Disabled by default | No complete BLE provisioning page or processing chain; verify dependencies before enabling |
FASTBEE_ENABLE_MDNS | ~2KB | ~5KB | Enabled by default | Disabling removes fastbee.local access |
FASTBEE_ENABLE_DNS | ~1KB | ~3KB | Enabled by default | Commonly used on AP provisioning page |
FASTBEE_ENABLE_AP_MODE | ~1-2KB | ~2KB | Enabled by default | Disabling affects first-time provisioning |
System & Web
| Flag Macro | RAM | Flash | Preset | Notes |
|---|---|---|---|---|
FASTBEE_ENABLE_WEB_SERVER | ~20-30KB | ~25KB | Enabled by default | Web console and REST API core |
FASTBEE_ENABLE_PERIPH_EXEC | ~2-4KB | ~8KB | Enabled by default | Timer, event, platform trigger automation rules |
FASTBEE_ENABLE_RULE_SCRIPT | ~4-8KB | ~8KB | Unified baseline | Rule script engine, subject to the startup budget |
FASTBEE_ENABLE_COMMAND_SCRIPT | ~1-2KB | ~3KB | Inherits rule script | Command script |
FASTBEE_ENABLE_OTA / FASTBEE_ENABLE_OTA_FS | ~4-6KB | ~10KB | Partition-dependent | Enabled only for 8MB/16MB A/B layouts |
FASTBEE_ENABLE_STORAGE_CACHE | ~2-4KB | ~1KB | Disabled by default | Large config files bypass cache to avoid peak doubling |
FASTBEE_ENABLE_FILE_LOGGING | ~500B | ~3KB | Unified baseline | Continuous Flash writes affect lifespan |
FASTBEE_ENABLE_USER_ADMIN | ~500B | ~5KB | Unified baseline | User-management routes; runtime-gated |
FASTBEE_ENABLE_FILE_MANAGER | ~500B | ~3KB | Disabled by default | File APIs for custom diagnostic tools; no release Web page |
FASTBEE_ENABLE_HEALTH_MONITOR | ~200B | ~4KB | Enabled by default | Not recommended to disable |
FASTBEE_ENABLE_LOGGER | ~300B | ~6KB | Enabled by default | Can reduce FASTBEE_LOG_BUFFER_SIZE |
Performance Tuning Parameters
| Parameter | Recommendation | Notes |
|---|---|---|
FASTBEE_USE_PSRAM / BOARD_HAS_PSRAM | Only enable on environments with actual PSRAM | Combined with heap_caps_malloc_extmem_enable(256) to prefer PSRAM for larger HTTP/JSON allocations |
FASTBEE_JSON_DOC_SIZE | Reduce from 4096/8192 in low-memory environments | Reduces JSON document peak, but not so small that config parsing breaks |
CONFIG_ASYNC_TCP_MAX_CONNECTIONS | Conservative for C3/C6, can increase for S3+PSRAM | Each connection consumes internal DRAM and lwIP PCB |
ARDUINO_LOOP_STACK_SIZE | Keep sufficient stack for Modbus, config save, script paths | Stack overflow manifests as Stack canary watchpoint triggered |
FASTBEE_STRIP_INFO_LOGS | Recommend 1 for production | Compile-time stripping of INFO log strings, saves Flash |
FASTBEE_DEBUG_LOG / CORE_DEBUG_LEVEL | Keep at low level for production | Debug logs increase Flash and runtime output pressure |
TCP_SND_BUF / TCP_WND (sdkconfig.defaults) | 2872 B for classic/C3/C6, 4308 B for S3 | Overrides ESP-IDF defaults (5744/5760 B); saves ~11.5 KB DRAM at 4 connections, see TCP Connection Budget |
requiresNetwork feature gating | Built-in (RuntimeFeatureManager) | Network-dependent features defer init until network ready, lowering boot DRAM peak |
Typical Configurations
ESP32-C3/C6 4MB Low-Budget Build
The release environment already disables OTA, Ethernet and cellular. If the application image approaches its limit, trim only features that the product will never use:
ini
-DFASTBEE_ENABLE_MODBUS=0
-DFASTBEE_ENABLE_OTA=0
-DFASTBEE_ENABLE_RULE_SCRIPT=0
-DFASTBEE_ENABLE_COMMAND_SCRIPT=0
-DFASTBEE_ENABLE_LCD=0
-DFASTBEE_ENABLE_NEOPIXEL=0
-DFASTBEE_ENABLE_I2C_SENSORS=0
-DFASTBEE_STRIP_INFO_LOGS=1
-DFASTBEE_LOG_BUFFER_SIZE=128ESP32 4MB Low-Budget Build
Target WiFi + MQTT + Modbus + basic peripherals. The environment already disables 4G, Ethernet, BLE and OTA; if Flash is still tight, remove the GB2312 font before core field capabilities:
ini
-DFASTBEE_ENABLE_OTA=0
-DFASTBEE_ENABLE_ETHERNET=0
-DFASTBEE_ENABLE_CELLULAR=0
-DFASTBEE_ENABLE_LCD_GB2312=0ESP32-S3/ESP32 with PSRAM
PSRAM environments have more headroom for MQTTS, larger displays and more rules, but MQTTS still depends on sufficient internal DRAM. Keep Ethernet, cellular and other unused hardware features disabled in Feature Config.
ini
-DFASTBEE_USE_PSRAM=1
-DBOARD_HAS_PSRAM
-DFASTBEE_ENABLE_BLE=0Resource Limit Reference
| Parameter | ESP32-C3 | ESP32-C6 | ESP32 | ESP32-S3 |
|---|---|---|---|---|
| Max Peripherals | 16 | 24 | 24 | 32 |
| Max Execution Rules | 12 | 24 | 16 | 32 |
| Sensor Cache Entries | 16 | 24 | 24 | 32 |
| TCP Concurrent Budget | 4 | 6 | 6 | 8 |
| SSE Connection Budget | 1 | 1 | 1 | 2 |
| HTTP Connection Budget | 3 | 5 | 5 | 6 |
| TCP Exhaustion Threshold | 10 | 12 | 12 | 14 |
Configuration Checklist
- Confirm which peripheral modules are actually connected to the hardware.
- Confirm required networking: WiFi, Ethernet or 4G.
- Confirm protocol needs: MQTT usually retained, Modbus enabled as needed (TCP/HTTP/CoAP clients removed).
- Do not enable OTA when Flash is less than 8MB.
- Only enable
FASTBEE_USE_PSRAM=1andBOARD_HAS_PSRAMon environments with actual PSRAM. - Unconnected peripherals, network modules and management features are disabled by default.
- When BLE is needed, also verify dependencies, source entry points, Web/API capabilities, provisioning workflow and resource validation; device-side defaults to WiFi AP/Web provisioning.
- After modifications, run
pio run -e <env>and check RAM/Flash usage in build output. - After flashing, check
heapFree,heapMaxAllocand PSRAM via/api/system/info, and feature state via/api/features/status.