### Copy Example Configuration for Custom Setup

Source: https://github.com/pioarduino/platform-espressif32/blob/main/ARDUINO_RELINKER_INTEGRATION.md

Copy the pre-configured CSV files from the relinker examples directory to your project's relinker directory. This serves as a starting point for creating your custom relinker configuration.

```bash
mkdir -p relinker
cp ~/.platformio/platforms/espressif32/builder/relinker/examples/arduino/esp32c2/*.csv relinker/

```

--------------------------------

### Basic ESP-IDF ULP Project Setup

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-ulp-lp/CMakeLists.txt

This snippet initializes the CMake build system for an ESP-IDF project, includes the necessary IDF build tools, and sets the project name. It's the standard starting point for most ESP-IDF projects, including those utilizing the ULP coprocessor.

```cmake
cmake_minimum_required(VERSION 3.16)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(lp_core_pulse_counter)
```

--------------------------------

### Path Expansion Example

Source: https://github.com/pioarduino/platform-espressif32/blob/main/ARDUINO_RELINKER_INTEGRATION.md

Illustrates how the $ARDUINO_LIBS_DIR variable is expanded to the specific library path for a given chip.

```ini
~/.platformio/packages/framework-arduinoespressif32-libs/<chip>/lib/
```

```ini
/Users/username/.platformio/packages/framework-arduinoespressif32-libs/esp32c2/lib/
```

--------------------------------

### Reading Pre-Flashed Files Output

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Example output demonstrating the listing and reading of pre-flashed files from the FFat filesystem.

```text
============================================================

=== Testing Pre-Flashed Files ===

Files in root directory:
Listing directory: /
  FILE: test.txt    SIZE: 12
  FILE: README.md   SIZE: 1234
  FILE: platformio.ini    SIZE: 456
  FILE: partitions.csv    SIZE: 234

Reading test files:

--- File: /test.txt ---
Reading file: /test.txt
- read from file:
Hello World!

--- File: /README.md ---
Reading file: /README.md
- read from file:
[README content...]
```

--------------------------------

### Example Output

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-ulp/README.md

Shows the expected log messages during operation, including initialization, deep sleep entry, ULP wake-ups, and NVS updates.

```text
Not ULP wakeup, initializing ULP
Entering deep sleep

ULP wakeup, saving pulse count
Read pulse count from NVS:   384
Pulse count from ULP:     5
Wrote updated pulse count to NVS:   389
Entering deep sleep

ULP wakeup, saving pulse count
Read pulse count from NVS:   389
Pulse count from ULP:     5
Wrote updated pulse count to NVS:   394
Entering deep sleep

ULP wakeup, saving pulse count
Read pulse count from NVS:   394
Pulse count from ULP:     6
Wrote updated pulse count to NVS:   400
Entering deep sleep

ULP wakeup, saving pulse count
Read pulse count from NVS:   400
Pulse count from ULP:     5
Wrote updated pulse count to NVS:   405
Entering deep sleep
```

--------------------------------

### Copy ESP32-C2 Relinker CSV Files (POSIX)

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

Copies the example CSV configuration files for the ESP32-C2 relinker integration from the platform directory to your project's relinker directory. Ensure you have the `espressif32` platform installed.

```bash
mkdir -p relinker
cp ~/.platformio/platforms/espressif32/builder/relinker/examples/esp32c2/*.csv relinker/
```

--------------------------------

### PlatformIO Project Commands

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-peripherals-usb/README.md

Commands to navigate to an example project, build it, upload firmware, and clean build files using PlatformIO.

```shell
# Change directory to example
$ cd platform-espressif32/examples/espidf-peripherals-usb

# Build project
$ pio run

# Upload firmware
$ pio run --target upload

# Clean build files
$ pio run --target clean
```

--------------------------------

### PlatformIO Project Commands

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-blink/README.md

Commands to navigate to the example directory, build the project, upload firmware, build specific environments, and clean build files.

```shell
# Change directory to example
$ cd platform-espressif32/examples/arduino-blink

# Build project
$ pio run

# Upload firmware
$ pio run --target upload

# Build specific environment
$ pio run -e esp32dev

# Upload firmware for the specific environment
$ pio run -e esp32dev --target upload

# Clean build files
$ pio run --target clean
```

--------------------------------

### Install Espressif32 Platform Package

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-relinker/README.md

Install or update the Espressif32 platform package using PlatformIO if the build fails with 'sections.ld not found'.

```bash
pio pkg install -p espressif32
```

--------------------------------

### Output of Building FAT Image

Source: https://github.com/pioarduino/platform-espressif32/blob/main/WEAR_LEVELING.md

Example output from the PlatformIO build process, showing the steps involved in creating a wear-leveling enabled FAT image and the calculated partition sizes.

