Home / Software / Arduino CLI / Getting started

Getting started

Author Arduino

v1.1.1

‌
‌

‌
‌
‌

‌

‌
‌

‌
‌
‌

‌

‌
‌

‌
‌
‌

‌

‌
‌

‌
‌
‌

‌

‌
‌

‌
‌
‌

‌

‌
‌

‌
‌
‌

‌

Arduino CLI provides all the features you can find in the Arduino IDE. Let's see some examples.

Before you start

arduino-cli

is a container of commands and each command has its own dedicated help text that can be shown with the

help

command like this:

1$ arduino-cli help core
2Arduino core operations.
3
4Usage:
5  arduino-cli core [command]
6
7Examples:
8  arduino-cli core update-index
9
10Available Commands:
11  download     Downloads one or more cores and corresponding tool dependencies.
12  install      Installs one or more cores and corresponding tool dependencies.
13  list         Shows the list of installed platforms.
14  search       Search for a core in Boards Manager.
15  uninstall    Uninstalls one or more cores and corresponding tool dependencies if no longer used.
16  update-index Updates the index of cores.
17  upgrade      Upgrades one or all installed platforms to the latest version.
18
19Flags:
20  -h, --help   help for core
21
22Global Flags:
23      --additional-urls strings   Comma-separated list of additional URLs for the Boards Manager.
24      --config-file string        The custom config file (if not specified the default will be used).
25      --json                      Print the output in JSON format.
26      --log                       Print the logs on the standard output.
27      --log-file string           Path to the file where logs will be written.
28      --log-format string         The output format for the logs, can be: text, json
29      --log-level string          Messages with this level and above will be logged. Valid levels are: trace, debug, info, warn, error, fatal, panic
30      --no-color                  Disable colored output.
31
32Use "arduino-cli core [command] --help" for more information about a command.

Create a configuration file

Arduino CLI doesn't strictly require a configuration file to work because the command line interface provides any possible functionality. However, having one can spare you a lot of typing when issuing a command, so let's go ahead and create it with:

1$ arduino-cli config init
2Config file written: /home/luca/.arduino15/arduino-cli.yaml

If you inspect the contents of

arduino-cli.yaml

, you'll find the available options with their respective default values. For more information, see the configuration documentation.

Create a new sketch

To create a new sketch named

MyFirstSketch

in the current directory, run the following command:

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

A sketch is a folder containing assets like source files and libraries; the

new

command creates for you a .ino file called

MyFirstSketch.ino

containing Arduino boilerplate code:

1$ cat $HOME/MyFirstSketch/MyFirstSketch.ino
2void setup() {
3}
4
5void loop() {
6}

At this point you can use your favourite file editor or IDE to open the file

$HOME/MyFirstSketch/MyFirstSketch.ino

and change the code like this:

1void setup() {
2    pinMode(LED_BUILTIN, OUTPUT);
3}
4
5void loop() {
6    digitalWrite(LED_BUILTIN, HIGH);
7    delay(1000);
8    digitalWrite(LED_BUILTIN, LOW);
9    delay(1000);
10}

Connect the board to your PC

The first thing to do upon a fresh install is to update the local cache of available platforms and libraries by running:

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

After connecting the board to your PC by using the USB cable, you should be able to check whether it's been recognized by running:

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

In this example, the MKR1000 board was recognized and from the output of the command you see the platform core called

arduino:samd

is the one that needs to be installed to make it work.

If you see an

Unknown

board listed, uploading should still work as long as you identify the platform core and use the correct FQBN string. When a board is not detected for whatever reason, you can list all the supported boards and their FQBN strings by running the following:

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

Install the core for your board

To install the

arduino:samd

platform core, run the following:

