fqbn / Exports

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.

Table of contents

Constructors

• constructor

Properties

• arch
• boardId
• options
• vendor

Methods

• equals
• sanitize
• setConfigOption
• toString
• withConfigOptions
• withFQBN

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

Table of contents

Classes

• FQBN

Type Aliases

• ConfigOption
• ConfigValue

Functions

• valid

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