```bash
Building FS image from 'data' directory to .pio/build/esp32dev/fatfs.bin
Wrapping FAT image with ESP32 Wear Leveling layer...
  Partition size: 1507328 bytes (368 sectors)
  FAT data size: 1486848 bytes (363 sectors)
  WL overhead: 5 sectors
Successfully created wear-leveling FAT image
```

--------------------------------

### PlatformIO Project Management Commands

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-arduino-wifiscan/README.md

Use these commands to navigate to the example directory, build the project, upload firmware, build for a specific environment, upload for a specific environment, and clean build files.

```shell
# Change directory to example
$ cd platform-espressif32/examples/espidf-arduino-wifiscan

# Build project
$ pio run

# Upload firmware
$ pio run --target upload

# Build specific environment
$ pio run -e esp32dev

# Upload firmware for the specific environment
$ pio run -e esp32dev --target upload

# Clean build files
$ pio run --target clean
```

--------------------------------

### Install pioarduino CLI

Source: https://github.com/pioarduino/platform-espressif32/blob/main/README.md

Installs the pioarduino core using a Python script. Ensure Python is installed and accessible.

```bash
curl -fsSL -o get-platformio.py https://raw.githubusercontent.com/pioarduino/pioarduino-core-installer/pioarduino/get-platformio.py
python3 get-platformio.py
source ~/.platformio/penv/bin/activate
```

--------------------------------

### Copy ESP32-C2 Relinker CSV Files (Windows PowerShell)

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

Copies the example CSV configuration files for the ESP32-C2 relinker integration from the platform directory to your project's relinker directory. Ensure you have the `espressif32` platform installed.

```powershell
New-Item -ItemType Directory -Force -Path relinker
Copy-Item -Path "$env:USERPROFILE\.platformio\platforms\espressif32\builder\relinker\examples\esp32c2\*.csv" -Destination relinker\
```

--------------------------------

### Install ESP32 Exception Decoder

Source: https://github.com/pioarduino/platform-espressif32/blob/main/monitor/README_STANDALONE.md

Install the ESP32 Exception Decoder by using the pioarduino platform. This command directly uses the script for decoding.

```bash
python3 filter_exception_decoder.py <elf_file> <crash_log>
```

--------------------------------

### Example Output Log

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-ulp-riscv/README.md

Shows the expected log output when the ULP-RISC-V wakes the main CPU due to a GPIO state change.

```log
Not a ULP wakeup, initializing it!
Entering in deep sleep

...

ULP-RISC-V woke up the main CPU!
ULP-RISC-V read changes in GPIO_0 current is: High
Entering in deep sleep

```

--------------------------------

### Example library.csv Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

This CSV maps library archive names to their filesystem paths. Paths can be relative to the build directory or absolute, and `$IDF_PATH` is automatically expanded.

```csv
library,path
libble_app.a,$IDF_PATH/components/bt/controller/lib_esp32c2/esp32c2-bt-lib/libble_app.a
libpp.a,$IDF_PATH/components/esp_wifi/lib/esp32c2/libpp.a
libfreertos.a,./esp-idf/freertos/libfreertos.a
libheap.a,./esp-idf/heap/libheap.a
libnewlib.a,./esp-idf/newlib/libnewlib.a
libesp_hw_support.a,./esp-idf/esp_hw_support/libesp_hw_support.a
libesp_system.a,./esp-idf/esp_system/libesp_system.a
libesp_timer.a,./esp-idf/esp_timer/libesp_timer.a
libspi_flash.a,./esp-idf/spi_flash/libspi_flash.a
liblog.a,./esp-idf/log/liblog.a
```

--------------------------------

### PlatformIO Project Commands

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-storage-sdcard/README.md

These commands are used to manage the ESP-IDF SD card example project. They cover building, uploading firmware, cleaning build files, and targeting specific environments.

```shell
# Change directory to example
$ cd platform-espressif32/examples/espidf-storage-sdcard

# Build project
$ pio run

# Upload firmware
$ pio run --target upload

# Build specific environment
$ pio run -e esp32dev

# Upload firmware for the specific environment
$ pio run -e esp32dev --target upload

# Clean build files
$ pio run --target clean
```

--------------------------------

### Install pio arduino Homebrew Tap

Source: https://github.com/pioarduino/platform-espressif32/blob/main/Formula/README.md

Use this command to install the pio arduino Homebrew tap. This command adds the necessary repository to your Homebrew installation.

```bash
brew install pioarduino/pio arduino/pio arduino
```

--------------------------------

### library.csv Example

Source: https://github.com/pioarduino/platform-espressif32/blob/main/builder/relinker/examples/arduino/README.md

Maps library names to their filesystem paths within the Arduino framework. The $ARDUINO_LIBS_DIR variable is automatically expanded.

