fqbn

Arduino FQBN (Fully Qualified Board Name)

ⓘ What's the FQBN string?

ⓘ This library is based on the official implementation of FQBN written in Go

Install

npm install fqbn

Usage

CommonJS:

const { FQBN, valid } = require('fqbn');

TypeScript:

import { FQBN, valid } from 'fqbn';

fqbn / Exports / FQBN

Class: FQBN

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.

Constructors

constructor

• new FQBN(fqbn): FQBN

Creates a new FQBN instance after parsing the raw FQBN string—errors when the FQBN string is invalid.

Parameters

Name	Type	Description
`fqbn`	`string`	the raw FQBN string to parse

Returns

FQBN

Example

// Valid FQBN.
const fqbn1 = new FQBN('arduino:samd:mkr1000');
assert.ok(fqbn1);
assert.strictEqual(fqbn1.vendor, 'arduino');
assert.strictEqual(fqbn1.arch, 'samd');
assert.strictEqual(fqbn1.boardId, 'mkr1000');
assert.strictEqual(fqbn1.options, undefined);

Example

// Valid FQBN with custom board options.
const fqbn2 = new FQBN('arduino:samd:mkr1000:o1=v1');
assert.ok(fqbn2);
assert.strictEqual(fqbn2.vendor, 'arduino');
assert.strictEqual(fqbn2.arch, 'samd');
assert.strictEqual(fqbn2.boardId, 'mkr1000');
assert.deepStrictEqual(fqbn2.options, { o1: 'v1' });

Example

// Invalid FQBN.
assert.throws(() => new FQBN('invalid'));

Properties

arch

• Readonly arch: string

The architecture of the board. It can be an empty string.

boardId

• Readonly boardId: string

The unique board identifier per vendor and architecture.

options

• Optional Readonly options: Readonly<Record<string, string>>

Optional custom board options and their selected values.

vendor

• Readonly vendor: string

The vendor identifier. It can be an empty string.

Methods

equals

▸ equals(other): boolean

true if the other FQBN equals this. The key order of the custom board configuration options is insignificant.

Parameters

Name	Type	Description
`other`	`FQBN`	the other FQBN.

Returns

boolean

true if equals. Otherwise, false.

Example

// The key order of the custom board configuration options is insignificant when comparing two FQBNs.
assert.ok(
  new FQBN('arduino:samd:mkr1000:o1=v1,o2=v2').equals(
    new FQBN('arduino:samd:mkr1000:o2=v2,o1=v1')
  )
);

sanitize

▸ sanitize(): FQBN

This function returns a new FQBN instance that does not include any configuration options.

Returns

FQBN

the new FQBN

Example

// Removes the custom board config options.
assert.strictEqual(
  new FQBN('arduino:samd:mkr1000:o1=v1,o2=v2').sanitize().toString(),
  'arduino:samd:mkr1000'
);

Example

// Returns the same instance when no custom board options are available.
const fqbn = new FQBN('arduino:samd:mkr1000');
assert.ok(fqbn === fqbn.sanitize());

setConfigOption

▸ setConfigOption(option, value, strict?): FQBN

Sets the configuration option to a specified value and returns a new FQBN instance.

FQBNs are immutable, ensuring that existing configuration option keys are maintained in their original positions during the update. By default, it operates in non-strict mode, which allows for the insertion of new configuration values without error. If strict mode is enabled, any attempt to set a value for an absent configuration option will result in an error.

Parameters

Name	Type	Default value	Description
`option`	`string`	`undefined`	the config option identifier to update.
`value`	`string`	`undefined`	the selected configuration option value to set.
`strict?`	`boolean`	`false`	Optional parameter to enable strict mode.

Returns

FQBN

Example

// Sets the configuration option to a specified value.
const fqbn1 = new FQBN('arduino:samd:mkr1000:o1=v1');
const fqbn2 = fqbn1.setConfigOption('o1', 'v2');
assert.strictEqual(fqbn2.vendor, 'arduino');
assert.strictEqual(fqbn2.arch, 'samd');
assert.strictEqual(fqbn2.boardId, 'mkr1000');
assert.deepStrictEqual(fqbn2.options, { o1: 'v2' });

