Skip to content
Arduino command line interface
Go C++ C Python Shell Dockerfile
Branch: master
Clone or download
cmaglie GRPC serial monitor: Fix unhandled error (`EINTR`) that leaves serial…
… port open (#507)

* Update go-serial library to latest version

Includes a fix to serial.Read method.

Should fix: #504

Actual patch: bugst/go-serial#69

* Using versioned release of go.bug.st/serial
Latest commit 2049a7a Dec 6, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.dependabot [ci skip] fix label name (#289) Jul 18, 2019
.github [skip ci] fix stalebot (#476) Nov 13, 2019
Dockerfiles/builder Bump golang version to 1.13 (#412) Sep 20, 2019
arduino GRPC serial monitor: Fix unhandled error (`EINTR`) that leaves serial… Dec 6, 2019
cli Added library dependency support (#351) Nov 27, 2019
client_example [skip changelog] gRPC "client_example" refresh (#434) Oct 3, 2019
commands GRPC serial monitor: Fix unhandled error (`EINTR`) that leaves serial… Dec 6, 2019
configs [skip changelog] Migrate tests to GH actions (#352) Aug 28, 2019
executils Updated license Aug 7, 2018
legacy/builder Auto-disable (deep) caching of core builds if needed (#479) Nov 11, 2019
rpc Added library dependency support (#351) Nov 27, 2019
table Rewrite the output system (#345) Aug 28, 2019
test Look for query string into more fields when searching for libs (#499) Dec 4, 2019
version
.codecov.yml [skip changelog] Add coverage for legacy tests (#390) Sep 3, 2019
.editorconfig Add install script and update install instructions (#324) Aug 6, 2019
.gitignore Command `sketch new` do not join sketchbook path to sketch name if on… Sep 11, 2019
.goreleaser.yml [skip changelog] better match for skip clauses (#449) Oct 22, 2019
CONTRIBUTING.md [skip changelog] Allow running specific unit tests (#466) Nov 5, 2019
LICENSE.txt Updated license Aug 7, 2018
README.md [ci skip] document config file (#492) Nov 21, 2019
Taskfile.yml [skip changelog] Allow running specific unit tests (#466) Nov 5, 2019
go.mod GRPC serial monitor: Fix unhandled error (`EINTR`) that leaves serial… Dec 6, 2019
go.sum GRPC serial monitor: Fix unhandled error (`EINTR`) that leaves serial… Dec 6, 2019
install.sh [ci skip] use unzip on Windows (#498) Nov 28, 2019
main.go Rewrite the output system (#345) Aug 28, 2019

README.md

arduino-cli

Tests passing Nightly build codecov

arduino-cli is an all-in-one solution that provides builder, boards/library manager, uploader, discovery and many other tools needed to use any Arduino compatible board and platforms.

This software is currently under active development: anything can change at any time, API and UI must be considered unstable.

How to contribute

Contributions are welcome!

Please read the document How to contribute which will guide you through how to build the source code, run the tests, and contribute your changes to the project.

Thanks to all our contributors!

How to install

Get the latest package

You have several options to install the latest version of the Arduino CLI on your system.

Install via Homebrew (macOS/Linux)

The Arduino CLI is available as a Homebrew formula since version 0.5.0:

brew update
brew install arduino-cli

Use the install script

The easiest way to get the latest version of arduino-cli on any supported platform is using the install.sh script:

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

The script will install arduino-cli at $PWD/bin, if you want to target a different directory, for example ~/local/bin, set the BINDIR environment variable like this:

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/local/bin sh

Download the latest packages from Arduino CDN

In order to get the latest stable release for your platform you can use the following links:

These links return a 302: Found response, redirecting to latest generated builds by replacing latest with the latest available stable release. Once downloaded, place the executable arduino-cli into a directory which is in your PATH.

Deprecation notice: Links in the form http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-<platform>.tar.bz2 won't be further updated. That URL will provide arduino-cli 0.3.7-alpha.preview, regardless of further releases.

Download the latest package from the release page on GitHub

Alternatively you can download one of the pre-built binaries for the supported platforms from the release page. Once downloaded, place the executable arduino-cli into a directory which is in your PATH.

Get a nightly build

These builds are generated once a day from master branch starting at 01:00 GMT. In order to get the latest nightly build for your platform, use the following links:

These links return a 302: Found response, redirecting to latest generated builds by replacing latest with the latest available build date, using the format YYYYMMDD (i.e for 2019/Aug/06 latest is replaced with 20190806 )

Checksums for the nightly builds are available at https://downloads.arduino.cc/arduino-cli/nightly/nightly-<DATE>-checksums.txt

Once downloaded, place the executable arduino-cli into a directory which is in your PATH.

Build from source using Docker

If you don't have a working Golang environment or if you want to build arduino-cli targeting different platforms, you can use Docker to get a binary directly from sources. From the project folder run:

docker run -v $PWD:/arduino-cli -w /arduino-cli -e PACKAGE_NAME_PREFIX='snapshot' arduino/arduino-cli:builder-1 goreleaser --rm-dist --snapshot --skip-publish

Once the build is over, you will find a ./dist/ folder containing the packages built out of the current source tree.

Build from source

If you're familiar with Golang or if you want to contribute to the project, you will probably build the arduino-cli locally with your Go compiler. Please refer to the contributing doc for setup instructions.

Getting Started

The goal of the Arduino CLI is to be used by either including it in Makefile or in any kind of script for the Command Line. The Arduino CLI aims to replace the majority of features the Arduino IDE has without the graphical UI.

Step 1. Create a new sketch

The command will create a new empty sketch named MyFirstSketch in the current directory

$ arduino-cli sketch new MyFirstSketch
Sketch created in: /home/luca/MyFirstSketch

$ cat /home/luca/MyFirstSketch/MyFirstSketch.ino
void setup() {
}

void loop() {
}

Step 2. Modify your sketch

Use your favourite file editor or IDE to modify the .ino file, in this example under: $HOME/MyFirstSketch/MyFirstSketch.ino and change the file to look like this one:

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}

Step 3. Connect the board to your PC

If you are running a fresh install of the arduino-cli you probably need to update the platform indexes by running:

$ arduino-cli core update-index
Updating index: package_index.json downloaded

Now, just connect the board to your PCs by using the USB cable. (Note: Connecting through an FTDI adapter chip will show Unknown for the Board Name because the VID/PID is generic. Uploading should still work as long as you identify the correct FQBN). In this example we will use the MKR1000 board:

$ arduino-cli board list
Port         Type              Board Name              FQBN                 Core
/dev/ttyACM1 Serial Port (USB) Arduino/Genuino MKR1000 arduino:samd:mkr1000 arduino:samd

the board has been discovered but we need the correct core to program it, let's install it!

Step 4. Install the core for your board

From the output of the board list command, the right platform for the Arduino MKR1000 is arduino:samd, we can install it with:

$ arduino-cli core install arduino:samd
Downloading tools...
arduino:arm-none-eabi-gcc@4.8.3-2014q1 downloaded
arduino:bossac@1.7.0 downloaded
arduino:openocd@0.9.0-arduino6-static downloaded
arduino:CMSIS@4.5.0 downloaded
arduino:CMSIS-Atmel@1.1.0 downloaded
arduino:arduinoOTA@1.2.0 downloaded
Downloading cores...
arduino:samd@1.6.19 downloaded
Installing tools...
Installing platforms...
Results:
arduino:samd@1.6.19 - Installed
arduino:arm-none-eabi-gcc@4.8.3-2014q1 - Installed
arduino:bossac@1.7.0 - Installed
arduino:openocd@0.9.0-arduino6-static - Installed
arduino:CMSIS@4.5.0 - Installed
arduino:CMSIS-Atmel@1.1.0 - Installed
arduino:arduinoOTA@1.2.0 - Installed

Now verify we have installed the core properly by running

$ arduino-cli core list
ID              Installed       Latest  Name
arduino:samd    1.6.19          1.6.19  Arduino SAMD Boards (32-bits ARM Cortex-M0+)

If the board is not detected for any reason, you can list all the supported boards with arduino-cli board listall and also search for a specific board:

$ arduino-cli board listall mkr
Board Name              FQBN
Arduino MKR FOX 1200    arduino:samd:mkrfox1200
Arduino MKR GSM 1400    arduino:samd:mkrgsm1400
Arduino MKR WAN 1300    arduino:samd:mkrwan1300
Arduino MKR WiFi 1010   arduino:samd:mkrwifi1010
Arduino MKRZERO         arduino:samd:mkrzero
Arduino/Genuino MKR1000 arduino:samd:mkr1000

Great! Now we are ready to compile and upload the sketch.

Adding 3rd party cores

To use 3rd party core packages, pass a link to the the additional package index file with the --additional-urls option to any command that supports additional cores:

$ arduino-cli core update-index --additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json
$
$ arduino-cli core search esp8266 --additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json
ID              Version Name
esp8266:esp8266 2.5.2   esp8266

To avoid passing the --additional-urls option every time you run a command, you can list the URLs to additional package indexes in the CLI configuration file. If you don't have a configuration file yet (it's the case of a fresh install) you can create one with the command:

$ arduino-cli config init
Config file PATH: /home/user/.arduino15/arduino-cli.yaml

This will create a configuration file in its default location for the current operating system and will print the full path to the file.

For example, to add the ESP8266 core, edit the configration file and add the following:

board_manager:
  additional_urls:
    - http://arduino.esp8266.com/stable/package_esp8266com_index.json

From now on, commands supporting custom cores will automatically use the additional URL from the configuration file:

$ arduino-cli core update-index
Updating index: package_index.json downloaded
Updating index: package_esp8266com_index.json downloaded
Updating index: package_index.json downloaded

$ arduino-cli core search esp8266
ID              Version Name
esp8266:esp8266 2.5.2   esp8266

Step 5. Compile the sketch

To compile the sketch we have to run the compile command with the proper FQBN we just got in the previous command.

$ arduino-cli compile --fqbn arduino:samd:mkr1000 MyFirstSketch
Sketch uses 9600 bytes (3%) of program storage space. Maximum is 262144 bytes.

Step 6. Upload your sketch

We can finally upload the sketch and see our board blinking, we now have to specify the serial port used by our board other than the FQBN:

$ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 MyFirstSketch
No new serial port detected.
Atmel SMART device 0x10010005 found
Device       : ATSAMD21G18A
Chip ID      : 10010005
Version      : v2.0 [Arduino:XYZ] Dec 20 2016 15:36:43
Address      : 8192
Pages        : 3968
Page Size    : 64 bytes
Total Size   : 248KB
Planes       : 1
Lock Regions : 16
Locked       : none
Security     : false
Boot Flash   : true
BOD          : true
BOR          : true
Arduino      : FAST_CHIP_ERASE
Arduino      : FAST_MULTI_PAGE_WRITE
Arduino      : CAN_CHECKSUM_MEMORY_BUFFER
Erase flash
done in 0.784 seconds

Write 9856 bytes to flash (154 pages)
[==============================] 100% (154/154 pages)
done in 0.069 seconds

Verify 9856 bytes of flash with checksum.
Verify successful
done in 0.009 seconds
CPU reset.

Step 7. Add libraries

Now we can try to add a useful library to our sketch. We can at first look at the name of a library, our favourite one is the wifi101, here the command to get more info:

$ arduino-cli lib search wifi101
Name: "WiFi101OTA"
  Author:  Arduino
  Maintainer:  Arduino <info@arduino.cc>
  Sentence:  Update sketches to your board over WiFi
  Paragraph:  Requires an SD card and SAMD board
  Website:  http://www.arduino.cc/en/Reference/WiFi101OTA
  Category:  Other
  Architecture:  samd
  Types:  Arduino
  Versions:  [1.0.2, 1.0.0, 1.0.1]
Name: "WiFi101"
  Author:  Arduino
  Maintainer:  Arduino <info@arduino.cc>
  Sentence:  Network driver for ATMEL WINC1500 module (used on Arduino/Genuino Wifi Shield 101 and MKR1000 boards)
  Paragraph:  This library implements a network driver for devices based on the ATMEL WINC1500 wifi module
  Website:  http://www.arduino.cc/en/Reference/WiFi101
  Category:  Communication
  Architecture:  *
  Types:  Arduino
  Versions:  [0.5.0, 0.6.0, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.15.2, 0.8.0, 0.9.0, 0.12.1, 0.14.1, 0.14.4, 0.14.5, 0.15.1, 0.7.0, 0.14.0, 0.14.2, 0.14.3, 0.9.1, 0.13.0, 0.15.0, 0.5.1]

We are now ready to install it! Please be sure to use the full name of the lib as specified in the "Name:" section previously seen:

$ arduino-cli lib install "WiFi101"
Downloading libraries...
WiFi101@0.15.2 downloaded
Installed WiFi101@0.15.2

Inline Help

arduino-cli is a container of commands, to see the full list just run:

$ arduino-cli
Arduino Command Line Interface (arduino-cli).

Usage:
  arduino-cli [command]

Examples:
arduino <command> [flags...]

Available Commands:
  board         Arduino board commands.
  compile       Compiles Arduino sketches.
  config        Arduino Configuration Commands.
  core          Arduino Core operations.
  help          Help about any command
  lib           Arduino commands about libraries.
  sketch        Arduino CLI Sketch Commands.
  upload        Upload Arduino sketches.
  version       Shows version number of Arduino CLI.
  ....

Each command has his own specific help that can be obtained with the help command, for example:

$ arduino-cli help core
Arduino Core operations.

Usage:
  arduino-cli core [command]

Examples:
arduino-cli core update-index # to update the package index file.

Available Commands:
  download     Downloads one or more cores and corresponding tool dependencies.
  install      Installs one or more cores and corresponding tool dependencies.
  list         Shows the list of installed cores.
  update-index Updates the index of cores.

Flags:
  -h, --help   help for core

Global Flags:
      --config-file string   The custom config file (if not specified the default one will be used).
      --debug                Enables debug output (super verbose, used to debug the CLI).
      --format string        The output format, can be [text|json]. (default "text")

Use "arduino-cli core [command] --help" for more information about a command.

FAQ

Why the Arduino Uno/Mega/Duemilanove is not detected when I run arduino-cli board list?

Because:

  • Your board is a cheaper clone, or
  • It mounts a USB2Serial converter like FT232 or CH320: these chips always reports the same USB VID/PID to the operating system, so the only thing that we know is that the board mounts that specific USB2Serial chip, but we don't know which board is.

What is the core for the Uno/Mega/Nano/Duemilanove?

arduino:avr

What is the FQBN for ...?

  • Arduino UNO: arduino:avr:uno
  • Arduino Mega: arduino:avr:mega
  • Arduino Nano: arduino:avr:nano or arduino:avr:nano:cpu=atmega328old if you have the old bootloader

How can I find the core/FQBN for a board?

Update the core index to have latest boards informations:

$ arduino-cli core update-index
Updating index: package_index.json downloaded

See: https://github.com/arduino/arduino-cli#step-4-find-and-install-the-right-core

Further help can be found in this comment in #138.

For a deeper understanding of how FQBN works, you should understand Arduino Hardware specification. You can find more information in this arduino/Arduino wiki page

Using the gRPC interface

The client_example folder contains a sample program that shows how to use gRPC interface of the CLI.

You can’t perform that action at this time.