```csv
library,path
libfreertos.a,$ARDUINO_LIBS_DIR/libfreertos.a
libheap.a,$ARDUINO_LIBS_DIR/libheap.a
```

--------------------------------

### Custom Relinker Configuration Setup

Source: https://github.com/pioarduino/platform-espressif32/blob/main/builder/relinker/examples/arduino/README.md

Copy the default CSV configuration files to your project's relinker directory for customization. Update platformio.ini to point to the local copies.

```bash
mkdir -p relinker
cp ~/.platformio/platforms/espressif32/builder/relinker/examples/arduino/<chip>/*.csv relinker/

```

```ini
custom_relinker_library  = relinker/library.csv
custom_relinker_object   = relinker/object.csv
custom_relinker_function = relinker/function.csv
```

--------------------------------

### Write Operations Output

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Example output for testing write operations, including file creation, appending, renaming, and deletion.

```text
============================================================

=== Testing Write Operations ===

1. Creating new file...
Writing file: /test_write.txt
- file written

2. Appending to file...
Appending to file: /test_write.txt
- message appended
Appending to file: /test_write.txt
- message appended

3. Reading back written file:
Reading file: /test_write.txt
- read from file:
Hello from ESP32!
This line was appended.
And another line.

4. Testing rename...
Renaming file /test_write.txt to /renamed.txt
- file renamed
Reading file: /renamed.txt
[content...]

5. Testing delete...
Deleting file: /renamed.txt
- file deleted
File successfully deleted
```

--------------------------------

### Enable ESP32 Debug Output in Arduino Setup

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Enables verbose debug messages from the ESP32 core during the Arduino setup function. Useful for diagnosing issues.

```cpp
void setup() {
    Serial.begin(115200);
    Serial.setDebugOutput(true);  // Enable ESP32 debug output
    // ...
}
```

--------------------------------

### object.csv Example

Source: https://github.com/pioarduino/platform-espressif32/blob/main/builder/relinker/examples/arduino/README.md

Maps object files within libraries to their paths, pointing to pre-compiled objects in the Arduino framework.

```csv
library,object,path
libfreertos.a,tasks.c.obj,$ARDUINO_LIBS_DIR/libfreertos.a
libheap.a,heap_caps.c.obj,$ARDUINO_LIBS_DIR/libheap.a
```

--------------------------------

### Example object.csv Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

This CSV maps individual object files within libraries to their build artifact paths. This enables the relinker to run `objdump` on specific object files.

```csv
library,object,path
libfreertos.a,tasks.c.obj,esp-idf/freertos/CMakeFiles/__idf_freertos.dir/FreeRTOS-Kernel/tasks.c.obj
libfreertos.a,queue.c.obj,esp-idf/freertos/CMakeFiles/__idf_freertos.dir/FreeRTOS-Kernel/queue.c.obj
libfreertos.a,list.c.obj,esp-idf/freertos/CMakeFiles/__idf_freertos.dir/FreeRTOS-Kernel/list.c.obj
libfreertos.a,port.c.obj,esp-idf/freertos/CMakeFiles/__idf_freertos.dir/FreeRTOS-Kernel/portable/riscv/port.c.obj
libheap.a,heap_caps.c.obj,esp-idf/heap/CMakeFiles/__idf_heap.dir/heap_caps.c.obj
libnewlib.a,locks.c.obj,esp-idf/newlib/CMakeFiles/__idf_newlib.dir/locks.c.obj
libnewlib.a,heap.c.obj,esp-idf/newlib/CMakeFiles/__idf_newlib.dir/heap.c.obj
libesp_system.a,cpu_start.c.obj,esp-idf/esp_system/CMakeFiles/__idf_esp_system.dir/port/cpu_start.c.obj
```

--------------------------------

### Successful FFat Mount Output

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Example output indicating a successful mount of the FFat filesystem. Shows total, used, and free space.

```text
============================================================
ESP32 FFat Filesystem Test
Testing pre-flashed image with Wear Leveling
============================================================

Mounting FFat filesystem...
✓ FFat mounted successfully!

=== Filesystem Information ===
Total space:    1486848 bytes (1.42 MB)
Used space:       12288 bytes (0.01 MB)
Free space:     1474560 bytes (1.41 MB)
Usage:       0.8%
```

--------------------------------

### function.csv Example

Source: https://github.com/pioarduino/platform-espressif32/blob/main/builder/relinker/examples/arduino/README.md

Lists functions to be relocated from IRAM to Flash. The 'option' column can be used to disable relocation (e.g., with 'FALSE').

```csv
library,object,function,option
libfreertos.a,tasks.c.obj,xTaskGetCurrentTaskHandle,
libheap.a,heap_caps.c.obj,heap_caps_malloc,
```

--------------------------------

