The PR has no duplicates (please search among thePull Requests
before creating one)
The PR follows
our contributing guidelines
[N/A] Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)
[N/A]UPGRADING.md has been updated with a migration guide (for breaking changes)
[N/A]configuration.schema.json updated if new parameters are added.

What kind of change does this PR introduce?

Docs update

What is the current behavior?

Arduino CLI restricts which characters are supported for use by platform developers in their vendor, architecture, board, custom board menu, and custom board option identifiers:

arduino-cli/pkg/fqbn/fqbn.go

Lines 45 to 93 infaf79a7

	varfqbnValidationRegex=regexp.MustCompile(`^[a-zA-Z0-9_.-]*$`)
	varvalueValidationRegex=regexp.MustCompile(`^[a-zA-Z0-9=_.-]*$`)

	// Parse parses an FQBN string from the input string
	funcParse(fqbnInstring) (*FQBN,error) {
	// Split fqbn parts
	fqbnParts:=strings.Split(fqbnIn,":")
	iflen(fqbnParts)<3\|\|len(fqbnParts)>4 {
	returnnil,errors.New(i18n.Tr("not an FQBN: %s",fqbnIn))
	}

	fqbn:=&FQBN{
	Vendor:fqbnParts[0],
	Architecture:fqbnParts[1],
	BoardID:fqbnParts[2],
	Configs:properties.NewMap(),
	}
	iffqbn.BoardID=="" {
	returnnil,errors.New(i18n.Tr("empty board identifier"))
	}
	// Check if the fqbn contains invalid characters
	fori:=0;i<3;i++ {
	if!fqbnValidationRegex.MatchString(fqbnParts[i]) {
	returnnil,errors.New(i18n.Tr("fqbn's field %s contains an invalid character",fqbnParts[i]))
	}
	}
	iflen(fqbnParts)>3 {
	for_,pair:=rangestrings.Split(fqbnParts[3],",") {
	parts:=strings.SplitN(pair,"=",2)
	iflen(parts)!=2 {
	returnnil,errors.New(i18n.Tr("invalid config option: %s",pair))
	}
	k:=strings.TrimSpace(parts[0])
	v:=strings.TrimSpace(parts[1])
	ifk=="" {
	returnnil,errors.New(i18n.Tr("invalid config option: %s",pair))
	}
	if!fqbnValidationRegex.MatchString(k) {
	returnnil,errors.New(i18n.Tr("config key %s contains an invalid character",k))
	}
	// The config value can also contain the = symbol
	if!valueValidationRegex.MatchString(v) {
	returnnil,errors.New(i18n.Tr("config value %s contains an invalid character",v))
	}
	fqbn.Configs.Set(k,v)
	}
	}
	returnfqbn,nil
	}

This information is only documented(?) in the "FAQ" (#2509). 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 (e.g.,arduino/arduino-cli#355).

It is especially problematic that this information is not properly documented because the restrictions were introduced relatively recently and there are established platforms which do not comply, and which work perfectly with Arduino IDE 1.x, which leads the affected developers and users to the conclusion that the resulting problems are caused by a bug in the Arduino development tools, rather than an intentional decision by the Arduino developers to refrain from supporting the previously functional identifiers (e.g.,#2901).

What is the new behavior?

The requirement is formally documented in the appropriate locations in the Arduino Package Index Specification and Arduino Platform Specifications.

This will ensure that developers will have access to this important information which will allow them to produce compliant platforms.

This will ensure that those investigating problems with non-compliant platforms will be able to find the information in the expected location.

Does this PR introduce a breaking change, and istitled accordingly?

No breaking change.

Other information

Move information re: allowed characters for FQBN component to specifi…

71b5037

…cationsArduino CLI restricts which characters can be used by platform developers in their vendor, architecture, board, customboard menu, and custom board option identifiers.Previously, the information was only documented(?) in the "FAQ". This type of requirement must be present in the formalspecifications. 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 theArduino CLI application and end users have no control over which characters were used by the platform developers intheir identifiers. So the presence of the information in the FAQ only harms readability by introducing unnecessarycomplexity into a subject that users often struggle to understand.

per1234 added type: enhancement

Proposed improvement

topic: documentationRelated to documentation for the project labels

Apr 30, 2025

per1234 requested a review fromMatteoPologruto

April 30, 2025 18:15

per1234 self-assigned this

Apr 30, 2025