Build Configuration

The source build entry point is platformio.ini. Release environments share [esp32_base] and [unified_flags], then override partitions, PSRAM, OTA and runtime parameters by chip.

Environment Matrix

Environment	Chip	Flash	PSRAM	Partition	OTA
esp32-F4R0	ESP32	4MB	None	partitions/4MB.csv	No
esp32-F8R0	ESP32	8MB	None	partitions/8MB.csv	Yes
esp32-F8R8	ESP32	8MB	8MB	partitions/8MB.csv	Yes
esp32c3-F4R0	ESP32-C3	4MB	None	partitions/4MB.csv	No
esp32c6-F4R0	ESP32-C6	4MB	None	partitions/4MB.csv	No
esp32c6-F8R0	ESP32-C6	8MB	None	partitions/8MB.csv	Yes
esp32s3-F8R0	ESP32-S3	8MB	None	partitions/8MB.csv	Yes
esp32s3-F8R8	ESP32-S3	8MB	8MB	partitions/8MB.csv	Yes
esp32s3-F16R8	ESP32-S3	16MB	8MB	partitions/16MB.csv	Yes
native	Host	-	-	-	-

All nine ESP32 environments are in the release matrix. R0 means no PSRAM and R8 means 8MB PSRAM; standard names no longer use F8R4.

Configuration Layers

[esp32_base]       platform, Arduino, LittleFS, common libraries and base flags
      |
[unified_flags]    shared feature compile flags
      |
[chip runtime]     TCP limits, queues and task stacks
      |
[env:<name>]       board, partition, PSRAM, OTA and library overrides

The project uses partitions/4MB.csv, partitions/8MB.csv and partitions/16MB.csv. The spiffs label inside a CSV is the Arduino-ESP32 compatibility name for the LittleFS data partition.

Unified Feature Flags

Compiling a feature through unified_flags does not automatically activate it. RuntimeFeatureManager reads /config/features.json, applies dependencies and user switches, then FeatureBudget checks internal DRAM before initialization.

Category	Representative Flags	Runtime Default
Core Web	WEB_SERVER, WEB_STATIC, WEB_API, AUTH, SESSION	Active
Core device	MQTT, GPIO, PERIPH_EXEC, HEALTH_MONITOR, LOGGER	Compiled; used as configured
Peripherals	SENSOR_DRIVER, DS18B20, LCD, NEOPIXEL, I2C_SENSORS, RFID	Disabled until needed
Automation	RULE_SCRIPT, COMMAND_SCRIPT	Disabled; command scripts depend on RuleScript
Operations	LOG_VIEWER, FILE_LOGGING, CONFIG_TRANSFER, USER_ADMIN	Disabled or determined by build flags
Network extensions	ETHERNET, CELLULAR, BLE	Disabled; external hardware required

Environment Overrides

Override	Environment	Reason
FASTBEE_ENABLE_OTA=0, OTA_FS=0	4MB environments	Single application partition, no ota_1
FASTBEE_ENABLE_ETHERNET=0, CELLULAR=0	ESP32-F4R0 and C3/C6 release environments	Resource policy and expected hardware
FASTBEE_ENABLE_IR_REMOTE=0, RF_LEARN=0	esp32s3-F8R8	RMT/library conflict in that build
FASTBEE_ENABLE_IR_REMOTE=1, RF_LEARN=1	esp32-F8R8, esp32s3-F16R8	Dependencies and hardware resources are available

A flag change may also require a library, Web form, API handler, memory budget and partition update. Do not implement capability differences only by hiding a menu.

Runtime Resource Parameters

Flag	ESP32	C3	C6	S3
CONFIG_ASYNC_TCP_MAX_CONNECTIONS	6	4	6	8
CONFIG_ASYNC_TCP_QUEUE_SIZE	32	4	8	24
ARDUINO_LOOP_STACK_SIZE	16384	12288	12288	16384
SCRIPT_TASK_STACK	8192	6144	6144	8192
SIMPLE_TASK_STACK	6144	4096	4096	6144

Higher connection and queue limits improve concurrency but consume more internal DRAM. When requests return 503 or a feature is budget-rejected, first reduce browser concurrency and disable unused heavy features.

OTA Policy

• 4MB: OTA is not compiled and the route is not registered. Upgrade with a complete merged image over serial or the online flasher.
• 8MB/16MB: app0/app1 A/B slots are present. The image must fit the application slot and pass the runtime memory guard.
• Release scripts archive application firmware, LittleFS and merged images from the same build.

Common Commands

# Build, generate Web assets, upload LittleFS and flash firmware
powershell -ExecutionPolicy Bypass -File scripts\deploy.ps1 -Env esp32s3-F8R8 -Port COM6

# Build one environment
pio run -e esp32s3-F8R8

# Host-side unit tests
pio test -e native

# Validate environments, partitions and OTA rules
node scripts/validate-build-matrix.js

Do not use stale files in data/www as a release source. Use deploy.ps1 or gzip-www.js so the staged filesystem matches the current Web source.

Custom Environment Checklist

1. Record the exact chip, Flash, PSRAM and external modules.
2. Select the matching partitions/*.csv; OTA requires an app1 slot.
3. Set PSRAM, OTA and network-adapter flags to match the hardware.
4. Run validate-build-matrix.js, then verify firmware, LittleFS, login and /api/health on the device.
5. Record the environment name and image SHA-256 so a development image is not mistaken for a release artifact.