PlatformIO Community

ESP8266 how to choose firmware

Trying to get ESP8266 platform to work on PlatformIO.
Discussion with ESP8266 developers to resolve a connectivity problem, they told me to try the following options in Arduino SDK.

  • Select “generic esp8266 module”, keep default values except these for your nodeMCU:
    • Flash mode: QIO
    • Erase Flash: All Flash Content
    • Espressif FW: 2.2.1-Legacy

How do I set these options within PlatformIO. I’ve found an option for QIO, but I do not see an option in particular to choose the optional firmware to load.

Is this possible with platformIO?

Yes, this is possible. As you can see in the builder code

Your wanted option of

Thus corresponds to adding

build_flags = 

in the platformio.ini.

If you execute the build in verbose mode (via VSCode “Verbose Build” or pio run -v) you can also double-check that by making sure the final linker command has

-L <arduino-esp8266 framework path>/tools/sdk/lib/NONOSDK221 

in it. It’s also a good idea to check if the macro was successfully defined from the build script, so e.g. do

#if NONOSDK221 == 1
Serial.println("Non-os SDK 2.2.1 is activated");
Serial.println("Other SDK version activated...");

I’ve just added the SDK version flags to the documentation, so that should update shortly, for future reference. Made possible by Max’s comments above! :wink:

I assume from your earlier comment you found the example showing to add board_build.flash_mode = qio to your platformio.ini to configure the flash mode as qio.

To erase flash, PlatformIO only does that on demand. Either run pio run --target erase from a PIO Terminal (click the rightmost icon of the group on the left) or use the ‘Erase Flash’ project task in the PlatformIO extension sidebar.


1 Like

@maxgerhardt That worked! Thanks!

1 Like

Will the updated documentation be at this link?
or somewhere else?

Yes, between the lwIP and SSL headings. The extra section has been accepted, I’m just not sure how often the docs get regenerated. You can it here now if you’re impatient like me! :wink:

@maxgerhardt - I only have a few of these options in PlatformIO (in VSCode) how do I get the full list?


With platformio.ini is that? Does your project build (to make sure all the platforms and frameworks are downloaded…)?

Yes, my project builds. This is the platformIO from the VSCode extensions: PlatformIO IDE

No I mean the platformio.ini file of the project folder there.

from this site: (Sry, misread first time, lol)

This uses an old platform version from 21 May 2019. In there I get the same behavior as you.


It may also have to do something with an the newer PIO core version or extension version that this doesn’t work anymore with older platform versions.

If I change the above referenced lines to

platform = espressif8266@2.6.3
platform_packages      = 

I get the tasks again.


But does the firmware still work then? Idk.

What you could try is stay with that old platform version and then use the CLI to trigger whatever you want.

Uploading and Building etc is still there so I can only image that you might want to do the “Upload filesystem image” task, which you can access by doing

pio run -e esp8266 -t uploadfs

I was able to get the CLI command to do what I wanted, Thank you for that!

I made the above changes and I got this error:

Show errors revealed that it seems to be looking for an ‘include’ folder I don’t have…

Whatev, the CLI worked. Much appreciated!

You pressed start debugging in the debug sidebar? The ESP8266 chips cannot be debugged in PlatformIO due to HW and SW issues.

Do you want to just upload the firmware to the chip?

Yes. I was able to upload, even with this error.

I tried this thread’s methodology with a project’s platformio.ini using:

platform = espressif8266
board = d1_mini
framework = arduino
monitor_speed = 115200
upload_speed = 921600

… and it worked great just as described above.

How do I do this same sort of thing with a NonOS version?

platform = espressif8266
board = d1_mini
framework = esp8266-nonos-sdk
build_flags = -I include
monitor_speed = 115200
upload_speed = 921600

I found the file described in @maxgerhardt post above for the Arduino version on my computer and went looking under the equivalent packages folder: framework-esp8266-nonos-sdk but found no file.

The default SDK version that installed on my computer a few weeks ago was only at 2.1.0, while I see the Espressif is up to 3.0.5.

Thanks for any help.

The info in this thread only applies to selecting the possible SDK versions contained in the Arduino core. The esp8266-nonos-sdk framework files (and builder script) are severely outdated in PlatformIO ( and that cannot be easily changed by adding a define. The developers have to integrate the newest version into PlatformIO.

Thank you for your reply.