espressif: freeze the env-collector's libraries on the 13 boards it targets

[tyeth]

Based on wifi-ap-debug — the branch the 13 custom builds actually used (d802e5f1b, which is the 10.4.0-alpha.1-9-gd802e5f1b the bench board runs), not main.

The ESP-NOW / WiFi / BLE environmental collector ships ~20 libraries in lib/. On a board without PSRAM that is the difference between running and not.

Measured on a Feather ESP32-S3 No PSRAM (2026-09-13), with the application itself already cross-compiled to .mpy:

• BLE + ESP-NOW + softAP all come up — and then import datastore dies with MemoryError: memory allocation failed, allocating 158 bytes;
• with BLE off it reaches the eInk dashboard, and the SD mount fails for want of 832 bytes, with 15.9 KB free.

Cross-compiling the application removes the on-device compiler peak — which is what made the C6 unbootable — but not the resident bytecode. Freezing does: a frozen module executes in place from flash and never occupies heap.

What this does

Freezes 22 libraries on the 13 espressif boards this project targets. Nine were not yet in frozen/ and are added as submodules: IL0373, JD79667, MAX1704x, NTP, SCD4X, SCD30, SEN6x, PCF8523, DS1307. The other thirteen were already present.

Why the 22 lines are repeated in every board file

Not an aesthetic choice, and worth reading before tidying it away.

tools/ci_fetch_deps.py reads each board's mpconfigboard.mk line by line, looking for literal FROZEN_MPY_DIRS += $(TOP)/ prefixes, to decide which submodules to check out. It does not follow include.

I tried the DRY version first — one shared ports/espressif/envhub_frozen.mk and a single include line per board. It resolves correctly under make (the build's own FREEZE step listed all 22 directories), and then CI fails at MKMANIFEST with every frozen directory empty, because the submodules were never fetched:

FREEZE ../../frozen/Adafruit_CircuitPython_BLE ... (all 22)
MKMANIFEST ../../frozen/Adafruit_CircuitPython_BLE ... (all 22)
make: *** [../../py/circuitpy_mpconfig.mk:855: build-.../manifest.py] Error 1

So each copy of the block carries a comment explaining why it is duplicated.

Deliberately not frozen

• adafruit_pixelbuf — already a built-in C module, not a library.
• sensirion_i2c_driver / sensirion_i2c_sen5x — from a third-party circup bundle rather than a library repo, and node_sensors.py carries a minimal built-in SEN5x driver for boards without them.
• PCF85063A — no Adafruit library exists; the project drives that chip directly from its own extrtc.py, validated against real hardware. (frozen/circuitpython-pcf85063a already exists in this tree from another author; unused here.)

Size — what CI has to answer

~162 KB of frozen bytecode from 621 KB of source, uniform across all 13:

BLE	30.6 KB
HTTPServer	32.3 KB
Display_Text	19.9 KB
Bitmap_Font	11.6 KB
Register	11.1 KB
SEN6x	9.3 KB
everything else	~47 KB

Comfortable on the 8 MB and 16 MB boards. The 4 MB ones are the risk — adafruit_qtpy_esp32s3_4mbflash_2mbpsram, adafruit_feather_huzzah32, adafruit_feather_esp32s3_tft, adafruit_feather_esp32s3_reverse_tft, adafruit_feather_esp32s3_4mbflash_2mbpsram, adafruit_feather_esp32c6_4mbflash_nopsram. If one overflows, the fix is to split the list per board rather than shrink it everywhere.

Verified on hardware

Flashed to a Feather ESP32-S3 No PSRAM running this project (2026-09-13). Same board, same application, display enabled:

	before freezing	with frozen libraries
dashboard built	lite, mem 15936	lite, mem 40256
SD mount	failed — MemoryError, 832 bytes	SD mounted
fuel gauge	died in battery.py	battery source: max17048
outcome	never reached the main loop	collector running / dashboard refreshed (mem 23200)

adafruit_ble costs 5,728 bytes to import frozen, against 30.6 KB of bytecode.

Firmware size on that board: 1,884,304 -> 2,050,112 bytes used of 2,097,152 (+165,808, matching the 162 KB estimate), leaving 47,040 free. It fits, but it is the tightest of the 13 -- an 8 MB board with a 2 MB firmware partition, not one of the 4 MB boards I flagged. feather_esp32s3_4mbflash_2mbpsram has a 2816 kB partition and over 1 MB spare.

Correction to an earlier version of this description: I claimed /lib is searched before .frozen, so a stale copy in lib/ would shadow the frozen one. That is wrong. sys.path on these builds is ['', '/', '.frozen', '/lib'] -- .frozen comes first, and the measurement above was taken with lib/ still fully populated. Deleting lib/ frees flash and removes ambiguity; it is not required to get the RAM back.

🤖 Generated with Claude Code