Using the Arduino CLI

Enfield Cat's Blog: Arduino and other projects.

Introduction

The Arduino CLI allows you to compile and upload Arduino projects from the command line interface. This allows Arduino projects be:

To use other IDE environments other than the Arduino IDE
To be managed by scripted or CI-CD (Continuous Integration - Continuous Delivery) environments.
To be compiled or uploaded without the overhead of the graphical interface
Run on systems which do not have a graphical interface

Install and configure the CLI

download the CLI build from: https://arduino.github.io/arduino-cli/installation/
Extract the compressed binary for your system and put it in your system path. This may vary between systems, on a Linux system it might be:
```
tar -xvf arduino-cli_latest_Linux_64bit.tar.gz
mv arduino-cli /usr/local/bin
rm arduino-cli_latest_Linux_64bit.tar.gz
```
Initialise the cli for your user:
```
arduino-cli config init
```

Modify the configution to include ESP32 and other boards you are interested in ~/.arduino15/arduino-cli.yaml, adjust your path to suit your user. "/home/nelson/" is just my home directory:

board_manager:
  additional_urls: []
daemon:
  port: "50051"
directories:
  data: /home/nelson/.arduino15
  downloads: /home/nelson/.arduino15/staging
  user: /home/nelson/Arduino
logging:
  file: ""
  format: text
  level: info
board_manager:
  additional_urls:
  - https://dl.espressif.com/dl/package_esp32_index.json
  - https://arduino.esp8266.com/stable/package_esp8266com_index.json
  - https://raw.githubusercontent.com/damellis/attiny/ide-1.6.x-boards-manager/package_damellis_attiny_index.json

Update your index, and check your boards are listed:
```
arduino-cli core update-index
arduino-cli core search
```
Note: You will have upated the index of known processor types at this stage, now you need to update the tools and codes for them. Repeat for each architecture you wat to support, then what you have installed, eg:
```
arduino-cli core install arduino:avr
arduino-cli core install esp32:esp32
arduino-cli core install esp8266:esp8266
arduino-cli core list
```

Search for libraries and install them. Note this will vary on what tasks and peripheral hardware your project will support, eg:

arduino-cli lib search debouncer
arduino-cli lib install FTDebouncer

Note, the install will also check for pre-requisite dependencies of your library and instll these for you. eg:

# arduino-cli lib install "Adafruit BME280 Library"
Adafruit BME280 Library depends on Adafruit BME280 Library@2.0.1
Adafruit BME280 Library depends on Adafruit Unified Sensor@1.1.2
Adafruit BME280 Library depends on Adafruit ADXL343@1.2.0
Downloading Adafruit ADXL343@1.2.0...
Adafruit ADXL343@1.2.0 downloaded
Installing Adafruit ADXL343@1.2.0...
Installed Adafruit ADXL343@1.2.0
Downloading Adafruit BME280 Library@2.0.1...
Adafruit BME280 Library@2.0.1 downloaded
Installing Adafruit BME280 Library@2.0.1...
Installed Adafruit BME280 Library@2.0.1
Downloading Adafruit Unified Sensor@1.1.2...
Adafruit Unified Sensor@1.1.2 downloaded
Installing Adafruit Unified Sensor@1.1.2...
Installed Adafruit Unified Sensor@1.1.2

You can list your installed libraries, eg:

$ arduino-cli lib list
Name                      Installed Available Location Description
Adafruit_BME280_Library   2.1.2    -        user     -
Adafruit_BusIO            1.7.2    -        user     -
Adafruit_GFX_Library      1.10.4   -        user     -
Adafruit_SSD1306          2.4.3    -        user     -
Adafruit_Unified_Sensor   1.1.4    -        user     -
Adafruit_VEML6075_Library 2.1.0    -        user     -
OneWire                   2.3.5    -        user     -

If you are running on a modern Ubuntu system, you may have Python3 installed but not python. This is needed for esp32 support. In this case install Python, eg:

apt-get install python python-serial

Or for Ubuntu 20.04... use python3 by changing the default python to python 3:

sudo apt-get install python3 python3-serial
sudo rm /usr/bin/python
sudo ln /usr/bin/python /usr/bin/python3

If these updates are not applied, then even without trying to flash the device, you may encounter errors like this:

$ arduino-cli compile --fqbn esp32:esp32:lolin32:CPUFreq=80,PartitionScheme=min_spiffs MyProject
Traceback (most recent call last):
  File "/home/nelson/.arduino15/packages/esp32/tools/esptool_py/2.6.1/esptool.py", line 37, in 
    import serial
ImportError: No module named serial

Error during build: exit status 1

Compiling for your board

You will need to specify the Fully Qualified Board Name (fqbn) when compiling. So work out what options you have. You could list all boards, or just grep for what might be of interest.
```
arduino-cli board listall
arduino-cli board listall | grep -i lolin
```
You should now be in a position to compile your first (and successive) programs, eg: if your code is under a directory ~/Arduino/myProject
```
cd ~/Arduino
arduino-cli compile --fqbn esp32:esp32:lolin32 myProject
```
We are not done yet! We've just used the default patitioning scheme, so what other partitioning schemes can we use? These are held in csv files. Note the executable portion of your code must start on a 64K boundary, don't specify a memory which exceeds that which you have. These CSV files will be in your user's found in a hidden arduino directory, view these or add your own as required:
```
find ~ -name "*.csv" -print 2>/dev/null
```
Which of these options are supported by your board, and what other options does it support? By answering these questions we can adjust our build. Assuming my target is lolin32, then I can first search for and appropriate boards.txt file for the core, then extract the menu options and acceptable settings for my target board, eg:
```
find ~ -name boards.txt -print
grep -i lolin32.menu /home/nelson/.arduino15/packages/esp32/hardware/esp32/1.0.4/boards.txt
```
Now when you compile append your selected "menu" options as a comma separated list in the fqdn after another ":", eg:
```
arduino-cli compile --fqbn esp32:esp32:lolin32:CPUFreq=80,PartitionScheme=min_spiffs myProject
```
While considering setup and configuration, what does the arduino.h define for your board? These settings are useful to know when writing code for your board. First find the directory holding your board info, then inpect the arduino,h file, eg:
```
find ~ -name lolin32 -print
cat /home/nelson/.arduino15/packages/esp32/hardware/esp32/1.0.4/variants/lolin32/arduino.h
```

And finally flash the update to your board...

If you are using over the air (OTA) updates, then this might be as simple as copying the resultant binary to the appropriate location on your web server. If your board is connected via usb, check what port it is connected to, then use the cli update command to flash your code, eg:

arduino-cli board list
arduino-cli upload -p /dev/ttyACM0 --fqbn esp32:esp32:lolin32 myProject

Maintain your installation

Your installation will need updating from time to time to benefit from fixes applied to the libraries. If a library contains an important security or bug fix, you will need to recompile your projects and reflash your Arduino / esp32 devices.

For both function libraries and cores, use the lib update-index and upgrade sub-commends, eg:

$ arduino-cli lib update-index
Updating index: library_index.json downloaded
$ arduino-cli lib upgrade
Downloading ArduinoOTA@1.0.7...
ArduinoOTA@1.0.7 downloaded
Downloading ArduinoOTA@1.0.7...
ArduinoOTA@1.0.7 already downloaded
Downloading Ticker@4.4.0...
Ticker@4.4.0 downloaded
Downloading Ticker@4.4.0...
Ticker@4.4.0 already downloaded
Downloading Ethernet@2.0.0...
Ethernet@2.0.0 downloaded
$ arduino-cli core update-index
Updating index: package_index.json downloaded
Updating index: package_index.json.sig downloaded
Updating index: package_esp32_index.json downloaded
Updating index: package_esp8266com_index.json downloaded
Updating index: package_damellis_attiny_index.json downloaded
[2021-09-26 13:30:47]
$ arduino-cli core upgrade
Tool esp32:mkspiffs@0.2.3 already installed
Downloading packages...
esp32:xtensa-esp32-elf-gcc@1.22.0-97-gc752ad5-5.2.0 4.96 MiB / 48.31 MiB   10.27
esp32:xtensa-esp32-elf-gcc@1.22.0-97-gc752ad5-5.2.0 11.22 MiB / 48.31 MiB   23.2
esp32:xtensa-esp32-elf-gcc@1.22.0-97-gc752ad5-5.2.0 17.12 MiB / 48.31 MiB   35.4

Thank you for visiting camelthorn.cloud

Home