### Quick Start Relinker Configuration in platformio.ini

Source: https://github.com/pioarduino/platform-espressif32/blob/main/builder/relinker/examples/arduino/README.md

Add these lines to your platformio.ini to enable relinker configuration for the Arduino framework. Replace 'esp32c2' with your specific chip variant.

```ini
[env:myboard]
platform = espressif32
board = esp32-c2-devkitm-1
framework = arduino

; Relinker configuration
custom_relinker_library  = ${platformio.platforms_dir}/espressif32/builder/relinker/examples/arduino/esp32c2/library.csv
custom_relinker_object   = ${platformio.platforms_dir}/espressif32/builder/relinker/examples/arduino/esp32c2/object.csv
custom_relinker_function = ${platformio.platforms_dir}/espressif32/builder/relinker/examples/arduino/esp32c2/function.csv
```

--------------------------------

### Output of Downloading and Extracting FAT Image

Source: https://github.com/pioarduino/platform-espressif32/blob/main/WEAR_LEVELING.md

Example output when downloading a wear-leveling enabled FAT image, indicating detection of the WL layer, extraction of FAT data, and the files extracted.

```bash
Detected Wear Leveling layer, extracting FAT data...
  Extracted FAT data: 1486848 bytes
Extracting files:
  FILE: /test.txt (12 bytes)
Successfully extracted 1 file(s) to unpacked_fs
```

--------------------------------

### ULP RISC-V Component Setup

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-ulp-riscv/main/CMakeLists.txt

Configures a component to use ULP RISC-V, specifying the ULP application name, source files, and dependencies for embedding the ULP binary.

```cmake
# ULP support additions to component CMakeLists.txt.
#
# 1. The ULP app name must be unique (if multiple components use ULP).
set(ulp_app_name ulp_${COMPONENT_NAME})
#
# 2. Specify all C and Assembly source files.
#    Files should be placed into a separate directory (in this case, ulp/),
#    which should not be added to COMPONENT_SRCS.
set(ulp_riscv_sources "../ulp/main.c")

#
# 3. List all the component source files which include automatically
#    generated ULP export file, ${ulp_app_name}.h:
set(ulp_exp_dep_srcs "ulp_riscv_example_main.c")

#
# 4. Call function to build ULP binary and embed in project using the argument
#    values above.
ulp_embed_binary(${ulp_app_name} "${ulp_riscv_sources}" "${ulp_exp_dep_srcs}")
```

--------------------------------

### Local Relinker Configuration Setup

Source: https://github.com/pioarduino/platform-espressif32/blob/main/builder/relinker/examples/esp32s2/README.md

Alternatively, copy the relinker CSV files to a local 'relinker' directory in your project and reference them directly in platformio.ini. This approach is useful for custom projects or when modifying the relinker files.

```bash
mkdir -p relinker
cp ~/.platformio/platforms/espressif32/builder/relinker/examples/esp32s2/*.csv relinker/
```

```ini
custom_relinker_library  = relinker/library.csv
custom_relinker_object   = relinker/object.csv
custom_relinker_function = relinker/function.csv
```

--------------------------------

### Full ESP32-C2 Relinker Configuration in platformio.ini

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

Example configuration in platformio.ini to use the full Espressif-validated relinker configuration files for the ESP32-C2. This sets custom relinker paths for library, object, and function CSV files.

```ini
[env:esp32c2]
platform    = espressif32
board       = esp32-c2-devkitm-1
framework   = espidf

; Use the full Espressif-validated relinker configuration
custom_relinker_library  = ${platformio.platforms_dir}/espressif32/builder/relinker/examples/esp32c2/library.csv
custom_relinker_object   = ${platformio.platforms_dir}/espressif32/builder/relinker/examples/esp32c2/object.csv
custom_relinker_function = ${platformio.platforms_dir}/espressif32/builder/relinker/examples/esp32c2/function.csv
```

--------------------------------

### function.csv Example with Options

Source: https://github.com/pioarduino/platform-espressif32/blob/main/ARDUINO_RELINKER_INTEGRATION.md

Defines functions to be moved from IRAM to Flash. The 'option' column can be empty for unconditional moves, specify configuration conditions (e.g., CONFIG_XYZ), or prevent moving with 'FALSE'.

```csv
library,object,function,option
libfreertos.a,tasks.c.obj,xTaskGetCurrentTaskHandle,
libfreertos.a,tasks.c.obj,xTaskGetSchedulerState,
libheap.a,heap_caps.c.obj,heap_caps_malloc,

```

--------------------------------

### Scenario 1: Fresh Filesystem Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Configure tests to create a new filesystem from scratch. Ensures all filesystem operations are tested on a clean slate.

```cpp
#define FORMAT_FFAT true
#define TEST_READ_EXISTING false
#define TEST_WRITE_NEW true
#define TEST_FILE_IO true
```

