arduino-cli

0.37.0 • Public • Published

Arduino-cli

A javascript wrapper over the arduino-cli tool

Works on Arduino-cli 0.3.1-alpha.preview

How to use

  1. Install it with npm install -S arduino-cli or yarn add arduino-cli;
  2. Require in the code import arduinoCli from 'arduino-cli';
  3. Create an instance and pass the path to the installed arduino-cli and config:
    const cli = arduinoCli('/bin/arduino-cli', {
      directories: {
        user: '~/arduino-cli/sketches',
        data: '~/arduino-cli/data',
      },
    });
    It will create a config file for the arduino-cli in your OS temp directory and pass it to any command you'll call later.
  4. Then you can run commands, like this:
    cli.version().then(console.log); // "0.2.1-alpha.preview"

API

All commands runs asynchronously, so methods return Promises.

version()

Returns the version of arduino-cli. Wraps arduino-cli version.

  • Returns Promise<String>

dumpConfig()

Returns the current config of arduino-cli as a plain JS object. Wraps arduino-cli config dump.

  • Returns Promise<Object>

updateConfig(newConfig)

Replaces old config with the new one.

Accepts:

  • newConfig <Object> — Plain JS object representation of .cli-config.yml

  • Returns <Object> with the new config

listConnectedBoards()

A wrapper with a custom extension over arduino-cli board list.

Custom extension may be removed in the future. See issue #45

Returns a plain JS object which describes boards connected through serial ports. Also, it extends boards' FQBN with cpu option from boards.txt if a board is identified (a package installed) and has some options. For example, Arduino Nano will be transformed into three items with a modified FQBN and name.

  • Returns Promise<Array<ConnectedBoard>>

listInstalledBoards()

A wrapper with a custom extension over arduino-cli board listall.

Custom extension may be removed in the future. See issue #45

Returns a plain JS object with boards, whose packages are installed. Also, it extends boards' FQBN with cpu option from boards.txt if a board is identified (a package installed) and it has some options. For example, Arduino Nano will be transformed into three items with a modified FQBN and name.

  • Returns Promise<Array<InstalledBoard>>

listAvailableBoards()

Returns a list of all boards that found in all package_*_index.json files.

  • Returns Promise<Array<AvailableBoard>>

setPackageIndexUrls(urls)

Sets a list of additional package index urls into the config file. Later you can download and install packages with arduino-cli (call core.updateIndex()).

Accepts:

  • urls <Array<String>> — List of URLs of the third-party package_*_index.json files

  • Returns Promise<Array<String>> with just added URLs

core.download(progressCallback, packageName)

Wraps arduino-cli core download packageName. Downloads core and tool archives for the specified package.

Accepts:

  • progressCallback <Function> — A function that will be called on progress with one argument <ProgressData>. See details below.

  • packageName <String> — A package and architecture to download. May contain a version. For example, arduino:avr or arduino:avr@1.6.9

  • Returns Promise<String> — log

core.install(progressCallback, packageName)

Wraps arduino-cli core install packageName. Downloads and installs core and tool archives for the specified package.

Accepts:

  • progressCallback <Function> — A function that will be called on progress with one argument <ProgressData>. See details below.

  • packageName <String> — A package and architecture to install. May contain a version. For example, arduino:avr or arduino:avr@1.6.9

  • Returns Promise<String> — log

core.list()

Wraps arduino-cli core list. Returns a list of installed packages.

  • Returns Promise<Array<InstalledPackages>>

core.search(query)

Wraps arduino-cli core search query. Returns a list of packages found.

Accepts:

  • query <String> — A search query

  • Returns Promise<Array<FoundPackages>>

core.uninstall(packageName)

Wraps arduino-cli core uninstall packageName. Uninstalls the core and tools for the specified package.

Accepts:

  • packageName <String> — A package identifier, like arduino:samd

  • Returns Promise<String> — a log

core.updateIndex()

Wraps arduino-cli core update-index. Downloads the original package_index.json and additional package index files.

  • Returns Promise<String> — a log

createSketch(sketchName)

Wraps arduino-cli sketch new sketchName. Creates an empty sketchName/sketchName.ino inside the sketchbook directory.

  • Returns Promise<String> — a full path to the created .ino file

