Arduino CLI Tutorial

Introduction

There is an official Arduino CLI application that allows you to compile and upload sketches from the command-line without IDE.

This guide will walk through the process of installing and configuring the CLI tool as well as compiling and uploading sketches. It will also cover third-party boards and libraries like the ESP8266 and Adafruit PyPortal.

Read the official documentation and view the source code at https://github.com/arduino/arduino-cli.

Install arduino-cli

You can either download the pre-built binary or build it from source yourself. It is written in Go so it generates a single statically linked executable.

Download the official pre-built release for Windows, Linux, Mac, or ARM from the arduino-cli releases page on GitHub. After downloading it, Unzip it and put the binary file in a directory that is in your PATH. Rename to arduino-cli for convenience.

Alternatively, if you want to build it from source (maybe unstable), you will need Go installed. Then run the go get command shown below and the binary will be in your $GOPATH/bin or $GOBIN directory.

go get -u github.com/arduino/arduino-cli

Setup

Before compiling and uploading sketches there is some setup to do. You will need to:

  • Update the board index that tracks all available boards you can install support for
  • Search for the proper "core" (board support)
  • Install the core support

Once you have done these steps, you can compile and upload sketches. Let's look at each of the setup steps individually.

Update board index

Before doing anything, update the index of boards by running:

arduino-cli core update-index

Search for board support

You can search for available cores using arduino-cli core search. Some example searches:

arduino-cli core search arduino
arduino-cli core search leonardo
arduino-cli core search uno
arduino-cli core search samd

In this example, I am using a TinyLab which has an Arduino Leonardo board that uses the arduino:avr core, just like an Arduino Duemilanove. Boards that have an SAMD21/SAMD51 chip use the arduino:samd core.

Install board support

After finding the ID of the platform you need, in my case, arduino:avr you need to install it. You can do that like this:

# Arduino board support like Leonardo/Uno
arduino-cli core install arduino:avr
# Or if you need SAMD21/SAMD51 support:
arduino-cli core install arduino:samd

Verify installed cores with:

arduino-cli core list

To get a complete list of all boards supported by your installed cores, use:

arduino-cli board listall

Install third-party board support

To add third-party boards like the ESP8266 or Adafruit boards you need to add additional board manager URLs. To do this, you need to create a YAML file named arduino-cli.yaml. This file should go in your current working directory.

# arduino-cli.yaml
board_manager:
  additional_urls:
    - http://arduino.esp8266.com/stable/package_esp8266com_index.json
    - https://adafruit.github.io/arduino-board-index/package_adafruit_index.json

After creating the YAML file, you will need to update the index again:

arduino-cli core update-index

Then you can search for boards like the ESP8266 or Adafruit boards:

arduino-cli core search esp8266
arduino-cli core search adafruit

Let's say you want to install support for ESP8266 boards, Adafruit AVR boards, and Adafruit SAMD boards. You can install those with:

arduino-cli core install adafruit:avr adafruit:samd esp8266:esp8266

After installing the support, you can view the list of boards that you have support installed for with:

arduino-cli board listall

At this point you should see boards like the Adafruit Trinket and NodeMCU listed.

List connected boards

Once your board is connected to your computer with a USB cable and the board support was installed in the previous step, you can list the boards connected to the computer, and it should list the connected boards, the serial port it is using, and the board name.

arduino-cli board list

Example output:

> arduino-cli board list
Port Type              Board Name       FQBN
COM9 Serial Port (USB) Arduino Leonardo arduino:avr:leonardo

Compile a sketch

Here is an example sketch you can use to test with. It is important to put your sketch inside a folder. When compiling and uploading, we will point to the directory containing the sketch and not the sketch itself.

// sketchbook/blink/blink.ino
// Example from https://www.arduino.cc/en/Tutorial/Blink

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

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

Once you have the sketc saved, your board support installed, and the boards fully-qualified board name (FQBN) you can compile the sketch to the proper target. For my example, the FQBN is arduino:avr:leonardo and my sketch is stored in ./sketchbook/blink/blink.ino. I can compile the program with:

# Sketch file should be: sketchbook/blink/blink.ino
arduino-cli compile --fqbn arduino:avr:leonardo sketchbook/blink

The compiled binaries will be in the directory next to the sketch file.

Upload a sketch

To upload the sketch that was just compiled, you need to call upload and pass it the serial port, FQBN, and the directory with the compiled sketch files.

Note that if you are uploading to a board like the AdaFruit PyPortal M4 (SAMD51), you must double-tap the reset button to get it in to the right mode before uploading.

Here is an example of an upload command:

arduino-cli upload --port COM9 --fqbn arduino:avr:leonardo sketchbook/blink

Install library dependencies

If you want to use any libraries outside of the core Arduino libraries, you can find and install them with the CLI tool. To demonstrate this, we will install the Adafruit Neopixel library and write a test program.

First update your library index with:

arduino-cli lib update-index

Then search for a library, like neopixel:

arduino-cli lib search neopixel

Install the library by its name, for example "Adafruit NeoPixel":

arduino-cli lib install "Adafruit NeoPixel"

Confirm it is installed with:

arduino-cli lib list

Libraries are installed in your Documents\Arduino\libraries\ directory by default. Core libraries are stored in a different location. In Windows they are in an Arduino directory in the AppData\Local directory of your user's home.

To uninstall a library, use the name of the folder in the libraries directory, which might be different from the install name. For example, to uninstall "Adafruit Zero DMA Library" you must use

arduino-cli lib uninstall "Adafruit_NeoPixel"

NeoPixel example for PyPortal

To provide an example of how to use third-party library for a third-party board, let's look at how to use the NeoPixel library for the Adafruit PyPortal. This assumes you installed the "Adafruit NeoPixel" library in the previous step and installed the adafruit:samd core support from the earlier steps too. It also assumes you have a PyPortal, but the point is to demonstrate the process.

See my PyPortal CircuitPy Tutorial (AdaBox 011) for more details about the board. Also check out my NeoTrellis M4 CircuitPy Tutorial (AdaBox 010) for another Adafruit board example.

// Example adapted from https://github.com/adafruit/Adafruit_NeoPixel/blob/master/examples/simple/simple.ino
// sketchbook/blink/blink.ino
#include <Adafruit_NeoPixel.h>

#define PIN 2 // Pin 2 on PyPortal
#define NUMPIXELS 1  // Only one pixel on PyPortal

Adafruit_NeoPixel pixels(NUMPIXELS, PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  pixels.begin();
}

void loop() {
  pixels.clear();
  pixels.show();
  delay(250);

  pixels.setPixelColor(0, pixels.Color(0, 255, 0));
  pixels.show();
  delay(250);
}

After writing the sketch, double-tap the reset button the PyPortal to get it in to the proper mode for upload. Then you can compile and upload the sketch using commands similar to these:

arduino-cli compile --fqbn adafruit:samd:adafruit_pyportal_m4 sketchbook/blink
arduino-cli upload --port COM6 --fqbn adafruit:samd:adafruit_pyportal_m4 sketchbook/blink

Be sure to replace the serial port and the sketch names as needed.

Conclusion

After reading this, you should be able to use the Arduino CLI to manage your boards and libraries as well as compile and upload sketches.

References