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

per1234 · 2025-04-30T18:15:25Z

Please check if the PR fulfills these requirements

The PR has no duplicates (please search among the Pull 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 in faf79a7

    
           var fqbnValidationRegex = regexp.MustCompile(`^[a-zA-Z0-9_.-]*$`) 
        
           var valueValidationRegex = regexp.MustCompile(`^[a-zA-Z0-9=_.-]*$`) 
        
           // Parse parses an FQBN string from the input string 
        
           func Parse(fqbnIn string) (*FQBN, error) { 
        
           	// Split fqbn parts 
        
           	fqbnParts := strings.Split(fqbnIn, ":") 
        
           	if len(fqbnParts) < 3 || len(fqbnParts) > 4 { 
        
           		return nil, errors.New(i18n.Tr("not an FQBN: %s", fqbnIn)) 
        
           	} 
        
           	fqbn := &FQBN{ 
        
           		Vendor:       fqbnParts[0], 
        
           		Architecture: fqbnParts[1], 
        
           		BoardID:      fqbnParts[2], 
        
           		Configs:      properties.NewMap(), 
        
           	} 
        
           	if fqbn.BoardID == "" { 
        
           		return nil, errors.New(i18n.Tr("empty board identifier")) 
        
           	} 
        
           	// Check if the fqbn contains invalid characters 
        
           	for i := 0; i < 3; i++ { 
        
           		if !fqbnValidationRegex.MatchString(fqbnParts[i]) { 
        
           			return nil, errors.New(i18n.Tr("fqbn's field %s contains an invalid character", fqbnParts[i])) 
        
           		} 
        
           	} 
        
           	if len(fqbnParts) > 3 { 
        
           		for _, pair := range strings.Split(fqbnParts[3], ",") { 
        
           			parts := strings.SplitN(pair, "=", 2) 
        
           			if len(parts) != 2 { 
        
           				return nil, errors.New(i18n.Tr("invalid config option: %s", pair)) 
        
           			} 
        
           			k := strings.TrimSpace(parts[0]) 
        
           			v := strings.TrimSpace(parts[1]) 
        
           			if k == "" { 
        
           				return nil, errors.New(i18n.Tr("invalid config option: %s", pair)) 
        
           			} 
        
           			if !fqbnValidationRegex.MatchString(k) { 
        
           				return nil, errors.New(i18n.Tr("config key %s contains an invalid character", k)) 
        
           			} 
        
           			// The config value can also contain the = symbol 
        
           			if !valueValidationRegex.MatchString(v) { 
        
           				return nil, errors.New(i18n.Tr("config value %s contains an invalid character", v)) 
        
           			} 
        
           			fqbn.Configs.Set(k, v) 
        
           		} 
        
           	} 
        
           	return fqbn, 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 is titled accordingly?

No breaking change.

Other information

…cations 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.

per1234 added type: enhancement Proposed improvement topic: documentation Related to documentation for the project labels Apr 30, 2025

per1234 requested a review from MatteoPologruto April 30, 2025 18:15

per1234 self-assigned this Apr 30, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

per1234 commented Apr 30, 2025

	var fqbnValidationRegex = regexp.MustCompile(`^[a-zA-Z0-9_.-]*$`)
	var valueValidationRegex = regexp.MustCompile(`^[a-zA-Z0-9=_.-]*$`)

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

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

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

Are you sure you want to change the base?

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

Conversation

per1234 commented Apr 30, 2025

Please check if the PR fulfills these requirements

What kind of change does this PR introduce?

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change, and is titled accordingly?

Other information