fqbn / Exports

fqbn

Arduino FQBN (fully qualified board name)

ℹ️ What's the FQBN string?

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 an ARCHITECTURE parts can be empty. For a deeper understanding of how FQBN works, you should understand the Arduino platform specification.

Table of contents

Constructors

• constructor

Properties

• arch
• boardId
• options
• vendor

Methods

• equals
• sanitize
• toString
• withConfigOptions

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. Can be any 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. Can be any empty string.

Methods

equals

▸ equals(other): boolean

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

Parameters

| Name | Type | Description | | :------ | :----------------------- | :-------------- | | other | FQBN | the other FQBN. |

Returns

boolean

true if equals. Otherwise, false.

Example

// the custom board option keys order 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

Returns a new FQBN instance without any config 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());

toString

▸ toString(skipOptions?): string

Creates the string representation of the FQBN instance.

Parameters

| Name | Type | Default value | Description | | :------------ | :-------- | :------------ | :----------------------------------------------------------------------------------------- | | skipOptions | boolean | false | when true, any custom board config options won't be serialized. It's false by default. |

Returns

string

the string representation of the FQBN.

Example

// creates 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

// can skip 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 FQBN after updating the custom board config options. Adds the new config options and updates the existing ones. New entries are appended to the end of the FQBN. Updates never changes the order.

Parameters

| Name | Type | Description | | :----------------- | :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ...configOptions | ConfigOption[] | to update the FQBN with. The config options are provided by the Arduino CLI via 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 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

// never changes the position of existing config option keys, but updates 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' });

fqbn / Exports

fqbn

Table of contents

Classes

• FQBN

Type Aliases

• ConfigOption
• ConfigValue

Functions

• valid

Type Aliases

ConfigOption

Ƭ ConfigOption: Object

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);