compile(onProgress, fqbn, sketchName[, verbose])

Wraps arduino-cli compile. Compiles the sketch for the specified board.

Accepts:

  • onProgress <Function> — A function that is called on new data in stdout

  • fqbn <String> — A fully-qualified board name. Like arduino:avr:mega:cpu=atmega2560

  • sketchName <String> — A name of the sketch in the sketchbook directory. It can contain sketch name or full path to the sketch.

  • verbose <Boolean> — Verbose output. By default is false

  • Returns Promise<String> with a log of the compilation process

upload(onProgress, port, fqbn, sketchName[, verbose])

Wraps arduino-cli upload. Uploads the compiled sketch onto the board.

Accepts:

  • onProgress <Function> — A function that is called on new data in stdout with a single argument

  • port <String> — A port name (e.g., COM3 or /dev/tty.usbmodem1411)

  • fqbn <String> — A fully-qualified board name. Like arduino:avr:mega:cpu=atmega2560

  • sketchName <String> — A name of the sketch in the sketchbook directory. It can contain sketch name or full path to the sketch.

  • verbose <Boolean> — Verbose output. By default is false

  • Returns Promise<String> with a log of the upload process

getRunningProcesses()

Returns a list of running arduino-cli processes.

  • Returns Array<ChildProcess>

killProcesses()

Kills all running arduino-cli processes.

  • Returns Boolean true

Types

ConnectedBoard

  • name <String> — A board name with an added cpu option, if it exists For example, "Arduino/Genuino Uno" or "Arduino/Genuino Mega2560 (ATmega2560 (Mega 2560))"
  • fqbn <String> — A fully-qualified board name For example, arduino:avr:uno or arduino:avr:mega2560:cpu=atmega2560
  • port <String> — A port name. Like /dev/tty.usbmodem1411
  • usbID String — An ID of the board (VID, PID). For example, 2341:0042

InstalledBoard

  • name <String> — A board name E.G. "Arduino/Genuino Uno" or "Arduino/Genuino Mega2560"
  • fqbn <String> — A fully-qualified board name E.G. "arduino:avr:uno" or "arduino:avr:mega2560"
  • options <Array<Option>> — a list of options for this board

Option

Object, that represents one group of the board option. For example, CPU Frequency.

  • optionName <String> — A human-readable name of the option group ("CPU Frequency")
  • optionId <String> — An id of the option from boards.txt. E.G. CpuFrequency
  • values <Array<OptionValue>> — a list of option values, that represented as objects with two fields
    • name <String> — A human-readable option name ("80 MHz")
    • value <String> — A value, that will be used by tools. ("80")

AvailableBoard

  • name <String> — A board name (e.g., "Arduino/Genuino Mega2560")
  • package <String> — A package and architecture, that could be used in the core.install command. For example, arduino:avr
  • packageName <String> — A human-readable architecture name. Like "Arduino AVR Boards"
  • version <String> — A Semver of the latest architecture for this board (e.g., 1.6.21)

ProgressData

  • message <String> — A progress message from stdout of the arduino-cli. In case that there is a downloading process that shows progress bar, it will be null, because this type of progress should notify only about a percentage.
  • percentage <Number> — A number in the range [0.00...100.00]
  • estimated <String> — An estimated time in the format 3m52s or unknown

InstalledPackages

  • ID <String> — A package identifier in format package:architecture (e.g., arduino:avr)
  • Installed <String> — A version of the installed package
  • Latest <String> — A version of the latest package
  • Name <String> — A human-readable name of the architecture

FoundPackages

  • ID <String> — A package identifier in format package:architecture (e.g., arduino:avr)
  • Version <String> — A version of the latest package
  • Installed <String> — Equals "Yes" if the package is installed, otherwise "No"
  • Name <String> — A name of the architecture

Readme

Keywords

Package Sidebar

Install

npm i arduino-cli

Weekly Downloads

4

Version

0.37.0

License

AGPL-3.0

Unpacked Size

78 kB

Total Files

17

Last publish

Collaborators

  • nailxx
  • brusher
  • evgenykochetkov