Example

// FQBNs are immutable.
assert.deepStrictEqual(fqbn1.options, { o1: 'v1' });
assert.deepStrictEqual(fqbn2.options, { o1: 'v2' });

Example

// Always maintains the position of existing configuration option keys while updating the value.
assert.strictEqual(
  new FQBN('arduino:samd:mkr1000:o1=v1,o2=v2')
    .setConfigOption('o1', 'v2')
    .toString(),
  'arduino:samd:mkr1000:o1=v2,o2=v2'
);

Example

// Inserts new configuration values by default (non-strict mode).
assert.strictEqual(
  new FQBN('arduino:samd:mkr1000').setConfigOption('o1', 'v2').toString(),
  'arduino:samd:mkr1000:o1=v2'
);

Example

// In strict mode, it throws an error when setting absent configuration option values.
assert.throws(() =>
  new FQBN('arduino:samd:mkr1000').setConfigOption('o1', 'v2', true)
);

toString

▸ toString(skipOptions?): string

Generates the string representation of the FQBN instance.

Parameters

Name	Type	Default value	Description
`skipOptions`	`boolean`	`false`	When set to `true`, any custom board configuration options will not be serialized. The default value is `false`.

Returns

string

The resulting string representation of the FQBN.

Example

// Generates the string representation of the FQBN.
assert.strictEqual(
  new FQBN('arduino:samd:mkr1000').toString(),
  'arduino:samd:mkr1000'
);

Example

// Keeps the order of the custom board option keys.
assert.strictEqual(
  new FQBN('arduino:samd:mkr1000:o1=v1').toString(),
  'arduino:samd:mkr1000:o1=v1'
);

Example

// Skips the config options from the serialization.
assert.strictEqual(
  new FQBN('arduino:samd:mkr1000:o1=v1').toString(true),
  'arduino:samd:mkr1000'
);

withConfigOptions

▸ withConfigOptions(...configOptions): FQBN

Creates an immutable copy of the current Fully Qualified Board Name (FQBN) after updating the custom board configuration options. Adds new configuration options and updates the existing ones. New entries are appended to the end of the FQBN, while the order of the existing options remains unchanged.

Parameters

Name	Type	Description
`...configOptions`	readonly `ConfigOption`[]	Configuration options to update the FQBN. These options are provided by the Arduino CLI through the gRPC equivalent of the `board --details` command.

Returns

FQBN

Example

// Creates a new FQBN instance by appending the custom board options to the end of the original FQBN.
const fqbn1 = new FQBN('arduino:samd:mkr1000');
const fqbn2 = fqbn1.withConfigOptions({
  option: 'o1',
  values: [
    { value: 'v1', selected: true },
    { value: 'v2', selected: false },
  ],
});
assert.strictEqual(fqbn2.vendor, 'arduino');
assert.strictEqual(fqbn2.arch, 'samd');
assert.strictEqual(fqbn2.boardId, 'mkr1000');
assert.deepStrictEqual(fqbn2.options, { o1: 'v1' });

Example

// FQBNs are immutable.
assert.strictEqual(fqbn1.options, undefined);
assert.ok(fqbn2.options);

Example

// Always maintains the position of existing configuration option keys while updating the selected value.
const fqbn3 = fqbn2.withConfigOptions(
  {
    option: 'o1',
    values: [
      { value: 'v1', selected: false },
      { value: 'v2', selected: true },
    ],
  },
  {
    option: 'o2',
    values: [
      { value: 'v2', selected: true },
      { value: 'w2', selected: false },
    ],
  }
);
assert.deepStrictEqual(fqbn3.options, { o1: 'v2', o2: 'v2' });

withFQBN

▸ withFQBN(fqbn): FQBN

Creates an immutable copy of the current Fully Qualified Board Name (FQBN) after updating the custom board configuration options extracted from another FQBN. New configuration options are added, and existing ones are updated accordingly. New entries are appended to the end of the FQBN, while the order of the existing options remains unchanged. If a configuration option is present in the current FQBN but absent in the other, the configuration option will still remain in place. Note that errors will occur if the FQBNs do not match.