--------------------------------

### Scenario 2: Pre-Flashed Image Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Configure tests to use a pre-flashed filesystem image. Allows testing of reading existing files and writing new ones.

```cpp
#define FORMAT_FFAT false
#define TEST_READ_EXISTING true
#define TEST_WRITE_NEW true
#define TEST_FILE_IO true
```

--------------------------------

### Initialize pioarduino Project

Source: https://github.com/pioarduino/platform-espressif32/blob/main/README.md

Creates a new project directory and initializes it with a specific ESP32 development board configuration.

```bash
mkdir my-project && cd my-project
pio project init --board esp32dev
```

--------------------------------

### Minimal relinker/function.csv Example

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

A minimal example of the function.csv file used by the relinker. It specifies libraries, object files, and functions to be relocated, along with an option to force placement in flash.

```csv
library,object,function,option
libfreertos.a,tasks.c.obj,xTaskGetCurrentTaskHandle,CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH
libfreertos.a,tasks.c.obj,xTaskGetSchedulerState,CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH
libfreertos.a,tasks.c.obj,xTaskGetTickCount,CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH
libfreertos.a,queue.c.obj,xQueueReceive,
libfreertos.a,queue.c.obj,xQueueGiveFromISR,
libheap.a,heap_caps.c.obj,heap_caps_malloc,
libheap.a,heap_caps.c.obj,heap_caps_free,
libnewlib.a,heap.c.obj,malloc,
libnewlib.a,heap.c.obj,free,
liblog.a,log.c.obj,esp_log_write,
```

--------------------------------

### Build FatFS Image with PlatformIO

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/FATFS_INTEGRATION.md

Prepare files in the 'data/' directory and use the 'pio run -t buildfs' command to create the FatFS filesystem image.

```bash
# Place files in data/ directory
mkdir -p data
echo "Hello FatFS" > data/test.txt

# Build image
pio run -t buildfs

```

--------------------------------

### Performance Test Output

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Example output for the file I/O performance test, showing write and read speeds.

```text
============================================================

Testing file I/O with /benchmark.bin
- writing................................
 - 1048576 bytes written in 2345 ms
- reading................................
 - 1048576 bytes read in 1234 ms
```

--------------------------------

### Build Firmware with PlatformIO

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/README.md

Use this command to build the main firmware for the ESP32 project.

```bash
pio run
```

--------------------------------

### Upload Project to Board

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-relinker/README.md

Upload the built project to the ESP32-C2 development board using PlatformIO.

```bash
pio run -e esp32-c2-devkitm-1 -t upload
```

--------------------------------

### Build FAT Filesystem Image

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/README.md

Builds a FAT filesystem image with ESP32 wear leveling support. Ensure files are placed in the `data/` directory before running.

```bash
pio run -t buildfs
```

--------------------------------

### ESP-IDF Project Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-blink/CMakeLists.txt

Sets the minimum CMake version and includes the ESP-IDF project setup script. Defines the project name.

```cmake
cmake_minimum_required(VERSION 3.16.0)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(espidf-blink)
```

--------------------------------

### Upload Firmware and Filesystem

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/README.md

Commands to upload the compiled firmware and the generated filesystem to the ESP32 device.

```bash
# Upload firmware
pio run -t upload

# Upload filesystem
pio run -t uploadfs
```

--------------------------------

### Arduino FatFS Initialization and File Operations

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/FATFS_INTEGRATION.md

Initialize the FFat library, mount the filesystem, and perform basic file read/write operations in your Arduino sketch.

```cpp
#include <FFat.h>

void setup() {
    Serial.begin(115200);
    
    // Mount FatFS
    if (!FFat.begin(true)) {
        Serial.println("FFat Mount Failed");
        return;
    }
    
    // Read file
    File file = FFat.open("/test.txt", "r");
    if (file) {
        Serial.println(file.readString());
        file.close();
    }
    
    // Write file
    file = FFat.open("/output.txt", "w");
    if (file) {
        file.println("Hello from ESP32!");
        file.close();
    }
}

void loop() {
    // ...
}

```

--------------------------------

### Monitor Serial Output

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-relinker/README.md

Monitor the serial output from the ESP32-C2 board after uploading the project to observe the relinker example's behavior and output.

```bash
pio device monitor -e esp32-c2-devkitm-1
```

--------------------------------

### Build Project with Relinker

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-relinker/README.md

Build the project using PlatformIO, enabling the relinker integration for ESP32-C2. Observe the build output indicating relinker configuration.

```bash
pio run -e esp32-c2-devkitm-1
```

--------------------------------

### Project Configuration CMakeLists.txt

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-arduino-littlefs/CMakeLists.txt