1$ arduino-cli core install arduino:samd
2Downloading tools...
3arduino:arm-none-eabi-gcc@4.8.3-2014q1 downloaded
4arduino:bossac@1.7.0 downloaded
5arduino:openocd@0.9.0-arduino6-static downloaded
6arduino:CMSIS@4.5.0 downloaded
7arduino:CMSIS-Atmel@1.1.0 downloaded
8arduino:arduinoOTA@1.2.0 downloaded
9Downloading cores...
10arduino:samd@1.6.19 downloaded
11Installing tools...
12Installing platforms...
13Results:
14arduino:samd@1.6.19 - Installed
15arduino:arm-none-eabi-gcc@4.8.3-2014q1 - Installed
16arduino:bossac@1.7.0 - Installed
17arduino:openocd@0.9.0-arduino6-static - Installed
18arduino:CMSIS@4.5.0 - Installed
19arduino:CMSIS-Atmel@1.1.0 - Installed
20arduino:arduinoOTA@1.2.0 - Installed

Now verify we have installed the core properly by running:

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

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

Adding 3rd party cores

If your board requires 3rd party core packages to work, you can list the URLs to additional package indexes in the Arduino CLI configuration file.

For example, to add the ESP8266 core, edit the configuration file and change the

board_manager

settings as follows:

1board_manager:
2  additional_urls:
3    - https://arduino.esp8266.com/stable/package_esp8266com_index.json

If you have your package indexes locally installed, you can list their file path in the Arduino CLI configuration file.

For example, to add the NRF52832 core, edit the configuration file and change the

board_manager

settings as follows:

1board_manager:
2  additional_urls:
3    - https://arduino.esp8266.com/stable/package_esp8266com_index.json
4    - file:///absolute/path/to/your/package_nrf52832_index.json

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

1$ arduino-cli core update-index
2Updating index: package_index.json downloaded
3Updating index: package_esp8266com_index.json downloaded
4Updating index: package_nrf52832_index.json
5Updating index: package_index.json downloaded
6
7$ arduino-cli core search esp8266
8ID              Version Name
9esp8266:esp8266 2.5.2   esp8266

Alternatively, you can pass a link to the additional package index file with the

--additional-urls

option, that has to be specified every time and for every command that operates on a 3rd party platform core, for example:

1$ arduino-cli  core update-index --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json
2Updating index: package_esp8266com_index.json downloaded
3
4$ arduino-cli core search esp8266 --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.json
5ID              Version Name
6esp8266:esp8266 2.5.2   esp8266

The same applies to the additional package index file provided by file paths:

1$ arduino-cli  core update-index --additional-urls file:///absolute/path/to/your/package_esp8266com_index.json
2Updating index: package_esp8266com_index.json downloaded
3
4$ arduino-cli core search esp8266 --additional-urls file:///absolute/path/to/your/package_esp8266com_index.json
5ID              Version Name
6esp8266:esp8266 2.5.2   esp8266

Compile and upload the sketch

To compile the sketch you run the

compile

command, passing the proper FQBN string:

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

To upload the sketch to your board, run the following command, using the serial port your board is connected to:

1$ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 MyFirstSketch
2No new serial port detected.
3Atmel SMART device 0x10010005 found
4Device       : ATSAMD21G18A
5Chip ID      : 10010005
6Version      : v2.0 [Arduino:XYZ] Dec 20 2016 15:36:43
7Address      : 8192
8Pages        : 3968
9Page Size    : 64 bytes
10Total Size   : 248KB
11Planes       : 1
12Lock Regions : 16
13Locked       : none
14Security     : false
15Boot Flash   : true
16BOD          : true
17BOR          : true
18Arduino      : FAST_CHIP_ERASE
19Arduino      : FAST_MULTI_PAGE_WRITE
20Arduino      : CAN_CHECKSUM_MEMORY_BUFFER
21Erase flash
22done in 0.784 seconds
23
24Write 9856 bytes to flash (154 pages)
25[==============================] 100% (154/154 pages)
26done in 0.069 seconds
27
28Verify 9856 bytes of flash with checksum.
29Verify successful
30done in 0.009 seconds
31CPU reset.

Add libraries

