refactor: use Fatfs python module to replace mkfatfs binary #370
Conversation
Removed the solution section explaining the esp32_wl.py module.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (6)
examples/arduino-fatfs/platformio.ini (1)
1-6: Consider adding monitor_speed configuration.The configuration is minimal and correct, but you may want to add
monitor_speed = 115200for consistent serial monitor output, as seen in the example's data directory configuration file.🔎 Suggested addition
[env:esp32dev] platform = espressif32 framework = arduino board = esp32dev board_build.filesystem = fatfs board_build.partitions = partitions.csv +monitor_speed = 115200examples/arduino-fatfs/data/README.md (1)
1-224: Consider simplifying this data directory READMEThis file is a near-duplicate of
examples/arduino-fatfs/README.mdand will be included in the FAT filesystem image flashed to the ESP32. Including ~5KB of documentation in the flashable data consumes valuable flash space unnecessarily.Consider replacing this with a minimal README (e.g., just the project name and a note to see the parent directory for full documentation), or remove it entirely if
test.txtis sufficient for testing purposes.FATFS_INTEGRATION.md (1)
70-72: Clarify package naming:fatfs-ngvspyfatfsLine 72 references
fatfs-ngas the dependency, but line 101 mentionspyfatfsfor extended features. If these are different names for the same package (e.g.,fatfs-ngis the PyPI package name andpyfatfsis the module import name), consider clarifying this relationship to avoid confusion.examples/arduino-fatfs/TEST_GUIDE.md (1)
287-314: CI script has reliability concernsThe CI script approach has a few issues:
pio run -t monitorruns indefinitely, soteewill never complete unless externally terminated- No timeout mechanism to handle test hangs
- The
sleep 2may not be sufficient for ESP32 boot on all systemsConsider using
timeoutand a more robust monitoring approach.🔎 Proposed improvement
# Wait for ESP32 to boot -sleep 2 +sleep 5 # Monitor output and check for success -pio run -t monitor | tee test_output.log +timeout 60 pio run -t monitor 2>&1 | tee test_output.log || true # Verify outputexamples/arduino-fatfs/src/ffat.ino (2)
146-156: Return value offile.read()not checkedThe return value of
file.read(buf, toRead)is not checked. While unlikely to fail mid-read, ignoring the return value means a partial read would go undetected, potentially corrupting the benchmark results.🔎 Proposed fix
size_t toRead = len; if (toRead > 512) { toRead = 512; } - file.read(buf, toRead); + size_t bytesRead = file.read(buf, toRead); + if (bytesRead != toRead) { + Serial.println("- read error"); + break; + } if ((i++ & 0x001F) == 0x001F) { Serial.print("."); } len -= toRead;
351-355: Document magic numbers for sector configurationThe values
4096and362are magic numbers representing the expected sector size and sector count. Consider adding a comment explaining these values or defining them as constants for clarity.🔎 Proposed improvement
+ // ESP32 FFat uses 4096-byte sectors + // 362 sectors = FAT data area for ~1.44MB partition with WL overhead if (bytes_per_sector == 4096 && total_sectors == 362) { Serial.println(" ✓ Correct format for ESP32 FFat!"); }
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
examples/arduino-fatfs/data/partitions.csvis excluded by!**/*.csvexamples/arduino-fatfs/partitions.csvis excluded by!**/*.csv
📒 Files selected for processing (16)
.github/workflows/examples.ymlFATFS_INTEGRATION.mdREADME.mdWEAR_LEVELING.mdbuilder/main.pybuilder/penv_setup.pyexamples/arduino-fatfs/.gitignoreexamples/arduino-fatfs/README.mdexamples/arduino-fatfs/TEST_GUIDE.mdexamples/arduino-fatfs/data/README.mdexamples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/data/test.txtexamples/arduino-fatfs/platformio.iniexamples/arduino-fatfs/src/ffat.inoplatform.jsonplatform.py
💤 Files with no reviewable changes (1)
- platform.json
🧰 Additional context used
🧠 Learnings (19)
📓 Common learnings
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 281
File: builder/frameworks/component_manager.py:1047-1054
Timestamp: 2025-09-04T15:27:18.112Z
Learning: In the pioarduino/platform-espressif32 project, Jason2866 prefers not to add guard checks for missing arduino_libs_mcu in backup operations, preferring to let the operation proceed rather than silently skip when the directory might be missing.
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 0
File: :0-0
Timestamp: 2025-12-23T17:13:00.004Z
Learning: In pioarduino/platform-espressif32 (builder/main.py), the LittleFS filesystem image builder uses parameters that intentionally differ from ESP-IDF defaults (read_size=1, prog_size=1, cache_size=block_size, lookahead_size=32, name_max=64 instead of ESP-IDF's 16, 16, 16, 16, 255 respectively). These values were determined through Arduino real-world testing and are necessary to prevent the firmware from reformatting the created filesystem image. Using ESP-IDF defaults causes reformatting issues.
📚 Learning: 2025-06-26T09:56:30.658Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 199
File: examples/arduino-blink/platformio.ini:81-83
Timestamp: 2025-06-26T09:56:30.658Z
Learning: In examples/arduino-blink/platformio.ini, the different lib_ignore configurations across environments (some including wifi, some not, different syntax styles) are intentional test cases, not inconsistencies that need to be fixed.
Applied to files:
examples/arduino-fatfs/.gitignoreexamples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/platformio.ini
📚 Learning: 2025-09-09T18:07:14.583Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 285
File: platform.py:670-683
Timestamp: 2025-09-09T18:07:14.583Z
Learning: In the pioarduino/platform-espressif32 project, when tools.json exists in mklittlefs tool directories, it triggers a reinstall via install_tool(). This is intentional behavior to convert tools installed via idf_tools.py method into the platform's tool management system, rather than a redundant check that should be avoided.
Applied to files:
platform.pyREADME.md
📚 Learning: 2025-08-10T19:13:25.599Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 255
File: builder/penv_setup.py:26-40
Timestamp: 2025-08-10T19:13:25.599Z
Learning: In the pioarduino/platform-espressif32 repository's builder/penv_setup.py file, semantic_version is imported but intentionally not listed in python_deps because it's a transitive dependency of platformio-core (version 2.10.*). When platformio is installed from the GitHub URL, semantic_version is automatically installed as one of its dependencies.
Applied to files:
builder/penv_setup.pyREADME.md
📚 Learning: 2025-12-23T17:13:00.004Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 0
File: :0-0
Timestamp: 2025-12-23T17:13:00.004Z
Learning: In pioarduino/platform-espressif32 (builder/main.py), the LittleFS filesystem image builder uses parameters that intentionally differ from ESP-IDF defaults (read_size=1, prog_size=1, cache_size=block_size, lookahead_size=32, name_max=64 instead of ESP-IDF's 16, 16, 16, 16, 255 respectively). These values were determined through Arduino real-world testing and are necessary to prevent the firmware from reformatting the created filesystem image. Using ESP-IDF defaults causes reformatting issues.
Applied to files:
WEAR_LEVELING.mdexamples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/README.mdexamples/arduino-fatfs/data/README.mdbuilder/main.pyFATFS_INTEGRATION.mdexamples/arduino-fatfs/TEST_GUIDE.mdexamples/arduino-fatfs/platformio.iniexamples/arduino-fatfs/src/ffat.inoREADME.md
📚 Learning: 2025-08-20T14:13:13.842Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 263
File: platform.py:80-84
Timestamp: 2025-08-20T14:13:13.842Z
Learning: For the pioarduino/platform-espressif32 project, Jason2866 prefers to always override IDF_TOOLS_PATH environment variable with PlatformIO's core directory, rather than respecting any existing user-defined IDF_TOOLS_PATH values. This ensures consistent ESP32 tool management within PlatformIO.
Applied to files:
examples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/platformio.iniREADME.md
📚 Learning: 2025-08-08T09:50:01.969Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 252
File: builder/frameworks/espidf.py:1382-1388
Timestamp: 2025-08-08T09:50:01.969Z
Learning: Preference in pioarduino/platform-espressif32 (builder/frameworks/espidf.py): Avoid using {"name": "boot"} as a sentinel when resolving the default app partition offset. Instead, call parttool.py with --partition-boot-default directly (and optionally fall back to factory/ota_0) to prevent confusion with non-existent CSV names.
Applied to files:
examples/arduino-fatfs/data/platformio.inibuilder/main.pyexamples/arduino-fatfs/platformio.ini
📚 Learning: 2025-08-05T11:47:41.756Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 246
File: builder/main.py:0-0
Timestamp: 2025-08-05T11:47:41.756Z
Learning: In the ESP32 platform builder, subprocess calls correctly use the virtual environment Python by explicitly passing PYTHON_EXE (which is set to the venv python path) as the first argument in the command array, rather than relying on environment variable propagation. The env=os.environ parameter only affects environment variables, not the executable path itself.
Applied to files:
examples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/platformio.ini
📚 Learning: 2025-09-23T14:15:00.476Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 0
File: :0-0
Timestamp: 2025-09-23T14:15:00.476Z
Learning: In the pioarduino/platform-espressif32 project, espidf.py creates an extra/separate virtual environment from the penv setup, so cryptography version differences between penv_setup.py and espidf.py do not cause conflicts since they operate in isolated environments.
Applied to files:
examples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/platformio.iniREADME.md
📚 Learning: 2025-08-08T09:55:50.842Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 252
File: builder/frameworks/espidf.py:1382-1388
Timestamp: 2025-08-08T09:55:50.842Z
Learning: In pioarduino/platform-espressif32 (builder/frameworks/espidf.py, Python), for get_app_partition_offset: preferred behavior is to probe app/ota_0 first, then app/factory; avoid using the {"name":"boot"} sentinel; make probes non-fatal (don’t exit on missing partitions), optionally fall back to calling parttool.py with --partition-boot-default, then default to 0x10000.
Applied to files:
examples/arduino-fatfs/data/platformio.inibuilder/main.pyexamples/arduino-fatfs/platformio.ini
📚 Learning: 2025-09-22T14:47:08.855Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 296
File: builder/main.py:49-50
Timestamp: 2025-09-22T14:47:08.855Z
Learning: For the pioarduino/platform-espressif32 project, Jason2866 prefers that critical setup operations like platform.setup_python_env should crash immediately if they fail rather than having fallback mechanisms, as this ensures problems are detected early and clearly rather than being masked.
Applied to files:
examples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/platformio.iniREADME.md
📚 Learning: 2025-10-19T17:30:42.403Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 0
File: :0-0
Timestamp: 2025-10-19T17:30:42.403Z
Learning: The tool-esp-rom-elfs package must remain in COMMON_IDF_PACKAGES in platform.py because espidf.py requires it to set the ESP_ROM_ELF_DIR environment variable for the ESP-IDF build system, independent of the exception decoder monitor filter usage.
Applied to files:
examples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/platformio.ini
📚 Learning: 2025-09-23T16:55:39.788Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 296
File: builder/penv_setup.py:612-647
Timestamp: 2025-09-23T16:55:39.788Z
Learning: In the pioarduino/platform-espressif32 project, Jason2866 prefers no fallback mechanisms in penv setup functions. The penv virtual environment setup must work properly and should crash immediately rather than falling back to host Python environments, to avoid using "unknown env" configurations.
Applied to files:
examples/arduino-fatfs/data/platformio.ini
📚 Learning: 2025-08-26T14:52:29.044Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 268
File: builder/penv_setup.py:87-96
Timestamp: 2025-08-26T14:52:29.044Z
Learning: For the pioarduino/platform-espressif32 project, Jason2866 prefers to trust system executables when falling back to PATH-based command resolution (like "uv"), rather than implementing additional validation checks for security concerns.
Applied to files:
examples/arduino-fatfs/data/platformio.iniexamples/arduino-fatfs/platformio.iniREADME.md
📚 Learning: 2025-08-08T09:44:18.366Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 252
File: builder/frameworks/espidf.py:1382-1388
Timestamp: 2025-08-08T09:44:18.366Z
Learning: In builder/frameworks/espidf.py, get_partition_info treats pt_params["name"] == "boot" as a sentinel to pass --partition-boot-default to parttool.py; "boot" is not expected to be a CSV partition name.
Applied to files:
builder/main.py
📚 Learning: 2025-08-08T10:04:46.044Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 252
File: builder/frameworks/espidf.py:1382-1388
Timestamp: 2025-08-08T10:04:46.044Z
Learning: When discussing espidf.py get_app_partition_offset behavior with Jason2866, they prefer the OTA-first then factory order and consider using the "boot" sentinel undesirable. Clarifications must be evidence-based, citing that get_partition_info calls env.Exit(1) on missing partitions, which can preempt fallbacks if used directly.
Applied to files:
builder/main.py
📚 Learning: 2025-07-13T20:03:29.695Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 225
File: builder/main.py:99-108
Timestamp: 2025-07-13T20:03:29.695Z
Learning: In the ESP32 platform builder, the subprocess call to get site-packages directory in setup_python_paths() function is intentionally left without error handling because if this basic Python operation fails, it indicates a fundamental system issue that would cause the entire build process to fail anyway.
Applied to files:
examples/arduino-fatfs/platformio.ini
📚 Learning: 2025-09-23T14:15:00.476Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 0
File: :0-0
Timestamp: 2025-09-23T14:15:00.476Z
Learning: In the pioarduino/platform-espressif32 project, espidf.py creates and manages its own separate IDF virtual environment (accessed via get_python_exe() from get_idf_venv_dir()). This IDF venv is completely isolated from the penv setup, so different cryptography versions between penv_setup.py and espidf.py don't cause conflicts as they exist in separate virtual environments.
Applied to files:
README.md
📚 Learning: 2025-09-23T12:35:35.508Z
Learnt from: Jason2866
Repo: pioarduino/platform-espressif32 PR: 0
File: :0-0
Timestamp: 2025-09-23T12:35:35.508Z
Learning: For the pioarduino/platform-espressif32 project, Jason2866 has explicitly instructed to NEVER create issues or PRs outside of his repositories (pioarduino/*). All issue and PR creation must be strictly limited to his own repositories only, never in upstream or other repositories.
Applied to files:
README.md
🧬 Code graph analysis (1)
builder/main.py (1)
platform.py (1)
wrapper(140-148)
🪛 LanguageTool
WEAR_LEVELING.md
[grammar] ~9-~9: Use a hyphen to join words.
Context: ...FAT partitions to be wrapped with a wear leveling layer: - Without WL: Raw FA...
(QB_NEW_EN_HYPHEN)
examples/arduino-fatfs/README.md
[grammar] ~50-~50: Use a hyphen to join words.
Context: ...s a FAT filesystem image with ESP32 wear leveling layer at: `.pio/build/esp32dev/...
(QB_NEW_EN_HYPHEN)
[grammar] ~112-~112: Use a hyphen to join words.
Context: ... automatically wrapped with ESP32's wear leveling layer: - Total partition: ...
(QB_NEW_EN_HYPHEN)
[grammar] ~127-~127: Ensure spelling is correct
Context: ...) for details. ## Troubleshooting ### "FFat Mount Failed" Possible causes: 1. ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
examples/arduino-fatfs/data/README.md
[grammar] ~50-~50: Use a hyphen to join words.
Context: ...s a FAT filesystem image with ESP32 wear leveling layer at: `.pio/build/esp32dev/...
(QB_NEW_EN_HYPHEN)
[grammar] ~112-~112: Use a hyphen to join words.
Context: ... automatically wrapped with ESP32's wear leveling layer: - Total partition: ...
(QB_NEW_EN_HYPHEN)
[grammar] ~127-~127: Ensure spelling is correct
Context: ...) for details. ## Troubleshooting ### "FFat Mount Failed" Possible causes: 1. ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
FATFS_INTEGRATION.md
[grammar] ~86-~86: Use a hyphen to join words.
Context: ...er ESP32's FFat library requires a wear leveling layer around the FAT filesystem...
(QB_NEW_EN_HYPHEN)
[grammar] ~87-~87: Use a hyphen to join words.
Context: ...tomatically: - Reserves sectors for wear leveling metadata - Wraps the FAT filesy...
(QB_NEW_EN_HYPHEN)
examples/arduino-fatfs/TEST_GUIDE.md
[grammar] ~160-~160: Ensure spelling is correct
Context: ...in 1234 ms ``` ## Troubleshooting ### "FFat Mount Failed" Possible causes: 1....
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~164-~164: Ensure spelling is correct
Context: ... Failed" Possible causes: 1. No FFat partition in partition table - Che...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
WEAR_LEVELING.md
15-15: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
80-80: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
98-98: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
examples/arduino-fatfs/data/README.md
21-21: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
70-70: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
119-119: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
examples/arduino-fatfs/TEST_GUIDE.md
21-21: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
70-70: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
119-119: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🪛 Ruff (0.14.10)
builder/main.py
570-570: Abstract raise to an inner function
(TRY301)
570-570: Create your own exception
(TRY002)
570-570: Avoid specifying long messages outside the exception class
(TRY003)
592-594: try-except-pass detected, consider logging the exception
(S110)
592-592: Do not catch blind exception: Exception
(BLE001)
601-602: try-except-pass detected, consider logging the exception
(S110)
601-601: Do not catch blind exception: Exception
(BLE001)
608-608: Do not catch blind exception: Exception
(BLE001)
625-625: Abstract raise to an inner function
(TRY301)
625-625: Create your own exception
(TRY002)
625-625: Avoid specifying long messages outside the exception class
(TRY003)
627-627: f-string without any placeholders
Remove extraneous f prefix
(F541)
633-633: f-string without any placeholders
Remove extraneous f prefix
(F541)
637-637: f-string without any placeholders
Remove extraneous f prefix
(F541)
662-662: Consider moving this statement to an else block
(TRY300)
664-664: Do not catch blind exception: Exception
(BLE001)
1115-1115: subprocess call: check for execution of untrusted input
(S603)
1119-1119: Do not catch blind exception: Exception
(BLE001)
1178-1178: subprocess call: check for execution of untrusted input
(S603)
1182-1182: Do not catch blind exception: Exception
(BLE001)
1191-1191: Unused function argument: target
(ARG001)
1191-1191: Unused function argument: source
(ARG001)
1206-1206: Unpacked variable fs_start is never used
Prefix it with an underscore or any other dummy variable pattern
(RUF059)
1206-1206: Unpacked variable fs_subtype is never used
Prefix it with an underscore or any other dummy variable pattern
(RUF059)
1262-1262: Consider moving this statement to an else block
(TRY300)
1264-1264: Do not catch blind exception: Exception
(BLE001)
1269-1269: Unused function argument: target
(ARG001)
1269-1269: Unused function argument: source
(ARG001)
1355-1355: Do not catch blind exception: Exception
(BLE001)
1364-1364: Consider moving this statement to an else block
(TRY300)
1366-1366: Do not catch blind exception: Exception
(BLE001)
🔇 Additional comments (17)
examples/arduino-fatfs/data/test.txt (1)
1-1: LGTM!Simple test file for demonstrating FatFS functionality in the example project.
.github/workflows/examples.yml (1)
18-18: LGTM!Correctly adds the new FatFS example to the CI matrix for testing across all platforms.
examples/arduino-fatfs/.gitignore (1)
1-5: LGTM!Standard ignore patterns for PlatformIO and VSCode IDE artifacts.
platform.py (1)
723-726: LGTM! Clean refactoring to Python-based FatFS tooling.The change correctly delegates LittleFS and FatFS handling to Python modules (littlefs-python and fatfs-ng), removing the need for the mkfatfs binary. Only SPIFFS continues to use a native tool.
builder/main.py (6)
25-25: LGTM! FatFS module import.Correctly imports necessary components from the fatfs-ng module for FatFS image creation and manipulation.
1037-1189: LGTM! Well-structured helper functions.The refactored helper functions properly separate concerns:
_get_unpack_dir: Configuration reading_prepare_unpack_dir: Directory management_download_partition_image: Common download logic with fs_type_filter parameterThis eliminates code duplication between
download_littlefsanddownload_fatfs.
512-669: LGTM! Comprehensive FatFS image builder with proper validation.The implementation correctly:
- Calculates ESP-IDF wear leveling overhead
- Creates and formats FAT filesystem with appropriate parameters (n_fat=2, n_root=512)
- Populates files and directories from source
- Validates boot sector parameters before wrapping
- Wraps with ESP-IDF wear leveling layer
The boot sector validation (lines 616-633) is particularly valuable for early error detection. The function includes detailed logging for debugging, which aids troubleshooting.
1269-1370: LGTM! Robust FatFS download with automatic WL handling.The implementation properly:
- Downloads FAT partition (subtype 0x81) from device
- Automatically detects and extracts ESP-IDF wear leveling wrapper
- Validates sector size from boot sector
- Mounts and extracts files with appropriate error handling
- Provides clear feedback including empty filesystem detection
The automatic WL detection (lines 1311-1320) is particularly useful, as it handles both WL-wrapped and raw FAT images transparently.
684-692: LGTM! Complete integration of FatFS tooling.The changes properly integrate FatFS support:
- Line 692: Disables LDF for download_fatfs target
- Lines 817-827: Routes fatfs filesystem to build_fatfs_image builder
- Lines 1617-1623: Registers download_fatfs as a platform target
This completes the FatFS toolchain alongside the existing LittleFS support.
Also applies to: 815-834, 1617-1623
1191-1267: LGTM! Refactored download_littlefs using shared helpers.The function now leverages the shared helper functions, reducing code duplication while maintaining the same functionality. The use of
_download_partition_imagewith[0x82, 0x83]filter correctly handles both SPIFFS and LittleFS partitions.examples/arduino-fatfs/data/platformio.ini (1)
1-7: File appears unnecessarily placed in data/ directory.The
platformio.inifile indata/platformio.iniis unusual. The project's own README.md documents thatplatformio.inishould be at the project root, not in thedata/directory. Additionally, thedata/directory is designated for files to be included in the FAT filesystem image (like test.txt and README.md).While the data/ version differs from the root (includes
monitor_speed), this configuration file should not reside in the filesystem content directory unless intentionally testing the ability to read configuration files from FatFS. If that's the case, it should be documented. Otherwise, this file should be removed.⛔ Skipped due to learnings
Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 199 File: examples/arduino-blink/platformio.ini:81-83 Timestamp: 2025-06-26T09:56:30.658Z Learning: In examples/arduino-blink/platformio.ini, the different lib_ignore configurations across environments (some including wifi, some not, different syntax styles) are intentional test cases, not inconsistencies that need to be fixed.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 0 File: :0-0 Timestamp: 2025-12-23T17:13:00.004Z Learning: In pioarduino/platform-espressif32 (builder/main.py), the LittleFS filesystem image builder uses parameters that intentionally differ from ESP-IDF defaults (read_size=1, prog_size=1, cache_size=block_size, lookahead_size=32, name_max=64 instead of ESP-IDF's 16, 16, 16, 16, 255 respectively). These values were determined through Arduino real-world testing and are necessary to prevent the firmware from reformatting the created filesystem image. Using ESP-IDF defaults causes reformatting issues.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 252 File: builder/frameworks/espidf.py:1382-1388 Timestamp: 2025-08-08T09:50:01.969Z Learning: Preference in pioarduino/platform-espressif32 (builder/frameworks/espidf.py): Avoid using {"name": "boot"} as a sentinel when resolving the default app partition offset. Instead, call parttool.py with --partition-boot-default directly (and optionally fall back to factory/ota_0) to prevent confusion with non-existent CSV names.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 263 File: platform.py:80-84 Timestamp: 2025-08-20T14:13:13.842Z Learning: For the pioarduino/platform-espressif32 project, Jason2866 prefers to always override IDF_TOOLS_PATH environment variable with PlatformIO's core directory, rather than respecting any existing user-defined IDF_TOOLS_PATH values. This ensures consistent ESP32 tool management within PlatformIO.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 246 File: builder/main.py:0-0 Timestamp: 2025-08-05T11:47:41.756Z Learning: In the ESP32 platform builder, subprocess calls correctly use the virtual environment Python by explicitly passing PYTHON_EXE (which is set to the venv python path) as the first argument in the command array, rather than relying on environment variable propagation. The env=os.environ parameter only affects environment variables, not the executable path itself.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 0 File: :0-0 Timestamp: 2025-09-23T14:15:00.476Z Learning: In the pioarduino/platform-espressif32 project, espidf.py creates an extra/separate virtual environment from the penv setup, so cryptography version differences between penv_setup.py and espidf.py do not cause conflicts since they operate in isolated environments.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 252 File: builder/frameworks/espidf.py:1382-1388 Timestamp: 2025-08-08T09:55:50.842Z Learning: In pioarduino/platform-espressif32 (builder/frameworks/espidf.py, Python), for get_app_partition_offset: preferred behavior is to probe app/ota_0 first, then app/factory; avoid using the {"name":"boot"} sentinel; make probes non-fatal (don’t exit on missing partitions), optionally fall back to calling parttool.py with --partition-boot-default, then default to 0x10000.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 296 File: builder/main.py:49-50 Timestamp: 2025-09-22T14:47:08.855Z Learning: For the pioarduino/platform-espressif32 project, Jason2866 prefers that critical setup operations like platform.setup_python_env should crash immediately if they fail rather than having fallback mechanisms, as this ensures problems are detected early and clearly rather than being masked.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 0 File: :0-0 Timestamp: 2025-10-19T17:30:42.403Z Learning: The tool-esp-rom-elfs package must remain in COMMON_IDF_PACKAGES in platform.py because espidf.py requires it to set the ESP_ROM_ELF_DIR environment variable for the ESP-IDF build system, independent of the exception decoder monitor filter usage.builder/penv_setup.py (1)
49-49: Fix the fatfs-ng version constraint—0.1.14 does not exist.The specified version
>=0.1.14cannot be satisfied. The latest available release of fatfs-ng on PyPI is version 0.1.7 (released Dec 26, 2025). Update the constraint to>=0.1.7or specify an appropriate available version.⛔ Skipped due to learnings
Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 255 File: builder/penv_setup.py:26-40 Timestamp: 2025-08-10T19:13:25.599Z Learning: In the pioarduino/platform-espressif32 repository's builder/penv_setup.py file, semantic_version is imported but intentionally not listed in python_deps because it's a transitive dependency of platformio-core (version 2.10.*). When platformio is installed from the GitHub URL, semantic_version is automatically installed as one of its dependencies.README.md (1)
32-61: LGTM!The new Features section is well-structured, clearly documents the FatFS integration, and provides helpful quick-start guidance with correct relative links to the integration documentation and example.
WEAR_LEVELING.md (1)
32-47: LGTM - Clear WL_State structure documentationThe WL_State structure documentation is well-formatted and provides essential technical details for understanding the wear leveling layer format.
FATFS_INTEGRATION.md (1)
1-175: LGTM - Comprehensive integration documentationThe FatFS integration documentation is well-structured, covering configuration, partition requirements, build/upload/download workflows, technical details including wear leveling, and a helpful comparison with LittleFS. The Arduino code example and troubleshooting section are valuable additions.
examples/arduino-fatfs/src/ffat.ino (1)
1-478: LGTM - Comprehensive FFat test sketchThis is a well-structured test sketch with excellent diagnostics:
- Good modular function design for directory listing, file I/O operations
- Comprehensive mount failure diagnostics including partition inspection, FAT boot sector analysis, and WL metadata verification
- Configurable test scenarios via
#defineflags- Clear serial output with status indicators
The detailed partition and filesystem debugging at lines 311-427 will be particularly valuable for users troubleshooting mount failures.
examples/arduino-fatfs/README.md (1)
209-216: Clarify the platform reference inconsistency in the example documentationThe README example (lines 209-216) shows
platform = https://github.com/Jason2866/platform-espressif32.git#fatfs_python, but the actualplatformio.iniin the same directory usesplatform = espressif32. These should match, or the README should clearly indicate this is an alternative configuration. The external fork reference differs from the standard platform used in the configuration file.⛔ Skipped due to learnings
Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 199 File: examples/arduino-blink/platformio.ini:81-83 Timestamp: 2025-06-26T09:56:30.658Z Learning: In examples/arduino-blink/platformio.ini, the different lib_ignore configurations across environments (some including wifi, some not, different syntax styles) are intentional test cases, not inconsistencies that need to be fixed.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 338 File: builder/frameworks/component_manager.py:1312-1380 Timestamp: 2025-11-14T14:46:51.257Z Learning: In the pioarduino/platform-espressif32 project, the `pioarduino-build.py` file has a fixed format that does not change, so exact string matching (e.g., `'CCFLAGS=['`) is acceptable and regex-based flexible matching is not necessary when modifying this file.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 263 File: platform.py:80-84 Timestamp: 2025-08-20T14:13:13.842Z Learning: For the pioarduino/platform-espressif32 project, Jason2866 prefers to always override IDF_TOOLS_PATH environment variable with PlatformIO's core directory, rather than respecting any existing user-defined IDF_TOOLS_PATH values. This ensures consistent ESP32 tool management within PlatformIO.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 263 File: platform.py:492-492 Timestamp: 2025-08-20T14:13:54.005Z Learning: In PlatformIO projects, `file://` is a special PlatformIO syntax for path references, not standard file URIs. The construction `f"file://{os.path.join(path, subpath)}"` is correct PlatformIO syntax and should not be replaced with pathlib.Path.as_uri().Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 296 File: builder/main.py:49-50 Timestamp: 2025-09-22T14:47:08.855Z Learning: For the pioarduino/platform-espressif32 project, Jason2866 prefers that critical setup operations like platform.setup_python_env should crash immediately if they fail rather than having fallback mechanisms, as this ensures problems are detected early and clearly rather than being masked.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 296 File: builder/penv_setup.py:612-647 Timestamp: 2025-09-23T16:55:39.788Z Learning: In the pioarduino/platform-espressif32 project, Jason2866 prefers no fallback mechanisms in penv setup functions. The penv virtual environment setup must work properly and should crash immediately rather than falling back to host Python environments, to avoid using "unknown env" configurations.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 0 File: :0-0 Timestamp: 2025-12-23T17:13:00.004Z Learning: In pioarduino/platform-espressif32 (builder/main.py), the LittleFS filesystem image builder uses parameters that intentionally differ from ESP-IDF defaults (read_size=1, prog_size=1, cache_size=block_size, lookahead_size=32, name_max=64 instead of ESP-IDF's 16, 16, 16, 16, 255 respectively). These values were determined through Arduino real-world testing and are necessary to prevent the firmware from reformatting the created filesystem image. Using ESP-IDF defaults causes reformatting issues.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 268 File: builder/penv_setup.py:87-96 Timestamp: 2025-08-26T14:52:29.044Z Learning: For the pioarduino/platform-espressif32 project, Jason2866 prefers to trust system executables when falling back to PATH-based command resolution (like "uv"), rather than implementing additional validation checks for security concerns.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 246 File: builder/main.py:0-0 Timestamp: 2025-08-05T11:47:41.756Z Learning: In the ESP32 platform builder, subprocess calls correctly use the virtual environment Python by explicitly passing PYTHON_EXE (which is set to the venv python path) as the first argument in the command array, rather than relying on environment variable propagation. The env=os.environ parameter only affects environment variables, not the executable path itself.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 252 File: builder/frameworks/espidf.py:1382-1388 Timestamp: 2025-08-08T09:50:01.969Z Learning: Preference in pioarduino/platform-espressif32 (builder/frameworks/espidf.py): Avoid using {"name": "boot"} as a sentinel when resolving the default app partition offset. Instead, call parttool.py with --partition-boot-default directly (and optionally fall back to factory/ota_0) to prevent confusion with non-existent CSV names.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 0 File: :0-0 Timestamp: 2025-09-23T12:35:35.508Z Learning: For the pioarduino/platform-espressif32 project, Jason2866 has explicitly instructed to NEVER create issues or PRs outside of his repositories (pioarduino/*). All issue and PR creation must be strictly limited to his own repositories only, never in upstream or other repositories.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 0 File: :0-0 Timestamp: 2025-09-23T12:35:35.508Z Learning: For the pioarduino/platform-espressif32 project, Jason2866 has explicitly instructed to NEVER create issues or PRs outside of his repositories (pioarduino/*). All issue and PR creation must be strictly limited to his own repositories only, never in upstream or other repositories.Learnt from: Jason2866 Repo: pioarduino/platform-espressif32 PR: 0 File: :0-0 Timestamp: 2025-09-23T14:15:00.476Z Learning: In the pioarduino/platform-espressif32 project, espidf.py creates an extra/separate virtual environment from the penv setup, so cryptography version differences between penv_setup.py and espidf.py do not cause conflicts since they operate in isolated environments.
Removed verification section including code examples for checking WL state and extracting FAT data.
Updated Python script to handle multiple downloaded FS files.
1 participant
Checklist:
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.