Boards.txt changes not applied, workaround doesn't work

[jimyuill]

My changes to board.txt are not applied.
This is a known problem, but the posted workaround is not working for me (i.e., delete arduino-ide).

I've spent 2 days investigating, and can't get the work-around to work, nor any other solution.

I'm using a 3rd party board package (from Espressiff), and I am wondering if the package might be in error? Or, I'm doing the workaround incorrectly? Or, the latest Arduino IDE broke the workaround?

More info is below.
Any help is greatly appreciated.
Jim

---- more info:

I'm using the Arduino IDE (v 2.3.6) and CLI (v1.2.0)

Also, I'm using an ESP32 board package from Espressif.
For the board package, I'm using v2.0.13, and FQBN esp32:esp32:esp32s3.
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

I've tried the simplest change to boards.txt. I changed this property from 0 to 1:
esp32s3.build.cdc_on_boot=1

In the IDE, in File : Tools, the default value (0) results in:
USB CDC on Boot: "Disabled"

A value of 1 should result in:
USB CDC on Boot: "Enabled"

The workaround appears in several posts (the same workaround):
https://forum.arduino.cc/t/changes-to-boards-txt-or-platform-txt-not-picked-up-until/1130913
https://forum.arduino.cc/t/issue-with-boards-txt-working-in-arduino-ide-1-x-but-not-in-2-x/1314293
https://forum.arduino.cc/t/manual-edits-to-boards-txt-not-picked-up/1045377

I used the workaround:

• Closed Arduino IDE

• Modified boards.txt
  At C:\Users<user>\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.13

• Deleted C:\Users\AppData\Roaming\arduino-ide\

• Opened IDE

• Created a new sketch and used board package: ESP32S3 Dev Module.

• In File : Tools, the new boards.txt was not applied. That is:
  "USB CDC on Boot" is still "Disabled"

Also, in the CLI, this command shows the modified boards.txt is not being used:
"arduino-cli compile --show-properties"

[ptillisch]

Hi @jimyuill.

@jimyuill

I've tried the simplest change to boards.txt. I changed this property from 0 to 1:
esp32s3.build.cdc_on_boot=1

Let's start with a general understanding how the system works

The "ESP32S3 Dev Module" board's Tools > USB CDC On Boot menu is created by a feature called "custom board options", which is documented in the Arduino Platform Specification:

https://arduino.github.io/arduino-cli/latest/platform-specification/#custom-board-options

The menu is configured by this code in the board definition:

esp32s3.menu.CDCOnBoot.default=Disabled
esp32s3.menu.CDCOnBoot.default.build.cdc_on_boot=0
esp32s3.menu.CDCOnBoot.cdc=Enabled
esp32s3.menu.CDCOnBoot.cdc.build.cdc_on_boot=1

These lines define the text of the two menu items:

esp32s3.menu.CDCOnBoot.default=Disabled

esp32s3.menu.CDCOnBoot.cdc=Enabled

These lines define the property definitions for each of the options:

esp32s3.menu.CDCOnBoot.default.build.cdc_on_boot=0

esp32s3.menu.CDCOnBoot.cdc.build.cdc_on_boot=1

The format is like this:

<board ID>.menu.<menu ID>.<option ID>.<property name>=<property value>

All properties associated with the option ID of the option that is selected from the custom board options menu will be defined. Properties associated with the option ID of the option that is not selected from the menu will not be defined. So if we select Tools > USB CDC On Boot > Enabled from the Arduino IDE windows, then the property build.cdc_on_boot will be defined with the value of 1.

The menu items are ordered according to the order of the menu text definition lines in the boards.txt file. The first item on the menu is the default menu selection. So if you want to change the default menu item from "Disabled" to "Enabled, then you would only need to swap the order of the lines:

esp32s3.menu.CDCOnBoot.cdc=Enabled
esp32s3.menu.CDCOnBoot.cdc.build.cdc_on_boot=1
esp32s3.menu.CDCOnBoot.default=Disabled
esp32s3.menu.CDCOnBoot.default.build.cdc_on_boot=0