Sets up the minimum CMake version, includes the ESP-IDF project module, and defines the project name.

```cmake
cmake_minimum_required(VERSION 3.16.0)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(espidf-arduino-littlefs)
```

--------------------------------

### SPIFFS Filesystem Operations in Arduino

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-spiffs/README.md

This Arduino sketch demonstrates mounting the SPIFFS filesystem, listing its contents, reading a file, and writing a new file. Ensure SPIFFS is enabled in `platformio.ini` and the partition table is correctly configured.

```cpp
#include "FS.h"
#include "SPIFFS.h"

void setup() {
    Serial.begin(115200);
    
    // Mount SPIFFS filesystem
    if (!SPIFFS.begin(false)) {
        Serial.println("SPIFFS Mount Failed");
        return;
    }
    
    // List files
    File root = SPIFFS.open("/");
    File file = root.openNextFile();
    while (file) {
        Serial.printf("File: %s, Size: %d\n", 
                     file.name(), file.size());
        file = root.openNextFile();
    }
    
    // Read file
    File f = SPIFFS.open("/test.txt", "r");
    if (f) {
        String content = f.readString();
        Serial.println(content);
        f.close();
    }
    
    // Write file
    f = SPIFFS.open("/output.txt", "w");
    if (f) {
        f.println("Hello from ESP32!");
        f.close();
    }
}

void loop() {
    // Your code here
}
```

--------------------------------

### PlatformIO Configuration for FAT Filesystem

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/README.md

This PlatformIO configuration snippet sets up the ESP32 development environment to use the FAT filesystem, specifying the board, framework, partition table, and filesystem type.

```ini
[env:esp32dev]
platform = espressif32
framework = arduino
board = esp32dev
board_build.filesystem = fatfs
board_build.partitions = partitions.csv

```

--------------------------------

### Python Unit Test Structure

Source: https://github.com/pioarduino/platform-espressif32/blob/main/test/TESTING.md

A standard Python unittest class demonstrating setup, teardown, and a basic test method. Ensure tests are isolated and clean up resources.

```python
import unittest
import tempfile
import os

class TestNewFeature(unittest.TestCase):
    """Test description."""
    
    def setUp(self):
        """Set up test fixtures."""
        self.temp_dir = tempfile.mkdtemp(prefix="relinker_test_")
    
    def tearDown(self):
        """Clean up after tests."""
        import shutil
        shutil.rmtree(self.temp_dir)
    
    def test_feature(self):
        """Test specific feature."""
        # Arrange
        expected = "value"
        
        # Act
        result = function_under_test()
        
        # Assert
        self.assertEqual(result, expected)
```

--------------------------------

### Configure FatFS Filesystem

Source: https://github.com/pioarduino/platform-espressif32/blob/main/README.md

Sets the project to use the FatFS filesystem. This configuration should be placed in the project's `platformio.ini` file.

```ini
[env:myenv]
board_build.filesystem = fatfs
```

--------------------------------

### object.csv Example

Source: https://github.com/pioarduino/platform-espressif32/blob/main/ARDUINO_RELINKER_INTEGRATION.md

Specifies object files within libraries. For Arduino, all paths in this file point to the .a archive file, as object files are contained within the archive.

```csv
library,object,path
libfreertos.a,tasks.c.obj,$ARDUINO_LIBS_DIR/libfreertos.a
libheap.a,heap_caps.c.obj,$ARDUINO_LIBS_DIR/libheap.a

```

--------------------------------

### Scenario 3: Read-Only Filesystem Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Configure tests for a read-only filesystem scenario. Only existing files can be read, and no modifications are allowed.

```cpp
#define FORMAT_FFAT false
#define TEST_READ_EXISTING true
#define TEST_WRITE_NEW false
#define TEST_FILE_IO false
```

--------------------------------

### Basic Component Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-ulp-riscv/main/CMakeLists.txt

Sets the source files, include directories, and required components for a standard ESP-IDF component.

```cmake
set(COMPONENT_SRCS "ulp_riscv_example_main.c")
set(COMPONENT_ADD_INCLUDEDIRS "")
set(COMPONENT_REQUIRES soc nvs_flash ulp driver)

register_component()
```

--------------------------------

### FatFS Build and Upload Commands

Source: https://github.com/pioarduino/platform-espressif32/blob/main/README.md

Commands to build the FatFS image for the project and upload it to the device.

```bash
pio run -t buildfs        # Build FatFS image
pio run -t uploadfs       # Upload FatFS image
pio run -t download_fatfs # Download and extract FatFS from device
```

--------------------------------

### ESP32 FAT Filesystem Arduino Sketch

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/README.md

This Arduino sketch demonstrates mounting the FFat filesystem, listing files, reading from a file, and writing to a new file. Ensure the FFat library is included and the filesystem is correctly mounted.

