From 71b5037a3a7c963d6f26e3ae88887f89abb1c16e Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 30 Apr 2025 10:16:54 -0700 Subject: [PATCH] Move information re: allowed characters for FQBN component to specifications Arduino CLI restricts which characters can be used by platform developers in their vendor, architecture, board, custom board menu, and custom board option identifiers. Previously, the information was only documented(?) in the "FAQ". This type of requirement must be present in the formal specifications. A platform developer is unlikely to ever think to look for such information in the FAQ. In addition, the inclusion of such information in the FAQ is not appropriate as this is intended for end users of the Arduino CLI application and end users have no control over which characters were used by the platform developers in their identifiers. So the presence of the information in the FAQ only harms readability by introducing unnecessary complexity into a subject that users often struggle to understand. --- docs/FAQ.md | 6 ++---- docs/package_index_json-specification.md | 4 ++++ docs/platform-specification.md | 23 ++++++++++++++++++++--- 3 files changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index ebd50812830..63aa5f74d1f 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -11,10 +11,8 @@ When you run [`arduino-cli board list`][arduino cli board list], your board does FQBN stands for Fully Qualified Board Name. It has the following format: `VENDOR:ARCHITECTURE:BOARD_ID[:MENU_ID=OPTION_ID[,MENU2_ID=OPTION_ID ...]]`, with each `MENU_ID=OPTION_ID` being an -optional key-value pair configuration. Each field accepts letters (`A-Z` or `a-z`), numbers (`0-9`), underscores (`_`), -dashes(`-`) and dots(`.`). The special character `=` is accepted in the configuration value. The `VENDOR` and -`ARCHITECTURE` parts can be empty. For a deeper understanding of how FQBN works, you should understand the [Arduino -platform specification][0]. +optional key-value pair configuration. The `VENDOR` and `ARCHITECTURE` parts can be empty. For a deeper understanding of +how FQBN works, you should understand the [Arduino platform specification][0]. ## How to set multiple board options? diff --git a/docs/package_index_json-specification.md b/docs/package_index_json-specification.md index 2752ef732ea..9cfcebe4422 100644 --- a/docs/package_index_json-specification.md +++ b/docs/package_index_json-specification.md @@ -64,6 +64,8 @@ The metadata fields are: - `name`: the folder used for the installed cores. The [vendor folder](platform-specification.md#hardware-folders-structure) name of the installed package is determined by this field + - The value must not contain any characters other than the letters `A`-`Z` and `a`-`z`, numbers (`0`-`9`), underscores + (`_`), dashes (`-`), and dots (`.`). - `maintainer`: the extended name of the vendor that is displayed on the Arduino IDE Boards Manager GUI - `websiteURL`: the URL to the vendor's website, appears on the Arduino IDE Boards Manager as a "More info" link - `email`: the email of the vendor/maintainer @@ -260,6 +262,8 @@ Each PLATFORM describes a core for a specific architecture. The fields needed ar - `name`: the extended name of the platform that is displayed on the Boards Manager GUI - `architecture`: is the architecture of the platform (avr, sam, etc...). It must match the architecture of the core as explained in the [Arduino platform specification](platform-specification.md#hardware-folders-structure) + - The value must not contain any characters other than the letters `A`-`Z` and `a`-`z`, numbers (`0`-`9`), underscores + (`_`), dashes (`-`), and dots (`.`). - `version`: the version of the platform. - `deprecated`: (optional) setting to `true` causes the platform to be moved to the bottom of all Boards Manager and [`arduino-cli core`](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_core/) listings and marked diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 47fbc2a62bc..652b7348878 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -24,7 +24,11 @@ Alternatively, a platform may be manually installed by the user inside the Sketc - `{directories.user}` is the user directory as specified in the [configuration file](configuration.md#default-directories). - `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform. + - The name of the vendor directory must not contain any characters other than the letters `A`-`Z` and `a`-`z`, numbers + (`0`-`9`), underscores (`_`), dashes (`-`), and dots (`.`). - `{ARCHITECTURE}` is the architecture of the CPU used in the platform. + - The name of the architecture directory must not contain any characters other than the letters `A`-`Z` and `a`-`z`, + numbers (`0`-`9`), underscores (`_`), dashes (`-`), and dots (`.`). A vendor/maintainer may have multiple supported architectures. @@ -534,6 +538,9 @@ This file contains definitions and metadata for the boards supported by the plat short name, the board ID. The settings for a board are defined through a set of properties with keys having the board ID as prefix. +The board ID must not contain any characters other than the letters `A`-`Z` and `a`-`z`, numbers (`0`-`9`), underscores +(`_`), and dashes (`-`). + For example, the board ID chosen for the Arduino Uno board is "uno". An extract of the Uno board configuration in boards.txt looks like: @@ -1591,8 +1598,13 @@ This board was produced in two models, one with an ATmega168 microcontroller and going then to define a custom option, using the "cpu" MENU_ID, that allows the user to choose between the two different microcontrollers. -We must first define a set of **menu.MENU_ID=Text** properties. **Text** is what is displayed on the GUI for every -custom menu we are going to create and must be declared at the beginning of the boards.txt file: +We must first define a set of **menu.MENU_ID=Text** properties. + +The menu ID must not contain any characters other than the letters `A`-`Z` and `a`-`z`, numbers (`0`-`9`), underscores +(`_`), and dashes (`-`). + +**Text** is what is displayed on the GUI for every custom menu we are going to create and must be declared at the +beginning of the boards.txt file: ``` menu.cpu=Processor @@ -1627,7 +1639,12 @@ duemilanove.menu.cpu.atmega168=ATmega168 We have defined two values: "atmega328" and "atmega168".
Note that the property keys must follow the format **BOARD_ID.menu.MENU_ID.OPTION_ID=Text**, where **Text** is what is displayed under the "Processor" menu in the IDE's -GUI.
Finally, the specific configuration for each option value: +GUI. + +The option ID must not contain any characters other than the letters `A`-`Z` and `a`-`z`, numbers (`0`-`9`), underscores +(`_`), dashes (`-`), and equal signs (`=`). + +Finally, the specific configuration for each option value: ``` [.....]