(it isn't required to also swap the order of the associated property definition lines along with the menu text definitions, but it makes the code easier to read and maintain if we keep them together)

So your first mistake was in assuming that the default menu selection was determined by a property value, when in truth it is solely controlled by the order of the lines in boards.txt.

The second mistake you made was in thinking that this line does anything at all:

esp32s3.build.cdc_on_boot=1

It does not. Both of the options of the CDCOnBoot custom board options menu define a build.cdc_on_boot property, and their property definitions are at a later point in the file than this non-custom option-based definition of the build.cdc_on_boot property, so this definition of build.cdc_on_boot will always be overridden by the definitions from the CDCOnBoot custom board options.

Unfortunately there is quite a bit of this sort of pointless cruft in the "esp32" platform's configuration files. Maybe it served a purpose at some time in the past and the developers forgot to remove it when it was superseded, or maybe they cursorily copy pasted it from some other board definition where it did serve a purpose, then left it in the new definition because they didn't understand that it was pointless due to never taking the time to learn how the system actually works.

---

So you can now see that the problem you encountered was not in fact caused by Arduino IDE and Arduino CLI not recognizing the change you made to the file. The problem you encountered was instead caused by the change you made to the file being incorrect.

[Deva_Rishi]

@ptillisch

The menu items are ordered according to the order of the menu text definition lines in the boards.txt file. The first item on the menu is the default menu selection. So if you want to change the default menu item from "Disabled" to "Enabled, then you would only need to swap the order of the lines:

!!!

@ptillisch

Unfortunately there is quite a bit of this sort of pointless cruft in the "esp32" platform's configuration files. Maybe it served a purpose at some time in the past and the developers forgot to remove it when it was superseded, or maybe they cursorily copy pasted it from some other board definition where it did serve a purpose, then left it in the new definition because they didn't understand that it was pointless due to never taking the time to learn how the system actually works.

I Actually suspect that they intended to provide plenty of options for 3rd part board developers to add to the boards, but yes in some ways the guys from Espressif know how to overflow the menu with options. Keep in mind though that the cores should provide support for many boards that use their MCU, but with added RAM PSRAM Serial ports pinouts etc, etc. I personally thought of removing some of the stuff or boards really, I would want to remove some of the boards that i'll never buy and use and in some case are not even for sale anymore, but i have more stressing matters to attent to, and am concerned that by removing an option i may not leave the correct setting in place.

[jimyuill]

ptillisch, this is great info-- THANK YOU!!!

Your tutorial on the menu structure is very clear and much appreciated.

I had deduced that structure from the Espressif boards.txt, but wrongly assumed the "cruft" at the beginning was where the selected build-options were stored, e.g.,
esp32s3.build.cdc_on_boot=1

So, for "USB CDC On Boot", when "Enabled" was selected, I wrongly assumed it was recorded in that cruft as:
esp32s3.build.cdc_on_boot=1

Also, I wrongly assumed the CLI's --show-properties would get the build properties from there.

FYI, not an unreasonable assumption given these statements in the CLI docs:
"Sketches are compiled by architecture-specific versions of gcc and g++ according to the variables in the boards.txt file"
"The settings for a board are defined through a set of properties with keys having the board ID as prefix."

Do you happen to know how that works internally?
When a Tools option is selected, where is it recorded internally?
My wild guess is:
C:\Users<user>\AppData\Roaming\arduino-ide\databases

Thanks again.
Please let me know if I can ever repay the favor,
Jim
https://jimyuill.com/

[ptillisch]

@jimyuill

Do you happen to know how that works internally?
When a Tools option is selected, where is it recorded internally?
My wild guess is:
C:\Users\AppData\Roaming\arduino-ide\databases

Your guess is correct.

Unfortunately I don't have an understanding of the system much beyond that.

The data is stored on a per-sketch basis. So Arduino IDE records the custom board options you select while a given sketch is open in Arduino IDE, and will automatically select those same options the next time you open that sketch. The data is associated to the sketch by the path of the sketch on your hard drive, so if you moved or renamed a sketch externally (e.g., via your file manager) instead of using Arduino IDE, then you will find that the default custom board options are selected the next time you open the sketch in Arduino IDE.

@jimyuill

Thanks again.
Please let me know if I can ever repay the favor,

You are welcome. Knowing that I was able to be of some small assistance is plenty enough for me personally.

Contributions are always welcome to support the Arduino company's work on open source software projects like Arduino IDE and Arduino CLI, documentation, and other efforts to support the Arduino community. There is some information on that here:

https://github.com/arduino/arduino-ide/blob/main/docs/CONTRIBUTING.md#contributor-guide

[dankeboy36]

@jimyuill

Do you happen to know how that works internally?
When a Tools option is selected, where is it recorded internally?
My wild guess is:
C:\Users\AppData\Roaming\arduino-ide\databases

Where does the Arduino IDE store board config options?

Arduino IDE stores the board configuration selections in localStorage, using Chromium's LevelDB backend.

On macOS, you can find it here:

/Users/<username>/Library/Application Support/arduino-ide/Local Storage/leveldb

How to inspect it:

1. Open the IDE.
2. Press Ctrl/Cmd + Shift + P to open the Command Palette.
3. Search for Toggle Developer Tools and activate it.
4. In the opened DevTools, navigate to the Application tab (click >> if it's hidden).
5. Under Storage → Local Storage, select the file:// origin.

Do not forget to close the Dev Tools in IDE by clicking on the X

You can use the filter bar at the top to search keys. The configuration is scoped by:

• Sketch folder path
• Platform version
• Board FQBN (e.g., esp8266:esp8266:generic)

When you filter using the board FQBN, you might see multiple matching keys — that's because it's stored per sketch folder. Select the one relevant to your sketch and inspect the config.

Tips:

• You can right-click on an entry and delete it without clearing the entire cache.
• If you remove the config and reselect the board in the UI, it will recreate the cache. (I have not verified it.)
• Restarting the IDE may help apply the reset. (I have not verified it, but this must work.)

---

How does this work internally?

When a board/tool menu item is selected, the IDE:

1. Checks localStorage for a matching cached value.
2. If none exists, it calls the equivalent of the board details gRPC command from arduino-cli.
3. This returns the board's config_options (API spec).
4. The IDE overrides the defaults with the user's choices, builds a JSON object, and stores it in localStorage.

On next startup, the IDE uses the cached data to populate menus without calling arduino-cli board details again — this is where the caching pays off.

---

Potential improvements?

There’s room for quality-of-life features, such as:

• A command to wipe all cached board config
• A scoped reset (per sketch folder / per platform / per board)
• Storing only deltas (user overrides), and always querying fresh board details on startup

However, calling board details repeatedly could slow down startup, especially when multiple sketch folders are restored.

---

If you want to dive deeper into this behavior, check out the relevant source code:
boards-data-store.ts

[jimyuill]

@ dankeboy36 Thanks! Very informative and clearly explained.
The code is cool-- amazing you did all of that in 500 LOC.
BTW: I followed your instructions-- they worked well.