Allow configuring board for IDE to select by default when sketch is opened

[matsekberg]

Enable the use of some meta-comment in the code so that the appropriate board is automatically selected for that code.

Additional context

Additional requests

• Allow configuring board for IDE to select by default when sketch is opened #2438 (comment)
• Allow configuring board for IDE to select by default when sketch is opened #2438 (comment)
• Allow configuring board for IDE to select by default when sketch is opened #2438 (comment)
• Allow configuring board for IDE to select by default when sketch is opened #2438 (comment)
• Allow configuring board for IDE to select by default when sketch is opened #2438 (comment)
• Allow configuring board for IDE to select by default when sketch is opened #2438 (comment)
• Automatic board selection #81
• Ability to associate board with sketch #1892
• Ability to associate board with sketch #1892 (comment)
• Assigning a board to a sketch Arduino#3228
• Tie together the port, board and sketch. Arduino#3459
• Persistent Board Setting Arduino#4950
• RFE: IDE to save board type inside the project Arduino#5121
• IDE does not place board info in INO file Arduino#5232
• Specify target board / settings in .ino code / comments. Arduino#5308
• Feature Request: sketch properties Arduino#6294
• Allow multiple Serial Monitor windows. Merge input from multiple ports into a single Serial Montor window. Arduino#6490
• Arduino IDE should recognize and apply settings found in preferences.txt in sketch folders Arduino#7324
• [Arduino IDE] Please add project settings connected to specific .ino Arduino#7327
• Custom hardware presets Arduino#7337
• [Suggestion] Add a header defining which board and additional compile settings, the sketch should compile with Arduino#7339
• Store board information beside sketch Arduino#7746
• feature request: hardcode-config board type by configuration in Sketch (e.g. #pragma config...) Arduino#10175
• We need a "project file" Arduino#10462
• Suggestion to save the settings in the project Arduino#11304
• Automatic board selection #81
• [IDE V2] Introduce a separate metadata manifest file for each project Arduino#11753
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/1
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/3
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/7
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/11
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/16
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/19
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/20
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/21
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/22
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/24
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/28
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/30
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/31
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/33
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/35
• https://forum.arduino.cc/t/board-settings-in-ino-file/343215/43
• https://forum.arduino.cc/t/setting-partition-for-a-project/699061
• https://forum.arduino.cc/t/store-board-info-in-ino-file-and-automatically-load/466878
• https://forum.arduino.cc/t/running-preload-script/506108
• https://forum.arduino.cc/t/save-board-selection-with-sketch/523805
• https://forum.arduino.cc/t/ide-parameters/557892
• https://forum.arduino.cc/t/associating-the-project-with-the-processor-important/670725
• https://forum.arduino.cc/t/feature-request-board-selection/941360
• https://forum.arduino.cc/t/defining-board-type-in-sketch/1203965
• https://forum.arduino.cc/t/saving-micro-controller-config-to-sketch/1300406
• https://forum.arduino.cc/t/can-i-just-swap-preferences-txt-to-switch-board-projects/1343878

Related

• Allow storing the protocol+port info per sketch profile arduino-cli#2554
• Use configuration from sketch project file #2573

[timkoers]

If you need any one to give it a try creating this function, count me in!
I'll see if I can create something.
If you can give a few examples about how you'd like the syntax to be and where ether you'd like a preferences.txt file or add it to a header in the main .ino file, might give it a try.

[JamesNewton]

@timkoers A few thoughts:

1. If there is a preferences file, then it doesn't "travel" with the INO file. Better to use, as originally suggested, "meta-comments" in the INO file. Yes, one can have multiple files in a folder, includes, data, etc... but many users find a single, simple, INO file posted on the web and copy it in. Yes, Arduino code is very portable, but it's best for the IDE to at least try to select the right one for the sketch when the author bothered to specify it. Keep in mind, the vast majority of INO files will not specify the chip. This is primary for those poor souls who are maintaining a large set of programs over a range of devices and are tired of switching. And also to help out new users who don't understand that a sketch might be for a specific device when the author is kind enough to hint that in the INO file.

2. In any case, the IDE should never assume an action. Upon opening the file, and parsing meta-comments, it should offer to make those changes for the user. The user can accept or reject the offer. If the user rejects the offer, no changes are made. The user may just be browsing the code.

3. Keeping a simple format in the INO file means it also works as documentation for the human. E.g.
   // Tools / Board / Arduino Nano
   can be read by the IDE and also by a human.

4. As one menu change may affect the availability of others, they should be processed in order. e.g.
   // Tools / Board / Node MCU 1.0 (ESP-12E Module)
// Tools / Flash Size / 4M (1M SPIFFS)

5. As humans hate to type, it might be good to have a menu option that records the current menu settings into the top of the .INO or updates the existing settings.

Things I'm less sure about:

• When to trigger the parsing? File / open only? File / New, Edit / Paste? Upon any change to the file, but only if the current menu settings don't match the parsed meta-comments? I would lean towards the latter, but that does mean that will be parsed on every build. That isn't too much of a burden is it?

• Which items should be included / excluded? Obviously, the File, Edit, Sketch, and Help menus should be excluded. Tools / Port and / Upload speed should probably be excluded. Perhaps just start with everything on the Tools menus and tune in later releases?

• What to do if a board isn't available. Actually, that's pretty obvious, just error out. But the point is you have to look for that and interact with the user about it.

[Avamander]

@timkoers
Just mentioning, compatibility with doxygen would be really nice (so that the generated documentation actually also mentions the sketchs' intended boards and etc.), it would be a good idea to even contact the doxygen developer if you aren't that familiar with doxygen yourself.

[timkoers]

Sure!
What I could do is use the doxygen syntax formatting so that doxygen is able to generate the data out of the box

[timkoers]

Just a little update, I managed to get it working!
The syntax is as following:

/** Arduino IDE Board Tool details
 * Board: Node32s
 * Flash Frequency: 80MHz
 * Upload Speed: 921600
*/

[JamesNewton]

Love it!

Is it looking for the exact text "Arduino IDE Board Tool details"? If so, may I suggest something simpler and less likely to be incorrectly entered? E.g. "Settings" or "Tools Menu" or even "Arduino Tools Menu Settings". I'm trying to come up with things that are unlikely to be misspelled or typoed. E.g. You can look up and see the word "Arduino" in the ide so that's a good choice. And it is the "Tools Menu" so that's easy to remember. Probably "Arduino Tools Menu" is best. It tells you exactly where it's going to have effect.

[tschundler]

@timkoers, have you submitted a pull request for that? Was it rejected? (If so, why?)

[timkoers]

@tschundler I submitted a pull request (arduino/Arduino#7349) that has the feature that we are talking about implemented. I don't think it was rejected, it was not accepted.

[JamesNewton]

@per1234 Oh, I'm terribly sorry if my tone came over wrong. I seriously meant no offense to you or anyone else. I guess my frustration with prior interactions with non-contributors is boiling over here and I apologize for that. Since you actually have contributed to the project, I'll take the time to try to explain further:

Perhaps the word "interaction" is confusing. Let me clarify: This must go two ways. If you put something in the comments of the source .ino file which /always/ causes a change to settings, that violates least user surprise and breaks the CLI. If you pop up a dialog and /ask/ what the user wants, surprise is mitigated.

Popping up a dialog is generally not done in CLI's, at least as far as I've seen. Would you want the CLI to stop mid way and ask the user about which board to target? For the CLI, a separate (optional) settings file, or the port / board association makes perfect sense. Interaction doesn't happen in CLI's except via the command line. The GUI IDE can write a settings file or, more obviously, change the command line options when invoking the compiler. This is a GUI IDE feature only.

I guess it could be valuable for the CLI to issue a warning if the comment indicates one board and you're command line settings are compiling for another? But more than that would be problematic.

Now, you could argue that the port / board association or a separate settings file makes sense in the GUI, but it has a serious limitation: The user must know about it. As I've indicated above, most beginning users are not aware of the need to select a board. Even if they understand the need to select for the board they own, the .INO that they pasted in often needs a specific board and this is not noted in the sketch which is all they have. An easy way for authors to add that to the file, in the comments so it doesn't break the CLI, and have the GUI IDE point it out to you, is a help.

Interactions are typically associated with the GUI. We are specifically asking for a change to the GUI IDE ONLY for /interaction/ with the user. Again: It's like syntax highlighting or autocomplete. It simply works WITH the user /interactively/ to help a new user select the correct board for the project.

Interactive. GUI only.

Like autocomplete, or syntax highlighting, or copy and paste, or typing in the .INO file.

Very simple: The GUI IDE looks at the comments, finds a matching block, sees that the menus don't match and this is the first time this session, so it asks the user if they want the menus updated from the comment. The user can say "Yes" or "No" and that's the end of the interaction. If they said yes, the menus are updated to match the INO.

[timkoers]

@JamesNewton +100000!
That is exactly what my PR (arduino/Arduino#7349) does, except for the dialog to ask the user if they'd like to get the settings matched with the comments in the .INO file.

The only problem with my PR, is that it is outdated. But I am willing to fix that

[tschundler]

Where is sketch.json documented? Quickly search Google found example of it, but no docs. It sounds like maybe a solution for most(?) cases.

[per1234]

If you put something in the comments of the source .ino file which /always/ causes a change to settings, that violates least user surprise and breaks the CLI.

But it doesn't always cause a change. Let's say you do this:

arduino-cli board attach arduino:avr:nano Foo

Now the default board for that sketch is the Nano. So if you do this:

arduino-cli compile Foo

it will compile for the Nano. However, if you do this:

arduino-cli compile --fqbn arduino:avr:uno Foo

then it will compile for the Uno. The only time you wouldn't use the --fqbn option is if you specifically wanted to use the default board associated with the sketch. So arduino-cli compiling for Nano in that case is not surprising to the user. Therefore there is no need for interaction in the CLI because the user is specifying exactly how they want arduino-cli to behave in advance in the command.

I guess it could be valuable for the CLI to issue a warning if the comment indicates one board and you're command line settings are compiling for another?

No need, since the command line settings, if present, override the default settings in sketch.json.

Now, you could argue that the port / board association or a separate settings file makes sense in the GUI, but it has a serious limitation: The user must know about it.

Not if the IDE has a GUI interface that allows them to set the associations. They don't need to know the mechanism behind how that information is stored. This similar to the Arduino IDE's File > Preferences interface. The preferences are stored to the preferences.txt file, but the user doesn't need to know that. They just set their preferences via the GUI. This is similar to how arduino-cli has a arduino-cli board attach command. Even the CLI user doesn't need to know about sketch.json.

Where is sketch.json documented?

I don't think it has been documented. It would be good to document this somewhere in the arduino-cli GitHub repository for people who might want to use that file directly UPDATE: it has now been documented in the Arduino sketch specification. However, arduino-cli's command line help does document the board attach command, which is the normal user's interface to that file:

>arduino-cli help board attach
Attaches a sketch to a board.

Usage:
  arduino-cli board attach <port>|<FQBN> [sketchPath] [flags]

Examples:
  C:\Users\per\go\bin\arduino-cli.exe board attach serial:///dev/tty/ACM0
  C:\Users\per\go\bin\arduino-cli.exe board attach serial:///dev/tty/ACM0 HelloWorld
  C:\Users\per\go\bin\arduino-cli.exe board attach arduino:samd:mkr1000

Flags:
  -h, --help             help for attach
      --timeout string   The timeout of the search of connected devices, try to high it if your board is not found (e.g. to 10s). (default "5s")

Global Flags:
      --additional-urls strings   Additional URLs for the board manager.
      --config-file string        The custom config file (if not specified the default will be used).
      --format string             The output format, can be [text|json]. (default "text")
      --log-file string           Path to the file where logs will be written.
      --log-format string         The output format for the logs, can be [text|json]. (default "text")
      --log-level string          Messages with this level and above will be logged. (default "info")
  -v, --verbose                   Print the logs on the standard output.

[dsyleixa]

IMO the most simple way would be to hardcode-config the targeted board type by configuration in Sketch (e.g. #pragma config...) such as

#pragma config board="Nano"
#pragma config board="NODE_MCU 1.0"
#pragma config board="Adafruit Feather ESP32"

[Tsessebe]

If I may add my 10 cents...

As I software developer by day; and Arduino enthusiast by night; may I make a suggestion:
Why not create a config folder (Similar to Visual Studio or JetBrains IDEs), in the sketch folder, where the settings are recoded?

The config/ meta data can them be sodred in either a JSON file or YAML file. My understanding is that the Arduino-CLI makes use of a YAML file.

Visual Studio creates a .vs folder, where the meta data for the project is stored, similarly JetBrains IDE's creates a .idea folder.
This is a standard practice in Modern IDEs.

This mechanism is also used in text editors like VS Code (.vscode folder).

It is a simple yet elegant way of recording the IDE metadata as well as user selected settings.