Parameters

Name	Type	Description
`fqbn`	`string`	the other FQBN to merge in

Returns

FQBN

Example

// Creates a new FQBN instance by appending the custom board options extracted from the other FQBN to the end of the original FQBN.
const fqbn1 = new FQBN('arduino:samd:mkr1000');
const fqbn2 = fqbn1.withFQBN('arduino:samd:mkr1000:o1=v1');
assert.strictEqual(fqbn2.vendor, 'arduino');
assert.strictEqual(fqbn2.arch, 'samd');
assert.strictEqual(fqbn2.boardId, 'mkr1000');
assert.deepStrictEqual(fqbn2.options, { o1: 'v1' });

Example

// FQBNs are immutable.
assert.strictEqual(fqbn1.options, undefined);
assert.ok(fqbn2.options);

Example

// Always maintains the position of existing configuration option keys while updating the selected value.
const fqbn3 = fqbn2.withFQBN('arduino:samd:mkr1000:o2=v2,o1=v2');
assert.deepStrictEqual(fqbn3.options, { o1: 'v2', o2: 'v2' });
assert.deepStrictEqual(fqbn3.toString(), 'arduino:samd:mkr1000:o1=v2,o2=v2');

Example

// Never removes config options.
const fqbn4 = fqbn3.withFQBN('arduino:samd:mkr1000');
assert.deepStrictEqual(fqbn4.options, { o1: 'v2', o2: 'v2' });
assert.deepStrictEqual(fqbn4.toString(), 'arduino:samd:mkr1000:o1=v2,o2=v2');

Example

// Errors on mismatching FQBNs.
assert.throws(() => fqbn4.withFQBN('arduino:avr:uno:o1=v3'));

fqbn / Exports

fqbn

Type Aliases

ConfigOption

Ƭ ConfigOption: Object

A lightweight representation of a custom board config option provided by the Arduino CLI.

Type declaration

Name	Type	Description
`option`	`string`	ID of the configuration option. For identifying the option to machines.
`optionLabel?`	`string`	Name of the configuration option for identifying the option to humans.
`values`	readonly `ConfigValue`[]	Possible values of the configuration option.

ConfigValue

Ƭ ConfigValue: Object

The bare minimum representation of the ConfigValue provided by the CLI via the gRPC equivalent of the board --details command.

Type declaration

Name	Type	Description
`selected`	`boolean`	Whether the configuration option is selected.
`value`	`string`	The configuration option value.
`valueLabel?`	`string`	Label to identify the configuration option to humans.

Functions

valid

▸ valid(fqbn): FQBN | undefined

Returns the parsed FQBN if valid. Otherwise, undefined.

Parameters

Name	Type	Description
`fqbn`	`string`	the FQBN string.

Returns

FQBN | undefined

the parsed FQBN or undefined.

Example

// Valid FQBN.
assert.ok(valid('arduino:samd:mkr1000') instanceof FQBN);

Example

// Invalid FQBN.
assert.strictEqual(valid('invalid'), undefined);

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.github/workflows		.github/workflows
.vscode		.vscode
docs		docs
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.mocharc.json		.mocharc.json
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
release.config.js		release.config.js
tsconfig.json		tsconfig.json
typedoc.config.js		typedoc.config.js

License

dankeboy36/fqbn

Folders and files

Latest commit

History

Repository files navigation

fqbn

Install

Usage

Class: FQBN

Table of contents

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns

Properties

arch

boardId

options

vendor

Methods

equals

Parameters

Returns

sanitize

Returns

setConfigOption

Parameters

Returns

toString

Parameters

Returns

withConfigOptions

Parameters

Returns

withFQBN

Parameters

Returns

fqbn

Table of contents

Classes

Type Aliases

Functions

Type Aliases

ConfigOption

Type declaration

ConfigValue

Type declaration

Functions

valid

Parameters

Returns

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 12

Contributors 2

Languages