If you need to add more functionalities to your sketch, chances are some of the libraries available in the Arduino ecosystem already provide what you need. For example, if you need a debouncing strategy to better handle button inputs, you can try searching for the

debouncer

keyword:

1$ arduino-cli lib search debouncer
2Name: "Debouncer"
3    Author: hideakitai
4    Maintainer: hideakitai
5    Sentence: Debounce library for Arduino
6    Paragraph: Debounce library for Arduino
7    Website: https://github.com/hideakitai
8    Category: Timing
9    Architecture: *
10    Types: Contributed
11    Versions: [0.1.0]
12Name: "FTDebouncer"
13    Author: Ubi de Feo
14    Maintainer: Ubi de Feo, Sebastian Hunkeler
15    Sentence: An efficient, low footprint, fast pin debouncing library for Arduino
16    Paragraph: This pin state supervisor manages debouncing of buttons and handles transitions between LOW and HIGH state, calling a function and notifying your code of which pin has been activated or deactivated.
17    Website: https://github.com/ubidefeo/FTDebouncer
18    Category: Uncategorized
19    Architecture: *
20    Types: Contributed
21    Versions: [1.3.0]
22Name: "SoftTimer"
23    Author: Balazs Kelemen <prampec+arduino@gmail.com>
24    Maintainer: Balazs Kelemen <prampec+arduino@gmail.com>
25    Sentence: SoftTimer is a lightweight pseudo multitasking solution for Arduino.
26    Paragraph: SoftTimer enables higher level Arduino programing, yet easy to use, and lightweight. You are often faced with the problem that you need to do multiple tasks at the same time. In SoftTimer, the programmer creates Tasks that runs periodically. This library comes with a collection of handy tools like blinker, pwm, debouncer.
27    Website: https://github.com/prampec/arduino-softtimer
28    Category: Timing
29    Architecture: *
30    Types: Contributed
31    Versions: [3.0.0, 3.1.0, 3.1.1, 3.1.2, 3.1.3, 3.1.5, 3.2.0]

Our favourite is

FTDebouncer

, let's install it by running:

1$ arduino-cli lib install FTDebouncer
2FTDebouncer depends on FTDebouncer@1.3.0
3Downloading FTDebouncer@1.3.0...
4FTDebouncer@1.3.0 downloaded
5Installing FTDebouncer@1.3.0...
6Installed FTDebouncer@1.3.0

Using the

daemon

mode and the gRPC interface

Arduino CLI can be launched as a gRPC server via the

daemon

command.

The client_example folder contains a sample client code that shows how to interact with the gRPC server. Available services and messages are detailed in the gRPC reference pages.

To provide observability for the gRPC server activities besides logs, the

daemon

mode activates and exposes by default a Prometheus endpoint (http://localhost:9090/metrics) that can be fetched for metrics data like:

1# TYPE daemon_compile counter
2daemon_compile{buildProperties="",exportFile="",fqbn="arduino:samd:mkr1000",installationID="ed6f1f22-1fbe-4b1f-84be-84d035b6369c",jobs="0",libraries="",preprocess="false",quiet="false",showProperties="false",sketchPath="5ff767c6fa5a91230f5cb4e267c889aa61489ab2c4f70f35f921f934c1462cb6",success="true",verbose="true",vidPid="",warnings=""} 1 1580385724726
3
4# TYPE daemon_board_list counter
5daemon_board_list{installationID="ed6f1f22-1fbe-4b1f-84be-84d035b6369c",success="true"} 1 1580385724833

The metrics settings are exposed via the

metrics

section in the CLI configuration:

1metrics:
2  enabled: true
3  addr: :9090

Arduino CLI

Guides

gRPC Reference

Getting started

Before you start

Create a configuration file

Create a new sketch

Connect the board to your PC

Install the core for your board

Adding 3rd party cores

Compile and upload the sketch

Add libraries

Using the
`daemon`
mode and the gRPC interface

ON THIS PAGE