arduino-cli

Date: — Topics: , , — by Slatian

While arduino-cli is an awesome tool, unfortunately most guides skip right past it and assume you use the Arduino IDE, this page is a collection of common patterns for arduino-cli. It assumes that you know a few things about how Arduino works.

Table of Contents

Basics

To create a sketch arduino-cli assumes that your main .ino file has the same name as the directory containing it.

To build and upload use arduino-cli compile --fqbn <fqbn> and arduino-cli upload -p <serial-device> --fqbn <fqbn> in your code directory.

Hint: On Linux your serial devices are called /dev/ttyUSBn and /dev/ttyACMn where n is a number.
Make sure you have the permissions to access them and nothing else is trying to use those ports.

You've got an unhelpful error message? Try adding the --log flag, it will cause arduino-cli to print out whatever it is currently doing.
This way one can get some context for the error.

FQBN? Fully Qualified Board Name!

The Fully qualified Board name consists of what Arduino calls the Platform ID and a name for the board. You can find it out either by using arduino-cli board search <searchterm>, arduino-cli board listall or by appending the official board name in lowercase to the Platform ID.

Examples include:

Please note that the esp boards are not available by default.

Compile and Upload a Sketch using arduino-cli

I usually create a compile-and-upload.sh script to make development and testing easier.

#!/bin/sh
arduino-cli compile --fqbn arduino:avr:uno && \
arduino-cli upload --fqbn arduino:avr:uno -p "${1:-/dev/ttyUSB0}"
A simple compile and upload script with a fixed board and an optional argument for the serial port that defaults to /dev/ttyUSB0

Note: When given the -u flag and the options needed for uploading arduino-cli compile --fqbn arduino:avr:uno -u -p "${1:-/dev/ttyUSB0}" behaves like the above example script.

Note on shell syntax: The "${1:-/dev/ttyUSB0}" is read by your shell as replace this with the first argument given to the script or with /dev/ttyUSB0.

Adding more Boards

The arduino-cli is not just a wrapper for a compiler and whatever you prefer for uploading … it also is a package manager. If you want more boards (or libraries) you can search for and install them.

But if you want to write code for a non-Arduino branded board (i.e. an ESP8266 or ESP32) those packages are not in the Arduino package repositories.

Adding an extra repository can be done by letting arduino-cli do the work …

arduino-cli config add board_manager.additional_urls 'url://to/index.json'

… or by manually editing ~/.arduino15/arduino-cli.yaml and adding the URL pinting to the respositories *_index.json file there.

board_manager:
  additional_urls:
  - https://arduino.esp8266.com/stable/package_esp8266com_index.json
  - https://dl.espressif.com/dl/package_esp32_index.json
  - https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json
An excerpt from the configuration file from my laptop with additional URL to the stable esp8266 and esp32 repositories in addition to the development version of the esp32 repository.

Don't forget to arduino-cli update and arduino-cli upgrade!

Flashing a Bootloader using arduino-cli

arduino-cli already knows how to flash a new bootloader with the burn-bootloader subcommand, you have to tell it for which board you want the bootloader using --fqbn and which programmer you are using with -P.

Note: Programmers usually aren't quite cheap, but if you have another Arduino (compatible) with UART (serial) and SPI interface you can use that Arduino as an ISP . (use -P arduinoasisp)

It may be necessary to provide the port the programmer is on via the -p option. (like with the upload command)

Example using the official AVRISP mkII programmer for AVR chips for an ATMEL 328P in an Arduino Uno like configuration 
arduino-cli burn-bootloader --fqbn arduino:avr:uno -P avrispmkii

To find out which programmer string you need, go to the ArduinoCore-* repository of your favourite architecture (See github.com/arduino for the official ones) and open the programmers.txt file (i.e. ArduinoCore-avr/programmers.txt), the keys used there are the needed ids for the -P option.

Note: An interesting option might be to use an Arduino Microcontroller as your programmer, use -P arduinoisp in this case. The neccessary code is also in a public repository.

Why do I need a Bootloader?

To be able to seamlessly upload code with just a USB to serial converter like in the example above your microcontroller needs to have the Arduino bootloader installed, a small piece of software that runs when the controller starts (that's the reason you need to hook up the reset line when programming) that can be told to write a new program to the controller instead of starting the already existing one.

The boards you can buy online come with a bootloader preinstalled. But maybe you want to build your own Arduino compatible or released the magic smoke and want to just buy the chip itself without a development-board, that is when you want to flash the bootloader yourself.

Do I need a Bootloader to use the Arduino Framwork?

No, you can use the programmer of your choice (just use the -P option with the upload command) to flash whatever you coded up directly into the controller at the cost of having to use the programmer every time you upload a new program. (Unless that program is a bootloader 😉)

Using sketch-local Libraries

To use liberies stored anywhere but the default location (i.e. in a libs folder next to your .ino files) the --library and --libraries can be used. Both accept a comma seperated list of filepaths.

--library points to individual libraries and --libraries points to folders of libraries.

Example to compile a sketch with a libs folder 
arduino-cli compile --libraries libs/ --fqbn <fqbn>

You may also be interested in

The official arduino-cli documantation

Serial Port Troublehooting on Linux