Please document the Arduino core Tools menu options

[technoblogy]

Related area

Arduino core documentation

Hardware specification

All ESP32, ESP-S2, ESP-C3, and ESP-S3 boards

Is your feature request related to a problem?

Many of the options on the Arduino IDE Tools menu for the ESP32 core aren't obvious, but I can't find them documented anywhere. If they are documented, please mention where to find this information in the main Arduino core ReadMe.

For example:

Upload Speed: Why might I want to choose 115200 rather than the default 921600?
USB CDC on Boot/USB Firmware MSC on Boot/USB DFU on Boot: What are these for, and recommended settings?
CPU Frequency: I assume the (WiFi/BT) options mean you must choose one of these to use WiFi or BT.
Flash Frequency: How do I know what setting to choose?
Flash Mode: Again, how do I know what setting to choose?
Partition Scheme: What's the difference between FAT and FATFS? What about LittleFS?
Arduino Runs On/Events Run On: When would I want to use these?

Perhaps a statement saying that the default option is usually the recommended choice would solve some of these.

Searching on docs.espressif.com doesn't find answers to most of these.

Describe the solution you'd like

A sentence expanding the menu option into a sentence, explaining the conditions under which you might want to choose other than the default option (eg lower power versus higher speed), with an explanation of the acronyms (CDC, MSC, DFU, etc), and perhaps a link to fuller information would be ideal.

This should ideally go as a separate section Arduino core Tools menu in the documentation between Installing (Windows, Linux and macOS) and Libraries.

I'm happy to draft something, with gaps where I don't know the answers.

Describe alternatives you've considered

No response

Additional context

No response

I have checked existing list of Feature requests and the Contribution Guide

• I confirm I have checked existing list of Feature requests and Contribution Guide.

[henrygab]

Not a solution, but offering my decoding of some of the acronyms:

USB CDC == Communications Device Class
USB MSC == Mass Storage Class
USB DFU == Device Firmware Update

Thus, it's possible that choosing ...

• CDC causes exposure of a COM-port (aka Serial Port)
• MSC causes exposure of a USB flash storage device
• DFU causes exposure of a device firmware update USB class (e.g., Base Class FEh, subclass 01h, protocol 01h)

See generally https://www.usb.org/defined-class-codes

[VojtechBartoska]

Hi @technoblogy, thanks for your feedback and extensive description. Tagging @pedrominatel.

[technoblogy]

@henrygab thanks for the acronyms!

[pedrominatel]

Thank you @technoblogy for your feedback. This document is currently on our docs roadmap and we will start working on that soon.