Enhance Filesystem partition detection

[Jason2866]

Description:

Related issue (if applicable): fixes #

Checklist:

• The pull request is done against the latest develop branch
• Only relevant files were touched
• Only one feature/fix was added per PR, more changes are allowed when changing boards.json
• I accept the CLA

Summary by CodeRabbit

• Bug Fixes & Improvements
  • Enhanced partition detection during builds with explicit filesystem filtering and a clear preference order (LittleFS → SPIFFS → FAT) for more reliable discovery.
  • Improved validation of partition boundaries to reduce build failures and corrupted images.
  • Updated diagnostic messaging and progress feedback to make partition-related issues easier to identify and troubleshoot.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ffb6806e-224a-4db3-9dd3-9204cffa0f40

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Enhanced filesystem partition detection in builder/main.py by adding KNOWN_FS_SUBTYPES and DATA_PARTITION_TYPE, and refactoring _download_partition_image to scan partition tables, filter by subtype, prioritize LittleFS → SPIFFS → FAT, validate partition boundaries, and emit detailed diagnostics. (48 words)

Changes

Filesystem Partition Detection

Layer / File(s)	Summary
Data Shape & Constants builder/main.py	Added public constants KNOWN_FS_SUBTYPES ((0x81, 0x82, 0x83)) and DATA_PARTITION_TYPE (0x01) to express filesystem subtype filtering criteria.
Core Partition Discovery builder/main.py	Refactored _download_partition_image to initialize upload port, scan the partition table by parsing 30-byte entries (magic 0xAA 0x50), extract partition metadata (type, subtype, offset, size, label), apply priority-based filtering (LittleFS → SPIFFS → FAT) and optional fs_type_filter, validate partition boundaries against image size, and emit diagnostic messages for discovered/selected partitions.
Messaging / Diagnostics builder/main.py	Updated log messages to reflect explicit detection flow, filesystem prioritization, and boundary validation outcomes.

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• pioarduino/platform-espressif32#372: Modifies builder/main.py to add filesystem autodetection using the same partition subtypes and reworks partition scanning/extraction logic.
• pioarduino/platform-espressif32#374: Changes filesystem detection logic and subtype-based fallback order in builder/main.py.
• pioarduino/platform-espressif32#444: Adjusts partition-table parsing and LittleFS handling in builder/main.py, related to filesystem discovery changes.

Poem

🐰
I hopped through bytes and magic flair,
Found little files in tidy lair,
LittleFS first, then SPIFFS sings,
FAT rounds out the filesystem ring,
Now partitions dance — hooray, I care!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Enhance Filesystem partition detection' clearly and directly summarizes the main change - enhanced partition-detection logic with filesystem filtering in builder/main.py.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch enh_FS_part_detect

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Jason2866]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[Jason2866]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[coderabbitai]

🧹 Nitpick comments (1)

builder/main.py (1)

1206-1207: ⚡ Quick win

Constants are function-scoped, not module-level — contradicts the PR summary.

The summary lists KNOWN_FS_SUBTYPES and DATA_PARTITION_TYPE as new public module-level constants, but they are defined inside _download_partition_image so they are re-created on every call and are not reusable from other call sites. In particular, download_fs_action (Lines 1673–1679) re-hardcodes 0x81/0x82/0x83, which is exactly the duplication these constants were meant to remove.

♻️ Proposed fix: hoist to module scope and reuse

@@
 filesystem = board.get("build.filesystem", "littlefs")
+
+# Known filesystem subtypes for ESP32 data partitions:
+#   0x81 = FAT, 0x82 = SPIFFS, 0x83 = LittleFS
+# All other data subtypes (e.g. 0x00 ota, 0x01 phy, 0x02 nvs,
+# 0x03 coredump, 0x04 nvs_keys, 0x05 efuse, 0x06 undefined) must
+# be excluded so that e.g. a coredump partition is not mistakenly
+# treated as a filesystem partition.
+KNOWN_FS_SUBTYPES = (0x81, 0x82, 0x83)
+DATA_PARTITION_TYPE = 0x01

@@ def _download_partition_image(env, fs_type_filter=None):
-    # Known filesystem subtypes for ESP32 data partitions:
-    #   0x81 = FAT, 0x82 = SPIFFS, 0x83 = LittleFS
-    # All other data subtypes (e.g. 0x00 ota, 0x01 phy, 0x02 nvs,
-    # 0x03 coredump, 0x04 nvs_keys, 0x05 efuse, 0x06 undefined) must
-    # be excluded so that e.g. a coredump partition is not mistakenly
-    # treated as a filesystem partition.
-    KNOWN_FS_SUBTYPES = (0x81, 0x82, 0x83)
-    DATA_PARTITION_TYPE = 0x01
     # Ensure upload port is set

And in download_fs_action, you can then drop the magic numbers in favor of the named constants.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@builder/main.py` around lines 1206 - 1207, KNOWN_FS_SUBTYPES and
DATA_PARTITION_TYPE are currently declared inside _download_partition_image so
they are recreated per-call and not available module-wide; hoist these constants
to the module scope as public constants (retain the uppercase names
KNOWN_FS_SUBTYPES and DATA_PARTITION_TYPE) and update all call
sites—specifically remove the hardcoded 0x81/0x82/0x83 in download_fs_action and
reference KNOWN_FS_SUBTYPES instead, and use DATA_PARTITION_TYPE where
appropriate—so the values are defined once and reused across
_download_partition_image and download_fs_action.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@builder/main.py`:
- Around line 1206-1207: KNOWN_FS_SUBTYPES and DATA_PARTITION_TYPE are currently
declared inside _download_partition_image so they are recreated per-call and not
available module-wide; hoist these constants to the module scope as public
constants (retain the uppercase names KNOWN_FS_SUBTYPES and DATA_PARTITION_TYPE)
and update all call sites—specifically remove the hardcoded 0x81/0x82/0x83 in
download_fs_action and reference KNOWN_FS_SUBTYPES instead, and use
DATA_PARTITION_TYPE where appropriate—so the values are defined once and reused
across _download_partition_image and download_fs_action.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 457062e6-d93a-49a0-b88b-f3416fd73d16

📥 Commits

Reviewing files that changed from the base of the PR and between bf0f8da and abb1f3b.

📒 Files selected for processing (1)

• builder/main.py