```cpp
#include "FFat.h"

void setup() {
    Serial.begin(115200);
    
    // Mount FAT filesystem
    if (!FFat.begin(false)) {
        Serial.println("FFat Mount Failed");
        return;
    }
    
    // List files
    File root = FFat.open("/");
    File file = root.openNextFile();
    while (file) {
        Serial.printf("File: %s, Size: %d\n", 
                     file.name(), file.size());
        file = root.openNextFile();
    }
    
    // Read file
    File f = FFat.open("/test.txt", "r");
    if (f) {
        String content = f.readString();
        Serial.println(content);
        f.close();
    }
    
    // Write file
    f = FFat.open("/output.txt", "w");
    if (f) {
        f.println("Hello from ESP32!");
        f.close();
    }
}

void loop() {
    // Your code here
}

```

--------------------------------

### Build Project with Relinker

Source: https://github.com/pioarduino/platform-espressif32/blob/main/ARDUINO_RELINKER_INTEGRATION.md

Execute the PlatformIO run command to build your project with the configured relinker settings. The build process will indicate when the Arduino relinker is being configured and running.

```bash
pio run -e myboard

```

--------------------------------

### Build Project with Custom Relinker Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

Execute this command to build your project after configuring custom relinker settings. The relinker will optimize IRAM usage.

```bash
pio run -e esp32c2
```

--------------------------------

### ESP-IDF Arduino Project Configuration

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-arduino-blink/CMakeLists.txt

Sets the minimum CMake version and includes the ESP-IDF project CMake script. This is a standard starting point for ESP-IDF projects using the Arduino framework.

```cmake
cmake_minimum_required(VERSION 3.16.0)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(espidf-arduino-blink)
```

--------------------------------

### Troubleshooting: Verify Library Path

Source: https://github.com/pioarduino/platform-espressif32/blob/main/builder/relinker/examples/arduino/README.md

If you encounter a 'Library not found' build error, verify the library path by listing the contents of the expected directory.

```bash
ls ~/.platformio/packages/framework-arduinoespressif32-libs/esp32c2/lib/
```

--------------------------------

### Decode Crash Log with Output File (Example 2)

Source: https://github.com/pioarduino/platform-espressif32/blob/main/monitor/README_STANDALONE.md

Decode a crash log using a specific ELF file path within the PlatformIO build directory and save the decoded output to a file.

```bash
python3 filter_exception_decoder.py \
  .pio/build/esp32c6/firmware.elf \
  crash_log.txt \
  -o decoded_crash.txt
```

--------------------------------

### LP Core Log Output

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-ulp-lp/README.md

This is the expected log output from the serial monitor connected to the LP core. It shows the pulse counter starting and reporting the number of pulses detected before waking up the main CPU.

```bash
LP Core pulse counter started
Pulse count: 10, wake-up main CPU
```

--------------------------------

### Add Files and Rebuild Filesystem

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/README.md

Steps to resolve issues where files are not appearing on the filesystem. This involves adding files to the `data/` directory, rebuilding the filesystem, and uploading it again.

```bash
1. Add files to data/ directory
2. Rebuild filesystem: pio run -t buildfs
3. Upload: pio run -t uploadfs
```

--------------------------------

### Continuous Integration Script for FATFS Testing

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Automates the build, upload, and monitoring process for FATFS tests using PlatformIO. Verifies test results by checking monitor output.

```bash
#!/bin/bash
# test_fatfs.sh

# Build and upload
pio run -t buildfs
pio run -t upload
pio run -t uploadfs

# Wait for ESP32 to boot
sleep 2

# Monitor output and check for success
pio run -t monitor | tee test_output.log

# Verify output
if grep -q "✓ All tests completed!" test_output.log; then
    echo "Tests PASSED"
    exit 0
else
    echo "Tests FAILED"
    exit 1
fi
```

--------------------------------

### PlatformIO Configuration for Relinker

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

Configures the PlatformIO build environment to use the Relinker tool by specifying the paths to the library, object, and function CSV configuration files. This setup is essential for enabling the relinker's memory optimization.

```ini
[env:esp32c2]
platform  = espressif32
board     = esp32-c2-devkitm-1
framework = espidf

; --- Relinker Configuration ---
custom_relinker_library  = relinker/library.csv
custom_relinker_object   = relinker/object.csv
custom_relinker_function = relinker/function.csv

; Optional: Enable warning-only mode for missing functions
; custom_relinker_missing_function_info = yes
```

--------------------------------

### Upload FatFS Image with PlatformIO

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/FATFS_INTEGRATION.md

Use the 'pio run -t uploadfs' command to upload the pre-built FatFS image to the device.

```bash
pio run -t uploadfs

```

--------------------------------

### PlatformIO Project Commands

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-coap-server/README.md

