Getting started

Despite the lack of feature parity at the moment, Arduino CLI provides many of the features you can find in the ArduinoIDE. 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 thehelp command like this:

$arduino-clihelp coreArduino Core operations.Usage:    arduino-cli core [command]Examples:    ./arduino-cli core update-indexAvailable 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 platforms.    search       Search for a core in Boards Manager.    uninstall    Uninstalls one or more cores and corresponding tool dependencies if no more used.    update-index Updates the index of cores.    upgrade      Upgrades one or all installed platforms to the latest version.Flags:    -h, --help   help for coreGlobal Flags:        --additional-urls strings   Additional URLs for Boards Manager.        --config-file string        The custom config file (if not specified the default will be used).        --format string             The output format, can be [text|json]. (default "text")        --log-file string           Path to the file where logs will be written.        --log-format string         The output format for the logs, can be [text|json].        --log-level string          Messages with this level and above will be logged.    -v, --verbose                   Print the logs on the standard output.Use "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 anypossible functionality. However, having one can spare you a lot of typing when issuing a command, so let's go ahead andcreate it with:

$ arduino-cli config initConfig file written: /home/luca/.arduino15/arduino-cli.yaml

If you inspect the contents ofarduino-cli.yaml, you'll find the available options with their respective defaultvalues. For more information, see theconfiguration documentation.

Create a new sketch¶

To create a new sketch namedMyFirstSketch in the current directory, run the following command:

$ arduino-cli sketch new MyFirstSketchSketch createdin: /home/luca/MyFirstSketch

A sketch is a folder containing assets like source files and libraries; thenew command creates for you a .ino filecalledMyFirstSketch.ino containing Arduino boilerplate code:

$ cat$HOME/MyFirstSketch/MyFirstSketch.inovoid setup(){}void loop(){}

At this point you can use your favourite file editor or IDE to open the file$HOME/MyFirstSketch/MyFirstSketch.ino andchange the code like this:

voidsetup(){pinMode(LED_BUILTIN,OUTPUT);}voidloop(){digitalWrite(LED_BUILTIN,HIGH);delay(1000);digitalWrite(LED_BUILTIN,LOW);delay(1000);}

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:

$ arduino-cli core update-indexUpdating 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 recognizedby running:

$ arduino-cli board listPort         Type              Board Name              FQBN                 Core/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 calledarduino:samd is the one that needs to be installed to make it work.

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

$ arduino-cli board listall mkrBoard Name              FQBNArduino MKR FOX1200    arduino:samd:mkrfox1200Arduino MKR GSM1400    arduino:samd:mkrgsm1400Arduino MKR WAN1300    arduino:samd:mkrwan1300Arduino MKR WiFi1010   arduino:samd:mkrwifi1010Arduino MKRZERO         arduino:samd:mkrzeroArduino/Genuino MKR1000 arduino:samd:mkr1000

Install the core for your board¶

To install thearduino:samd platform core, run the following:

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

Now verify we have installed the core properly by running:

$ arduino-cli core listID              Installed       Latest  Namearduino:samd1.6.191.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 theArduino CLI configuration file.

For example, to add the ESP8266 core, edit the configuration file and change theboard_manager settings as follows:

board_manager:additional_urls:-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 theboard_manager settings as follows:

board_manager:additional_urls:-https://arduino.esp8266.com/stable/package_esp8266com_index.json-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:

$ arduino-cli core update-indexUpdating index: package_index.json downloadedUpdating index: package_esp8266com_index.json downloadedUpdating index: package_nrf52832_index.jsonUpdating index: package_index.json downloaded$ arduino-cli core search esp8266ID              Version Nameesp8266:esp82662.5.2   esp8266

Alternatively, you can pass a link to the additional package index file with the--additional-urls option, that has tobe specified every time and for every command that operates on a 3rd party platform core, for example:

$ arduino-cli  core update-index --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.jsonUpdating index: package_esp8266com_index.json downloaded$ arduino-cli core search esp8266 --additional-urls https://arduino.esp8266.com/stable/package_esp8266com_index.jsonID              Version Nameesp8266:esp82662.5.2   esp8266

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

