Skip to content

Move information re: allowed characters for FQBN component to specifications #2902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Move information re: allowed characters for FQBN component to specifications #2902

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions docs/FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?

Expand Down
4 changes: 4 additions & 0 deletions docs/package_index_json-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
23 changes: 20 additions & 3 deletions docs/platform-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1627,7 +1639,12 @@ duemilanove.menu.cpu.atmega168=ATmega168

We have defined two values: "atmega328" and "atmega168".<br> 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.<br> 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:

```
[.....]
Expand Down