A recurring question on this forum is, “How can I convert my Arduino program to PlatformIO?”
To help with this, I’ve created a detailed guide on converting (multi file) Arduino projects to PlatformIO. Even better, I’ve developed a program that can handle the conversion for you!
In the guide, I explain the steps the program takes and walk you through the entire process. The conversion program simplifies the transition by automatically managing library dependencies, prototyping functions, and defining external global variables to ensure seamless integration with PlatformIO.
Don’t miss this opportunity to modernize your projects!
Disclaimer:
I’ve tested this program with a few of my own Arduino projects, and it worked well. However, I have my own style of writing Arduino code, and yours might be different, so your mileage may vary.
Excellent article! However, you missed a bit I’m afraid.
… the Arduino IDE ignores all files that do not have the extension ‘.ino’, ‘.c’, ‘.cpp’ or ‘.h’.
The Arduino IDE also allows source files with the .S extension for Assembly Language sources. I used these in some of my projects and I’m actually writing a book on the subject!
Also, and you probably already know this, in VSCode, open the PlatformIO Home page and there’s an option to import an existing Arduino sketch as a new PlatformIO project.
Admittedly, this is imported as a framework=arduino style project and simply has the source files copied into the src directory.
As I mentioned though, an excellent article, thank you.
Imagine you have three files: ‘myProgram.ino’, ‘sensor.ino’ and ‘display.ino’. The IDE merges these in the order ‘display.ino’, ‘myProgram.ino’ and ‘sensor.ino’.
The order is the ino file with the same name as the sketch (and the same name as the directory) then all the other *.ino files in alphabetic order. So your example would be myProgram.ino then display.ino and sensor.ino.
if you use the Arduino IDE version 2.x or have downloaded the arduino-cli utility, then you can create a “profile” which is very similar to the platformio.ini file in that it contains the board identifier, code and platform information and a list of used libraries plus their versions.
The profile can be created by:
cd mySketch
/path/to/arduino-cli compile --fqbn arduino:avr:uno --dump-profile > sketch.yaml
Obviously, the “fqbn” should match your particular board, this one is for an Uno. The output file must be sketch.yaml I’m afraid. The docs imply that the output file—sketch.yaml—is in the correct format, but it has not been so far. There is profile information but also, all the compilation messages.
You have to edit the file and remove everything up to, but not including profiles: to get a correct profile for subsequent use.
In future, when the arduino-cli compiles the sketch, the profile will be read, the correct library versions downloaded as necessary, and the sketch rebuilt “exactly” as at first compiled—or at least, when the profile was created.
Sketch project file - Arduino CLI has details of the profile file. Here’s a simple on from one of my Uno’s sketches using a small OLED display:
I think if you use assembler code in your Arduino project you are an advanced user (at least) in witch case this conversion program is not really for you!
Thank you so much for your efforts. I’m sure many will appreciate this info.
One small caveat I’d like to point out, and I say this as a massive fan of PlatformIO and of ESP products: The issue of non-cooperation that has arisen between Espressif and the PlatformIO folks is definitely a concern and something people should keep in mind before they make a switch. There are things missing from the PlatformIO implementation that are significant, especially relating to newer ESP32 products. Yes there are some ways around this, but they aren’t ideal, and no official solution would seem to be forthcoming any time soon.
This is indeed is a concern that I did not know off!
I tried to create a project for the esp32-‘C3’ (RISC-V0 mcu to find out the board is not available with the ‘arduino framework’.
Hope they will solve this non-cooperation issue soon!
One item that remains a bugaboo to migrating from Arduino IDE to PlatformIO and I’ve not found addressed (or I’m failing to create the correct search incantation).
The Arduino IDE Tools menu, after setting up a project looks something like this:
Board: “ESP32S3 Dev Module”
USB CDC On Boot: “Enabled”
CPU Frequency: “240MHZ (WiFi)”
Core Debug Level: “Info”
USB DFU On Boot: “Disabled”
Erase All Flash Before Sketch Upload: “Disabled”
Events Run On: “Core 1”
Flash Mode: “OPI 80MHz”
Flash Size: “8MB (64Mb)”
JTAG Adapter: “Integrated USB JTAG”
Arduino Runs On: “Core 1”
USB Firmware MSC On Boot: “Disabled”
Partition Scheme: “ESP SR 16M (3MB APP/7MB SPIFFS/2.9MB MODEL)”
PSRAM: “OPI PSRAM”
Upload Mode: “UARTO / Hardware CDC”
Upload Speed: “921600”
USB Mode: “Hardware CDC and JTAG”
Zigbee Mode: “Disabled”
Programmer: “Esptool”
For each option above:
How does one find what the equivalent entry for the platformio.ini file would be and, where options are available (like the Flash Size and CPU Frequency), where can the enumerated list of each option be found?
Regarding the article, what about custom partition schemes? The "partitions.csv" file needs to be located in the Arduino-esp32 core and copied in to correct location within the pio project structure. No easy way to find the .csv file matching the name selected in the Tools menu. An easy way to locate?
I’ve tried reverse engineering the Arduino IDE compile output, but that is an exercise best left to a masochist it seems.
Not a rant, just some important things that seem to be skipped over.
… but it seems strange that I have to select ‘seeed_xiao_esp32c3’ for a completely different board.
I wish PlatformIO uses the type of SoC as the main board. Manufacturers can than build on these SoC for a specific ‘board’. I do projects with SoC’s and make my own PCB’s for that. Those PCB’s are never in the PlatformIO board-selector
Wondering how sivar2311 figured that out? Is there anywhere you’re aware of a canonical reference where these options are spelled out (board_build.arduino. vs board_build.) and what combination is required?
As well, options for selecting USB mode, JTAG Adapter and the like?
I got the tip with board_build.arduino.memory_type from maxgerhard for my ESP32-S3 N16R8. I was then able to derive the necessary settings for the other boards from the Espressif data sheets.
There is indeed, it was published in December last year.
Most of the book remains the same in the second edition, however, the chapters on the Arduino-cli and also PlatformIO have been updated quite a lot.
The IDE stuff is actually quite similar, apart from the preferences, and the fact that under the hood, the IDE now uses the Arduino-cli to do all the compilation work.
It can also burn bootloaders now, which it couldn’t do when I covered it in the first edition. It still can’t upload EEPROM files though!
If you don’t mind the plug, I also have “Arduino Interrupts” out as well.
