Board Capabilities and Verification Boundaries
This page describes the interfaces and usage boundaries of the platform-improvement candidate. On 2026-10-01, the first batch of source code and targeted host tests completed partial verification; full builds, device deployment, physical behavior, and long-term operation are still governed by the corresponding candidate release reports and do not mean existing online devices have been upgraded.
Chip Support Does Not Equal Whole-Board Compatibility
Board information comes from the certified endpoint /api/boards/profiles, resource usage from /api/peripherals/resources; run /api/peripherals/preflight before adding or modifying peripherals. Preflight requires authorization and developer mode; offline comparison against another board type cannot change the real capability of the current chip.
- scope chip-policy: generic chip capability and conservative resource strategy; it cannot represent that a specific carrier board's relays, power supply, screen, or wiring have been verified.
- scope board-policy: an existing board-specific strategy; you must still verify the board revision and wiring, and it does not automatically get a physical pass conclusion.
- scope module-policy: a conservative strategy including chip limits and the module's internal Flash/PSRAM wiring; it does not mean a specific carrier board has been verified.
- hardwareVerified stays false and requiresBoardWiringVerification is true; real physical acceptance is bound to the device, board revision, wiring, firmware hash, and test records.
- Even on the same ESP32-S3, Octal PSRAM and other memory wirings have different usable GPIOs; compare with the full profile key, not just the chip name.
ESP32-C3 Candidate Policy
The 2026-10-03 successor source also adds classic ESP32 esp32-wroom (number 4) and esp32-wrover (number 5); they await centralized verification and deployment. Classic builds with PSRAM must not use GPIO16/17 as ordinary peripherals, and these pins are not released even if PSRAM initialization fails. PZ/WROOM board types are no longer applied automatically to all classic builds and must be selected explicitly; compilation rejects conflicts with PSRAM. Default GPIOs and module names cannot replace verifying the actual carrier-board wiring. References: WROOM-32 datasheet, WROVER-E/IE datasheet.
The new esp32-c3 policy keeps existing board numbers, and the new number is 3. This policy is used for the actual preflight of current C3 builds and no longer borrows the classic ESP32 pin table.
| Item | Policy and limits |
|---|---|
| GPIO11-17 | Protect common modules' Flash power and bus; forbidden from assignment to ordinary peripherals |
| GPIO2, 8, 9 | Boot strap pins; risk is shown and confirmation required — do not consider power-on safe just because the save succeeded |
| GPIO18/19 | Protect USB Serial/JTAG; treated as occupied by default preflight |
| GPIO20/21 | UART0 console pins, handled per console-occupation policy |
| ADC | This policy exposes only ADC1 on GPIO0-4; no generic reliable-collection promise is made for ADC2 on GPIO5 |
| PWM / RMT | Six PWM channels; the NeoPixel RMT TX budget is two, and RX channels are not counted as extra TX |
| UART / buses | Software resource budget of one generic UART, one shared I2C, and one application SPI; not a claim of all the chip's hardware units |
References: Espressif C3 GPIO notes, ADC one-shot sampling limits, RMT notes. Peripheral configuration still follows actual wiring; default pins are not an automatic wiring promise.
Driver-Registration Capacity and Memory
The sensor-driver registry uses a static bounded array that holds 12 registered names by default; the build parameter FASTBEE_SENSOR_DRIVER_CAPACITY can set 1-64. Aliases also occupy an entry; before shrinking the capacity, make sure it can hold the names actually compiled into that firmware.
Peripheral-type descriptions add registeredDriverCount, driverCapacity, availableDriverSlots, and registrationFailures to help spot shortages or duplicate registrations; drivers that failed registration must not be displayed as available. A registration entry is only a name, factory, and descriptor reference, not a sensor instance; compiled count, enabled count, and actually-initialized count must be understood separately.
The default four added entries cost about 48 bytes of static storage on ESP32; instances are still created on demand. Disabling a feature at runtime does not make the firmware smaller, nor does it automatically prove all instance usage is released; real RAM gains and fragmentation/peaks follow the corresponding resource reports.
The board-list endpoint reads immutable policies segment by segment with a fixed 1536-byte fragment buffer instead of constructing the whole JSON tree of all boards/pins and a full response copy at once. Response objects and the network send queue still cost extra; this is not a promise that the entire HTTP request takes only 1536 bytes. Total length is verified before sending; on allocation failure or a future policy description exceeding the buffer boundary, it returns 503 instead of truncating to a success result. The endpoint still requires login, is not cached, and keeps the original fields compatible.
The local host has tested activation flags for five policies, different fragment lengths, character escaping, over-length rejection, and 1000-re-read/early-disconnect simulation; actual peaks on no-PSRAM devices, slow connections, and concurrency still require real-device verification.
Acceptance and Upgrades
Reading Feature State and Memory Numbers Correctly
| Field/phenomenon | What it can tell you | What it cannot prove |
|---|---|---|
| compiled | The feature code is included in the current firmware | The feature already has a hardware instance, or the external module is wired |
| userEnabled | The user's saved enable intent | Dependencies, budget, and driver initialization all succeeded |
| active | The current initialization/execution admission gate allows use | All instances are running, data is valid, or objects are released after disable |
| bootEnabled / pendingRestart | Features providing this field can compare boot-time vs current selection | Features without the field support safe hot switching; a missing field must not be treated as false |
| ramB / flashKB / activeRamB | Resource estimates and summaries in metadata | Real-time memory allocation, operation peaks, or exact reclaimable bytes |
| dram8Free / dram8Largest | Internal 8-bit DRAM free amount and largest contiguous block (bytes) from the status endpoint | A single snapshot is enough to rule out leaks or cover all operation peaks |
Resource gains after disabling a feature must be measured per the actual effect path; a failed save should keep the original config. Budget rejection, initialization failure, runtime degradation, and unconfigured instances need separate diagnoses; do not mask shortages by clearing user selections.
Shared-SPI Compatibility and Exit Boundaries
Generic SPI means byte transfers per configuration; it does not mean arbitrary SPI chips already have complete drivers. Generic SPI, SDSPI, MFRC522, and spi_tft currently use the global SPI object; each module needs an independent CS and must pass the actual board's pin/resource preflight. Different pin declarations are not separate hardware buses, and legacy configs bypassing preflight may conflict. SDMMC and RGB panels cannot be inferred from SDSPI/TFT rules.
Successor candidates add conservative protection when generic SPI is removed: as long as other enabled configs still use the global SPI, the bus is not ended; when legacy configs overlap on CS, other modules' CS is not released. This protection only removes part of the early-shutdown risk; it does not mean fixed runtime leases, concurrent exit, initialization-failure cleanup, or W5500 host coordination are complete; whether the feature is in effect on a specific device follows the release report of its firmware hash.
The current planner still strictly compares SPI pin groups. Writing TFT without MISO does not justify claiming it can mix with arbitrary full-duplex SD/RFID configs; do not disable preflight or skip physical wiring to bypass warnings. Full shared-bus support still needs initialization order, disable-during-transfer, offline recovery, and no-PSRAM/S3 real-device combination acceptance.
Candidate Release Evidence
Verify in order: source implementation, host tests, target compilation, deployment write/readback, physical behavior, and long-term stability. If any step is pending, do not replace it with "supports all hardware" or "long-term stable".
Deployment reuses the project's existing scripts and keeps each device's own identity, auth, network, MQTT, user config, and historical data; do not overwrite field configs with public templates, and do not use touch-specific firmware on non-touch boards of the same capacity.
Related entries: Architecture, Resource Tuning, Peripheral Configuration, Stability Release Checklist.