With the Arduino platform moving on from the classic editor to the new Command Line Interface (arduino-cli) and Pro IDE, it becomes important for all hobbyists and enthusiasts to get started with them as well. In this blog, I will be showing how to get started with the arduino-cli, downloading and setting it up, using it to compile and upload code, and a whole lot more. Let’s get started!
What is the Arduino CLI?
For quite some time, the classic IDE was the only way to program & build applications for Arduino. Since everything was built into the IDE, it was difficult to perform various steps like compilation, upload etc. individually & integrate them into third-party editors, IDEs or workflows. To solve these problems, Arduino created a command line based tool – Arduino-cli. Using this tool, each of these steps can be performed using text commands. The arduino-cli is a command line tool to perform all build related tasks on the Arduino platform.
What is a Command Line Interface (CLI)?
If you have never worked with a Command Line interface, it may sound a little intimidating, but it need not be so. In the GUI (Graphical User Interface) world, most things are done by pointing and clicking (using a mouse or touch interface), while in the CLI world, the same can be done by typing in text commands. For example, to copy a file on the GUI, you may drag and drop it from the source to the target folder, while on the CLI, you might type in a command like copy <source> <destination>.
Both the GUI and CLI can be used to do the same tasks, and are essentially just two different methods of interacting with the Operating System. You can read more about it here.
To start using the CLI on a GUI oriented OS like Windows, programs such as PowerShell, cmd or even gitbash can be used, which are known as shell applications. They usually open a Window containing a prompt with a cursor. It will look something as follows.
Go to the Windows search bar (bottom left), type cmd and select “Command Prompt”. You are now on a CLI. It will look like the picture above. You may try typing in each of the following commands and see their outputs to familiarize yourself-
- dir
- help
- pause
- date
- echo “abc”
- copy
- ls (This will show an error message on cmd)
- exit
After you have familiarized yourself with the CLI, you can go ahead to download and install the arduino-cli. Once in place, you can now perform tasks you would otherwise perform using the Arduino IDE (such as compiling, uploading, debugging, getting libraries etc.), but on the command line.
Download and Install
In this section, I will be showing two ways to download and install the Arduino-cli on your system and add it to the search PATH. The first method is using a tool called CUrl where the various steps are done automatically. The second method is where I show how to get the binaries from GitHub & do it step by step yourself.
Using CUrl
This is a simple method where you execute the curl command as stated on the Arduino web-site here.
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
This command uses the Curl tool to do the following:
- Connect to the Arduino Github repository
- Download a shell script
- Execute it
This shell script (install.sh) downloads & installs the right version of the arduino-cli after checking your Operating System as well as other parameters.
This method makes everything quick and easy, but it has multiple dependencies, such as needing CUrl as well as bash (or equivalent shell) to be pre-installed on your system. These are not very common on Windows, however, you can get them as part of cygwin (a collection of such Unix like tools on Windows).
Alternatively, you can use the following method, which reads longer but is preferred as it gives greater understanding while only taking a few minutes.
From Github
Start by clicking here to go to the GitHub repository where the various releases of the arduino-cli can be found. You would usually want to get the one marked as latest release, however, you can scroll down for older releases. The CLI packages for different platforms (including Windows) are listed below the Changelog. Click on the package appropriate for your platform to download it. The package is in the form of a compressed file (zip).
If you aren’t sure about whether you should get the 32 or 64-bit version, then click here to be taken to a simple guide on finding out the bitness of your system.
Create a folder in your root directory (in my case, C:\) where the CLI will be set up. Move the zip file from the downloads folder into this folder. You can choose to name the folder anything. I have named it arduino-cli.
Extract the files from the zip into this folder – double click on the zip to go inside and, drag & drop its contents outside. You should see two files, the actual program (arduino-cli.exe) and the license details (LICENSE.txt). The zip file can now be deleted.
Now, open PowerShell/cmd.exe and try running the CLI by giving its full path (in my case, “C:\arduino-cli\arduino-cli.exe”). If everything has gone well, you should see the arduino-cli’s help text.
The installation of the CLI is complete, however, the complete path must be specified each time it is used, which is inconvenient. To avoid this, the CLI’s path must be added to the system’s PATH variable.
Adding the Arduino CLI to system Path
In this section I will be showing how the arduino-cli can be added to the PATH variable of your system. If you already know how to do this/have already done this, you can skip this step.
Search for “System Variables” in the Windows search bar and open the “Edit the system environment variables” option which shows up.
Then, click on the environment variables button on the bottom right corner.
This should have opened another window showing the different system variables and user variables. Click on Path and then Edit.
This will open yet another window containing a list of the paths the OS uses. Click on the New button and paste the path of your program in the text box and press Enter to save it.
The path of the CLI has now been added to your system. You can now close all of the windows. Once again, open PowerShell/cmd.exe and type in arduino-cli (without the complete path this time). If everything has been done right, you should see the same help text as before.
Understanding Cores, Boards and Tool-chains
Despite being a tool itself, the arduino-cli requires other tools to function and perform its various tasks. These tools are specific to your target board. While there are many different boards, each using a different microcontroller, several boards may share the same chip architecture and form a set or board-family. For example, the UNO and Mega are part of the AVR family while the Zero and MKR1000 are part of the SAMD family. Each of these families requires its own specific tool-set for tasks like compilation, uploading/downloading, debugging, a Programmer & bootloader etc.
The Compiler is what converts the sketch from high level human readable code (which you write) to low level instructions which the microcontroller on your target board can read and execute. It generates binary files from your source code.
The Uploader/Downloader is a program which acts as an intermediary between your PC and the target microcontroller. It is allows you to manipulate the contents of the microcontroller’s ROM and is used for transferring the program from your PC to the board.
The Debugger is a program/tool which can be used to examine the state of YOUR program while it is running on the microcontroller. It can be used to find and remove errors from your program and in some instances, even optimize it.
The Programmer is a physical device (unlike the other 3) which is used to burn the program onto the microcontroller’s ROM, bypassing any and all data previously on it, including the bootloader.
These are collectively referred to as a Core or Architecture or Platform. The arduino-cli makes it incredibly easy to get & set them up.
Additionally, your sketch may use a library. A Library provides additional capability as a collection of functions, classes and constants (sometimes pre-compiled) that can be used from your code without compulsorily having to know its internal working and logic. The arduino-cli also allows you to get libraries and install them in a very easy manner, as will be seen.
Setting up Cores
To get the list of cores currently installed at any point of time, enter the following command-
arduino-cli core list
This will list all the cores you currently have installed along with their IDs, current version and latest available version. If you do not have any cores installed yet (like me), it will be empty.
A list of installed boards can also be individually displayed with the following command-
arduino-cli board listall
This lists all the installed boards individually, along with their Fully Qualified Board Names (The official name used to denote them). If you do not have any cores installed yet (like me), it will be empty.
To install a core along with all its dependencies (such as compiler, debuggers etc.), enter the following command. Arduino regularly updates its list of available cores to match the boards available in the market.
arduino-cli core install arduino:avr
Since I am using an Arduino Uno in this example, I have chosen to get the AVR core, however you can get a different core by simply changing the ID given at the end.
To upgrade all installed cores to the latest version, you can use the following command-
arduino-cli core upgrade
Installing Third party cores
The arduino-cli can also be used to compile and upload programs to third party boards (not officially distributed by Arduino). To get third party cores the same method as above may be followed, albeit with a few additional steps.
Enter the following command to get initialize the config file of your arduino-cli.
arduino-cli config init
This will print the path to the config file of your arduino-cli. If it doesn’t exist, it will be created.
Now, open this file using any text editor. It should look a bit like this-
You will now have to add the package index of the target core to the additional urls. In this example, I will be getting the
STM32 (http://dan.drown.org/stm32duino/package_STM32duino_index.json) and
ESP8266 (https://arduino.esp8266.com/stable/package_esp8266com_index.json) cores.
Copy and paste the following URLs into the square brackets in front of additional urls (seperated by a comma) as shown-
You may replace the URLs I have used with those of your target core. You can save and exit the arduino-cli.yaml config file now.
Finally, enter the following command to update the core indexes.
arduino-cli core update-index
If everything went well the output should be similar to what is shown, indicating that you can now use the regular method to install, upgrade and use third party cores.
Setting up Libraries
Next, it is time to get the libraries set up. This step is not essential for your first sketch and can be temporarily skipped if you just want to see your first program running initially.
The following command can be used to list all libraries currently installed on your PC.
arduino-cli lib list
This will list all libraries you currently have installed along with the version currently installed, latest available version and location.
As you can see, two of my libraries (Bluetooth Low Energy and WifiNinna) aren’t at their latest versions and can be upgraded. To do so, use the following command
arduino-cli lib upgrade
This will upgrade all your installed libraries to their latest stable version.
To search for a library, you can use the following command-
arduino-cli lib search “someString”
It will do a case insensitive search for libraries whose names contain the string given at the end (shown as “someString”) and display the list.
After you have found your desired library, you can install it using the following command-
arduino-cli lib install libraryName
The library name should be the full name of the library. If the name contains white-spaces, give it in double quotes (otherwise the CLI will not be able to make sense out of it). To get a specific version of the library, use the “@” character followed by the version number, for example-
arduino-cli lib install libraryName@a.b.c
In the following pictures, I get the newPing library by Tim Eckel (for easily controlling ultrasonic sensors) by first searching for it, installing it and then upgrading it to the latest version.
Once a library has been installed and is listed, you can include it in your sketches.
Compiling and Uploading your First Sketch
Creating the sketch
In this section, I will be showing how you can write your sketches without the classic IDE so that they can be used with the arduino-cli.
For this example, I will be using the “blink” program as it is simple and does not need any other components. This allows any problems in the cli to be narrowed down faster. The program’s results are easy to verify, with the user only having to see if the time intervals of the LED in each state are correct.
All Arduino sketches need to be in a folder with the same name (called the project folder). The project folder can be created anywhere, just make sure to remember all its details. To keep everything easy to follow, I have named the folder “blink”.
Now, create a new text file in the folder (right-click) and name it blink.ino. It must have the same name as the project folder. The extension cannot be changed from .ino as it is standard for all Arduino programs.
Alternatively, the above steps can be skipped and the sketch, along with the project folder can directly be created using the CLI.
First, cd into the folder/drive where you project folder must be created (in my case d:\). Then enter the following comand-
arduino-cli sketch new blink
It will create the project folder along with the program file. If successful, it will give the following output.
Since I already have the classic IDE installed, the icon shows up as the Arduino symbol, however this may not be the case for you, which is perfectly normal.
Now, open the file using your favorite text editor/IDE and paste the following code into it. You can even use the classic arduino IDE for this. If you aren’t familiar with Arduino programming, click here to be taken to my guide to getting started with Arduino.
void setup() {
pinMode(LED_BUILTIN, OUTPUT);
}
void loop() {
digitalWrite(LED_BUILTIN, HIGH);
delay(1000);
digitalWrite(LED_BUILTIN, LOW);
delay(250);
}
And that’s it! You can save this and close the editor, your sketch is complete.
Compiling
In this section, I will be showing how to compile the program to make it ready for uploading.
Start by opening PowerShell/cmd.exe and give it the following command-
arduino-cli compile –fqbn arduino:avr:uno “d:\Arduino programs\Projects\blink”
*Note: –fqbn can also be replaced with -b without changing the meaning/functionality
This tells the arduino-cli to compile the program inside c:\blink to be uploaded to an Arduino UNO. Change the Fully Qualified Board name to match the board which you’re using and the path at the end to wherever you have saved the program.
Alternatively, you can also cd into the folder where your sketch is stored and run the compile command without specifying a path (provided the folder and program share the same name).
If you now go and check the contents of your program folder, you will see a sub-folder apart from your program, named build. This contains the binaries (seperately for each of the boards the sketch has been compiled for) which will be uploaded.
Uploading
With the binaries ready, it is now time to upload the program to the board, but first it is necessary to know which port the board is connected to. While the classic IDE did this automatically (most of the time), you will need to enter the following command to check the list of boards currently connected to your PC.
arduino-cli board list
This should print a list of the boards connected to your PC, along with their ports and Fully Qualified Board names.
Remember the port of the board you wish to upload the sketch to. The Arduino UNO I am using for this example is connected to COM7.
Now, enter the following command to upload your binaries to the board.
arduino-cli upload -p COM7 -b arduino:avr:uno “d:\Arduino programs\Projects\blink”
Once again, change the port, fqbn and the path at the end to match your port, fqbn and program’s path. You do not need to give the path to the binaries, only to the project folder.
Just like compile, you can cd into the folder where your sketch is stored and run the upload command without specifying a path (provided the folder and program share the same name).
The upload command does not give any output (unless specified using the -v flag). So, while this should upload the program to your board, you can verify by seeing if the Rx and Tx LEDs on your board are blinking and the built-in LED is blinking properly as well.
Compile and Upload together
The arduino-cli also gives you the ability to compile and upload your sketches simultaneously. Note down the COM port and fqbn of your target board by listing the connected boards and run the following command. The Arduino UNO I am using for this example is connected to COM7.
arduino-cli compile –fqbn arduino:avr:uno –upload -p COM7 “d:\Arduino programs\Projects\blink”
Once again, you can cd into the folder where the sketch is stored and omit giving the path at the end. Replace the fqbn and port name with those of your target board and the cli will upload the binaries after the sketch is finished uploading. While it uploads, you can see the Tx and Rx Leds of the board blinking.
Attaching the sketch to a board/port
The arduino-cli also gives you the option to “attach” a sketch to a port or a board. By doing this, you don’t have to repeatedly specify the port & fqbn of the target board. This is especially helpful when you might be using multiple boards simultaneously, as it reduces confusion by removing extra steps and the need to repeatedly verify if the given parameters are correct.
To do this, enter the following command. Since I am using an Arduino UNO, I have specified the same in the example, however you will have to replace it with the fqbn of your target board.
arduino-cli board attach arduino:avr:uno
To attach the sketch to a COM port (in my case, COM7), just replace the board name with the COM port as shown below-
arduino-cli board attach COM7
By doing this, you can compile your sketches without specifiying the “–fqbn” and “-p” flags.
If you now go and check the contents of your program folder, you will find that a json file has been created, names sketch.json which will contain the target board and target port for which your sketch will be compiled and to which it will be uploaded to.
Arduino-CLI’s Flow Visualized
Conclusion
The arduino-cli is an important new addition to the Arduino platform and after reading this blog, you should be better prepared to use it for your work.
If you have any thoughts or queries, leave them in the comments down below, I’d love to know them! Happy Hacking!