$ arduino-cli  core update-index --additional-urls file:///absolute/path/to/your/package_esp8266com_index.jsonUpdating index: package_esp8266com_index.json downloaded$ arduino-cli core search esp8266 --additional-urls file:///absolute/path/to/your/package_esp8266com_index.jsonID              Version Nameesp8266:esp82662.5.2   esp8266

Compile and upload the sketch¶

To compile the sketch you run thecompile command, passing the proper FQBN string:

$ arduino-cli compile --fqbn arduino:samd:mkr1000 MyFirstSketchSketch uses9600 bytes(3%) of program storage space. Maximum is262144 bytes.

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

$ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 MyFirstSketchNo new serial port detected.Atmel SMART device 0x10010005 foundDevice       : ATSAMD21G18AChip ID      :10010005Version      : v2.0[Arduino:XYZ] Dec20201615:36:43Address      :8192Pages        :3968Page Size    :64 bytesTotal Size   : 248KBPlanes       :1Lock Regions :16Locked       : noneSecurity     :falseBoot Flash   :trueBOD          :trueBOR          :trueArduino      : FAST_CHIP_ERASEArduino      : FAST_MULTI_PAGE_WRITEArduino      : CAN_CHECKSUM_MEMORY_BUFFERErase flashdonein0.784 secondsWrite9856 bytes to flash(154 pages)[==============================]100%(154/154 pages)donein0.069 secondsVerify9856 bytes of flash with checksum.Verify successfuldonein0.009 secondsCPU reset.

Add libraries¶

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

$ arduino-cli lib search debouncerName:"Debouncer"    Author: hideakitai    Maintainer: hideakitai    Sentence: Debounce libraryfor Arduino    Paragraph: Debounce libraryfor Arduino    Website: https://github.com/hideakitai    Category: Timing    Architecture: *    Types: Contributed    Versions:[0.1.0]Name:"FTDebouncer"    Author: Ubi de Feo    Maintainer: Ubi de Feo, Sebastian Hunkeler    Sentence: An efficient, low footprint, fast pin debouncing libraryfor Arduino    Paragraph: This pin state supervisor manages debouncing of buttons and handles transitions between LOW and HIGH state, calling afunction and notifying your code of which pin has been activated or deactivated.    Website: https://github.com/ubidefeo/FTDebouncer    Category: Uncategorized    Architecture: *    Types: Contributed    Versions:[1.3.0]Name:"SoftTimer"    Author: Balazs Kelemen <prampec+arduino@gmail.com>    Maintainer: Balazs Kelemen <prampec+arduino@gmail.com>    Sentence: SoftTimer is a lightweight pseudo multitasking solutionfor Arduino.    Paragraph: SoftTimer enables higher level Arduino programing, yet easy to use, and lightweight. You are often faced with the problem that you need todo 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.    Website: https://github.com/prampec/arduino-softtimer    Category: Timing    Architecture: *    Types: Contributed    Versions:[3.0.0,3.1.0,3.1.1,3.1.2,3.1.3,3.1.5,3.2.0]

Our favourite isFTDebouncer, let's install it by running:

$ arduino-cli lib install FTDebouncerFTDebouncer depends on FTDebouncer@1.3.0Downloading FTDebouncer@1.3.0...FTDebouncer@1.3.0 downloadedInstalling FTDebouncer@1.3.0...Installed FTDebouncer@1.3.0

Using the`daemon` mode and the gRPC interface¶

Arduino CLI can be launched as a gRPC server via thedaemon command.

Theclient_example folder contains a sample client code that shows how to interact with the gRPC server. Availableservices and messages are detailed in thegRPC reference pages.

To provide observability for the gRPC server activities besides logs, thedaemon mode activates and exposes by defaultaPrometheus endpoint (http://localhost:9090/metrics) that can be fetched for metrics datalike:

# TYPE daemon_compile counterdaemon_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# TYPE daemon_board_list counterdaemon_board_list{installationID="ed6f1f22-1fbe-4b1f-84be-84d035b6369c",success="true"} 1 1580385724833

The metrics settings are exposed via themetrics section in the CLI configuration:

metrics:enabled:trueaddr::9090

Movatterモバイル変換