How to Move an ESP32 Arduino Prototype to PlatformIO Without Rewriting Everything

The first decision: toolchain migration or framework migration?

PlatformIO is a development environment and build system. On its Espressif 32 platform, a project can use the Arduino framework or the Espressif IoT Development Framework. That means moving an Arduino sketch into PlatformIO does not automatically require rewriting the application in ESP-IDF.

For a working prototype, the lowest-risk sequence is usually:

1. Move the current Arduino behavior into a reproducible PlatformIO project.
2. Make board, library, partition and build settings explicit.
3. Verify the same normal and failure paths on the same hardware.
4. Refactor only the parts that block reliability, testing or production.
5. Choose a broader ESP-IDF migration only when the product requirements justify it.

Before touching the project structure, freeze a baseline

Record what “working” means. A successful compile is not a baseline. Capture the board and module, pin map, flash and partition assumptions, power source, peripherals, library versions, expected serial output and one repeatable check for every critical path.

If no one can reproduce the current build on a clean machine, fix that before changing architecture.

Inventory hidden Arduino IDE assumptions

Arduino IDE projects often depend on state that is not obvious from the sketch itself. List the selected board, board-menu options, library sources and versions, locally modified libraries, additional source files, filesystem upload process, partition table, compiler defines and any secrets stored outside version control.

Also separate four kinds of dependency:

• Framework APIs: functions such as setup, loop and familiar Arduino libraries.
• Board support: pin aliases, flash layout and upload settings.
• External libraries: registry, Git or local sources with version constraints.
• Product configuration: network endpoints, credentials, calibration and feature flags.

Create the PlatformIO project without refactoring behavior

Choose the exact PlatformIO board definition or define the board settings you actually require. Start with the Arduino framework if the existing product uses Arduino. Move the application into the project source directory, add dependencies explicitly, and reproduce the existing monitor, upload and build settings in platformio.ini.

Do not combine this step with renaming every file, replacing every library and redesigning the application. When multiple variables change together, a passing or failing result tells you very little.

Make dependencies and environments explicit

Pin dependencies to reviewed versions where practical. Create separate environments only when they represent a real difference such as target board, release channel or test configuration. Avoid one large configuration full of undocumented flags.

Keep secrets out of the repository. Define how local development, automated builds and production provisioning receive configuration. Treat partition tables and filesystem contents as versioned release inputs rather than manual IDE settings.

Verify the edges that migrations expose

A toolchain change can reveal timing, initialization-order and dependency assumptions that the original environment happened to tolerate. Exercise the project repeatedly and deliberately:

• Cold boot, warm reset and rapid repeated resets.
• Network unavailable at boot, dropped during operation and restored later.
• Peripheral absent, returning invalid data or responding slowly.
• Configuration missing, corrupted or from an older release.
• Flash near the expected capacity and heap under the expected workload.
• Programming and serial access on the intended production hardware.

Record the test condition and firmware identifier with every result. “It worked once” is not a production handover.

Refactor after parity, not before

Once the migrated project matches the baseline, split hardware drivers, connectivity, configuration, product state and application rules into reviewable modules. Add logging around state transitions and faults. Replace hidden delays or retry loops with explicit timing and recovery rules.

This is also the point to add automated host-side tests where possible and repeatable target-hardware checks where hardware behavior matters.

When should the product move to ESP-IDF?

ESP-IDF organizes applications from components and provides explicit project configuration, build, bootloader and partition outputs. A move can be worthwhile when the product needs tighter control over system behavior, supported ESP-IDF capabilities, a component architecture, deeper diagnostics or a release process that the current Arduino structure cannot support cleanly.

But framework migration is not a quality badge. A poorly scoped ESP-IDF rewrite can introduce more risk than a disciplined Arduino-based product. Decide from requirements, dependencies and lifecycle ownership.

Production handover checklist

• Repository and dependency sources are accessible to the owner.
• A clean environment can reproduce the release.
• Board, partition, configuration and provisioning inputs are versioned.
• The approved firmware is identifiable on the device.
• Programming and manufacturing-test steps are written down.
• Normal, failure and recovery checks have recorded results.
• Known limitations and deferred risks are visible.
• Source, binary and support responsibilities match the commercial agreement.

What comes after a reproducible firmware build?

A controlled toolchain migration is one part of product readiness. Use the ESP32 product development guide to plan hardware validation, provisioning, update recovery and release acceptance. If the build is reproducible but the next production decision is unclear, the ESP32 production-readiness review defines the evidence to inspect before committing to a wider development scope.