Commands for building, uploading, and cleaning PlatformIO projects, including specific environments.

```shell
cd platform-espressif32/examples/espidf-coap-server

# Build project
pio run

# Upload firmware
pio run --target upload

# Build specific environment
pio run -e esp32dev

# Upload firmware for the specific environment
pio run -e esp32dev --target upload

# Clean build files
pio run --target clean
```

--------------------------------

### Compare Original and Downloaded Files

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/TEST_GUIDE.md

Compares original files in the data/ directory with the downloaded filesystem files. Useful for verifying changes after tests.

```bash
# Compare original files
diff data/test.txt unpacked_fs/test.txt

# Check for new files created by tests
ls -la unpacked_fs/
```

--------------------------------

### PlatformIO Configuration for ESP32 Boards

Source: https://github.com/pioarduino/platform-espressif32/blob/main/README.md

Use these configurations to set up PlatformIO for ESP32-C2, ESP32-C61, and ESP32-solo1 boards with the Arduino framework. Ensure the platform URL points to the correct release.

```ini
[env:esp32-c2-devkitm-1]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
framework = arduino
board = esp32-c2-devkitm-1
monitor_speed = 115200

[env:esp32-c61-devkitc1-n8r2]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
framework = arduino
board = esp32-c61-devkitc1-n8r2
monitor_speed = 115200

[env:esp32solo1]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
framework = arduino
board = esp32-solo1
monitor_speed = 115200

```

--------------------------------

### Download and Extract FatFS Image from Device

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/FATFS_INTEGRATION.md

Execute 'pio run -t download_fatfs' to download the FatFS partition from the device and extract its contents.

```bash
pio run -t download_fatfs

```

--------------------------------

### PlatformIO Build and Upload Commands

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-http-request/README.md

Use these commands to manage the build and upload process for your ESP-IDF project. Commands cover building, uploading, cleaning, and targeting specific environments.

```shell
# Change directory to example
$ cd platform-espressif32/examples/espidf-http-request

# Build project
$ pio run

# Upload firmware
$ pio run --target upload

# Build specific environment
$ pio run -e quantum

# Upload firmware for the specific environment
$ pio run -e quantum --target upload

# Clean build files
$ pio run --target clean
```

--------------------------------

### Running Unit and Integration Tests

Source: https://github.com/pioarduino/platform-espressif32/blob/main/test/VALIDATION_REPORT.md

Command to execute all unit and integration tests by navigating to the test directory and running the main test runner script.

```bash
# Run all unit and integration tests
cd test
python3 run_tests.py
```

--------------------------------

### PlatformIO Configuration for FatFS

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/FATFS_INTEGRATION.md

Configure your platformio.ini file to use FatFS as the board's filesystem. Specify the unpack directory if needed.

```ini
[env:myenv]
platform = espressif32
board = esp32dev
framework = arduino

; Select FatFS as filesystem
board_build.filesystem = fatfs

; Optional: Directory for extracted files (default: unpacked_fs)
board_build.unpack_dir = unpacked_fs

```

--------------------------------

### Clean and Rebuild Project

Source: https://github.com/pioarduino/platform-espressif32/blob/main/RELINKER_INTEGRATION.md

Commands to clean the project and then perform a full rebuild. This is useful for resolving build issues, especially when relinker paths are incorrect.

```bash
pio run -e esp32c2 -t clean
pio run -e esp32c2
```

--------------------------------

### Run Configuration Tests

Source: https://github.com/pioarduino/platform-espressif32/blob/main/test/README.md

Execute only the unit tests for the configuration module.

```bash
cd test
python3 -m unittest test_configuration
```

--------------------------------

### Configure ESP-IDF Arduino WiFi Scan Project

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/espidf-arduino-wifiscan/CMakeLists.txt

Sets up the build environment for an ESP-IDF project using Arduino framework for WiFi scanning. Ensure IDF_PATH environment variable is set correctly.

```cmake
cmake_minimum_required(VERSION 3.16.0)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(espidf-arduino-wifiscan)
```

--------------------------------

### Rebuild and Upload Filesystem

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/README.md

Commands to resolve 'FFat Mount Failed' errors by rebuilding the filesystem and uploading it again. This is useful if the filesystem is not uploaded or is corrupted.

```bash
# Rebuild and upload filesystem
pio run -t buildfs
pio run -t uploadfs
```

--------------------------------

### Troubleshooting Build Errors with PlatformIO

Source: https://github.com/pioarduino/platform-espressif32/blob/main/examples/arduino-fatfs/FATFS_INTEGRATION.md

If build errors occur, try recreating the PlatformIO Python environment by removing the existing one and running 'pio run' again.

```bash
# Recreate Python environment
rm -rf ~/.platformio/penv
pio run

```