From 0ee87a76c0b50291221d8bc11f2cbffaf236b7e8 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 10:14:22 +0100 Subject: [PATCH 01/10] convert to rST --- README.md | 469 --------------------------------------------- README.rst | 547 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 547 insertions(+), 469 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index e0a8a9e7080..00000000000 --- a/README.md +++ /dev/null @@ -1,469 +0,0 @@ -# arduino-cli - -[![Tests passing](https://github.com/Arduino/arduino-cli/workflows/test/badge.svg)](https://github.com/Arduino/arduino-cli/actions?workflow=test) -[![Nightly build](https://github.com/Arduino/arduino-cli/workflows/nightly/badge.svg)](https://github.com/Arduino/arduino-cli/actions?workflow=nightly) -[![codecov](https://codecov.io/gh/arduino/arduino-cli/branch/master/graph/badge.svg)](https://codecov.io/gh/arduino/arduino-cli) - -`arduino-cli` is an all-in-one solution that provides builder, boards/library manager, uploader, -discovery and many other tools needed to use any Arduino compatible board and platforms. - -This software is currently under active development: anything can change at any time, API and UI -must be considered unstable. - -## How to contribute - -Contributions are welcome! - -Please read the document [How to contribute](CONTRIBUTING.md) which will guide you through how to -build the source code, run the tests, and contribute your changes to the project. - -:sparkles: Thanks to all our [contributors](https://github.com/arduino/arduino-cli/graphs/contributors)! :sparkles: - -## How to install - -### Get the latest package - -You have several options to install the latest version of the Arduino CLI -on your system. - -#### Install via Homebrew (macOS/Linux) - -The Arduino CLI is available as a Homebrew formula since version `0.5.0`: - -```console -brew update -brew install arduino-cli -``` - -#### Use the install script - -The easiest way to get the latest version of `arduino-cli` on any supported -platform is using the `install.sh` script: - -```console -curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh -``` - -The script will install `arduino-cli` at `$PWD/bin`, if you want to target a different directory, -for example `~/local/bin`, set the `BINDIR` environment variable like this: - -```console -curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/local/bin sh -``` - -#### Download the latest packages from Arduino CDN - -In order to get the latest stable release for your platform you can use the -following links: - -- [Linux 64 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_64bit.tar.gz) -- [Linux 32 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_32bit.tar.gz) -- [Linux ARM 64 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_ARM64.tar.gz) -- [Linux ARM 32 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_ARMv7.tar.gz) -- [Windows 64 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.zip) -- [Windows 32 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_32bit.zip) -- [Mac OSX](https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_macOS_64bit.tar.gz) - -These links return a `302: Found` response, redirecting to latest generated builds by replacing `latest` with the latest -available stable release. Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH`. - -**Deprecation notice:** Links in the form `http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-.tar.bz2` -won't be further updated. That URL will provide arduino-cli 0.3.7-alpha.preview, regardless of further releases. - -#### Download the latest package from the release page on GitHub - -Alternatively you can download one of the pre-built binaries for the supported -platforms from the -[release page](https://github.com/arduino/arduino-cli/releases). Once downloaded, -place the executable `arduino-cli` into a directory which is in your `PATH`. - -### Get a nightly build - -These builds are generated once a day from `master` branch starting at 01:00 GMT. -In order to get the latest nightly build for your platform, use the following links: - -- [Linux 64 bit](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_64bit.tar.gz) -- [Linux 32 bit](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_32bit.tar.gz) -- [Linux ARM 64 bit](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_ARM64.tar.gz) -- [Linux ARM 32 bit](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_ARMv7.tar.gz) -- [Windows 64 bit](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Windows_64bit.zip) -- [Windows 32 bit](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Windows_32bit.zip) -- [Mac OSX](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_macOS_64bit.tar.gz) - -These links return a `302: Found` response, redirecting to latest generated builds by replacing `latest` with the latest -available build date, using the format YYYYMMDD (i.e for 2019/Aug/06 `latest` is replaced with `20190806` ) - -Checksums for the nightly builds are available at -`https://downloads.arduino.cc/arduino-cli/nightly/nightly--checksums.txt` - -Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH`. - -### Build from source using Docker - -If you don't have a working Golang environment or if you want to build -`arduino-cli` targeting different platforms, you can use Docker to get a binary -directly from sources. From the project folder run: - -```console -docker run -v $PWD:/arduino-cli -w /arduino-cli -e PACKAGE_NAME_PREFIX='snapshot' arduino/arduino-cli:builder-1 goreleaser --rm-dist --snapshot --skip-publish -``` - -Once the build is over, you will find a `./dist/` folder containing the packages built out of -the current source tree. - -### Build from source - -If you're familiar with Golang or if you want to contribute to the project, you will probably -build the `arduino-cli` locally with your Go compiler. Please refer to the -[contributing](CONTRIBUTING.md) doc for setup instructions. - -## Getting Started - -The goal of the Arduino CLI is to be used by either including it in Makefile or in any kind of -script for the Command Line. The Arduino CLI aims to replace the majority of features the Arduino -IDE has without the graphical UI. - -### Step 1. Create a new sketch - -The command will create a new empty sketch named `MyFirstSketch` in the current directory - -```console -$ arduino-cli sketch new MyFirstSketch -Sketch created in: /home/luca/MyFirstSketch - -$ cat /home/luca/MyFirstSketch/MyFirstSketch.ino -void setup() { -} - -void loop() { -} -``` - -### Step 2. Modify your sketch - -Use your favourite file editor or IDE to modify the .ino file, in this example -under: `$HOME/MyFirstSketch/MyFirstSketch.ino` -and change the file to look like this one: - -```C -void setup() { - pinMode(LED_BUILTIN, OUTPUT); -} - -void loop() { - digitalWrite(LED_BUILTIN, HIGH); - delay(1000); - digitalWrite(LED_BUILTIN, LOW); - delay(1000); -} -``` - -### Step 3. Connect the board to your PC - -If you are running a fresh install of the arduino-cli you probably need to update the platform -indexes by running: - -```console -$ arduino-cli core update-index -Updating index: package_index.json downloaded -``` - -Now, just connect the board to your PCs by using the USB cable. (**Note**: Connecting through an FTDI adapter chip will show Unknown for the Board Name because the VID/PID is generic. Uploading should still work as long as you identify the correct FQBN). In this example we will use the -MKR1000 board: - -```console -$ arduino-cli board list -Port Type Board Name FQBN Core -/dev/ttyACM1 Serial Port (USB) Arduino/Genuino MKR1000 arduino:samd:mkr1000 arduino:samd -``` - -the board has been discovered but we need the correct core to program it, let's -install it! - -### Step 4. Install the core for your board - -From the output of the `board list` command, the right platform for the Arduino -MKR1000 is `arduino:samd`, we can install it with: - -```console -$ arduino-cli core install arduino:samd -Downloading tools... -arduino:arm-none-eabi-gcc@4.8.3-2014q1 downloaded -arduino:bossac@1.7.0 downloaded -arduino:openocd@0.9.0-arduino6-static downloaded -arduino:CMSIS@4.5.0 downloaded -arduino:CMSIS-Atmel@1.1.0 downloaded -arduino:arduinoOTA@1.2.0 downloaded -Downloading cores... -arduino:samd@1.6.19 downloaded -Installing tools... -Installing platforms... -Results: -arduino:samd@1.6.19 - Installed -arduino:arm-none-eabi-gcc@4.8.3-2014q1 - Installed -arduino:bossac@1.7.0 - Installed -arduino:openocd@0.9.0-arduino6-static - Installed -arduino:CMSIS@4.5.0 - Installed -arduino:CMSIS-Atmel@1.1.0 - Installed -arduino:arduinoOTA@1.2.0 - Installed -``` - -Now verify we have installed the core properly by running - -```console -$ arduino-cli core list -ID Installed Latest Name -arduino:samd 1.6.19 1.6.19 Arduino SAMD Boards (32-bits ARM Cortex-M0+) -``` - -If the board is not detected for any reason, you can list all the supported boards -with `arduino-cli board listall` and also search for a specific board: - -```console -$ arduino-cli board listall mkr -Board Name FQBN -Arduino MKR FOX 1200 arduino:samd:mkrfox1200 -Arduino MKR GSM 1400 arduino:samd:mkrgsm1400 -Arduino MKR WAN 1300 arduino:samd:mkrwan1300 -Arduino MKR WiFi 1010 arduino:samd:mkrwifi1010 -Arduino MKRZERO arduino:samd:mkrzero -Arduino/Genuino MKR1000 arduino:samd:mkr1000 -``` - -Great! Now we are ready to compile and upload the sketch. - -#### Adding 3rd party cores - -To use 3rd party core packages, pass a link to the the additional package index -file with the `--additional-urls` option to any command that supports additional -cores: - -```console -$ arduino-cli core update-index --additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json -$ -$ arduino-cli core search esp8266 --additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json -ID Version Name -esp8266:esp8266 2.5.2 esp8266 -``` - -To avoid passing the `--additional-urls` option every time you run a command, -you can list the URLs to additional package indexes in the CLI configuration -file. If you don't have a configuration file yet (it's the case of a fresh -install) you can create one with the command: - -```console -$ arduino-cli config init -Config file PATH: /home/user/.arduino15/arduino-cli.yaml -``` - -This will create a configuration file in its default location for the current -operating system and will print the full path to the file. - -For example, to add the ESP8266 core, edit the configration file and add the -following: - -```yaml -board_manager: - additional_urls: - - http://arduino.esp8266.com/stable/package_esp8266com_index.json -``` - -From now on, commands supporting custom cores will automatically use the -additional URL from the configuration file: - -```console -$ arduino-cli core update-index -Updating index: package_index.json downloaded -Updating index: package_esp8266com_index.json downloaded -Updating index: package_index.json downloaded - -$ arduino-cli core search esp8266 -ID Version Name -esp8266:esp8266 2.5.2 esp8266 -``` - -### Step 5. Compile the sketch - -To compile the sketch we have to run the `compile` command with the proper FQBN we just got in the -previous command. - -```console -$ arduino-cli compile --fqbn arduino:samd:mkr1000 MyFirstSketch -Sketch uses 9600 bytes (3%) of program storage space. Maximum is 262144 bytes. -``` - -### Step 6. Upload your sketch - -We can finally upload the sketch and see our board blinking, we now have to specify the serial port -used by our board other than the FQBN: - -```console -$ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 MyFirstSketch -No new serial port detected. -Atmel SMART device 0x10010005 found -Device : ATSAMD21G18A -Chip ID : 10010005 -Version : v2.0 [Arduino:XYZ] Dec 20 2016 15:36:43 -Address : 8192 -Pages : 3968 -Page Size : 64 bytes -Total Size : 248KB -Planes : 1 -Lock Regions : 16 -Locked : none -Security : false -Boot Flash : true -BOD : true -BOR : true -Arduino : FAST_CHIP_ERASE -Arduino : FAST_MULTI_PAGE_WRITE -Arduino : CAN_CHECKSUM_MEMORY_BUFFER -Erase flash -done in 0.784 seconds - -Write 9856 bytes to flash (154 pages) -[==============================] 100% (154/154 pages) -done in 0.069 seconds - -Verify 9856 bytes of flash with checksum. -Verify successful -done in 0.009 seconds -CPU reset. -``` - -### Step 7. Add libraries - -Now we can try to add a useful library to our sketch. We can at first look at the name of a library, -our favourite one is the wifi101, here the command to get more info: - -```console -$ arduino-cli lib search wifi101 -Name: "WiFi101OTA" - Author: Arduino - Maintainer: Arduino - Sentence: Update sketches to your board over WiFi - Paragraph: Requires an SD card and SAMD board - Website: http://www.arduino.cc/en/Reference/WiFi101OTA - Category: Other - Architecture: samd - Types: Arduino - Versions: [1.0.2, 1.0.0, 1.0.1] -Name: "WiFi101" - Author: Arduino - Maintainer: Arduino - Sentence: Network driver for ATMEL WINC1500 module (used on Arduino/Genuino Wifi Shield 101 and MKR1000 boards) - Paragraph: This library implements a network driver for devices based on the ATMEL WINC1500 wifi module - Website: http://www.arduino.cc/en/Reference/WiFi101 - Category: Communication - Architecture: * - Types: Arduino - Versions: [0.5.0, 0.6.0, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.15.2, 0.8.0, 0.9.0, 0.12.1, 0.14.1, 0.14.4, 0.14.5, 0.15.1, 0.7.0, 0.14.0, 0.14.2, 0.14.3, 0.9.1, 0.13.0, 0.15.0, 0.5.1] -``` - -We are now ready to install it! Please be sure to use the full name of the lib as specified in the -"Name:" section previously seen: - -```console -$ arduino-cli lib install "WiFi101" -Downloading libraries... -WiFi101@0.15.2 downloaded -Installed WiFi101@0.15.2 -``` - -## Inline Help - -`arduino-cli` is a container of commands, to see the full list just run: - -```console -$ arduino-cli -Arduino Command Line Interface (arduino-cli). - -Usage: - arduino-cli [command] - -Examples: -arduino [flags...] - -Available Commands: - board Arduino board commands. - compile Compiles Arduino sketches. - config Arduino Configuration Commands. - core Arduino Core operations. - help Help about any command - lib Arduino commands about libraries. - sketch Arduino CLI Sketch Commands. - upload Upload Arduino sketches. - version Shows version number of Arduino CLI. - .... -``` - -Each command has his own specific help that can be obtained with the `help` command, for example: - -```console -$ arduino-cli help core -Arduino Core operations. - -Usage: - arduino-cli core [command] - -Examples: -arduino-cli core update-index # to update the package index file. - -Available 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 cores. - update-index Updates the index of cores. - -Flags: - -h, --help help for core - -Global Flags: - --config-file string The custom config file (if not specified the default one will be used). - --debug Enables debug output (super verbose, used to debug the CLI). - --format string The output format, can be [text|json]. (default "text") - -Use "arduino-cli core [command] --help" for more information about a command. -``` - -## FAQ - -### Why the Arduino Uno/Mega/Duemilanove is not detected when I run `arduino-cli board list`? - -Because: - -- Your board is a cheaper clone, or -- It mounts a USB2Serial converter like FT232 or CH320: these chips always reports the same USB -VID/PID to the operating system, so the only thing that we know is that the board mounts that -specific USB2Serial chip, but we don't know which board is. - -### What is the core for the Uno/Mega/Nano/Duemilanove? - -`arduino:avr` - -### What is the FQBN for ...? - -- Arduino UNO: `arduino:avr:uno` -- Arduino Mega: `arduino:avr:mega` -- Arduino Nano: `arduino:avr:nano` or `arduino:avr:nano:cpu=atmega328old` if you have the old bootloader - -### How can I find the core/FQBN for a board? - -Update the core index to have latest boards informations: - -```console -$ arduino-cli core update-index -Updating index: package_index.json downloaded -``` - -See: - -Further help can be found in [this comment](https://github.com/arduino/arduino-cli/issues/138#issuecomment-459169051) in [#138](https://github.com/arduino/arduino-cli/issues/138). - -For a deeper understanding of how FQBN works, you should understand Arduino Hardware specification. -You can find more information in this [arduino/Arduino wiki page](https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5-3rd-party-Hardware-specification) - -## Using the gRPC interface - -The [client_example](./client_example) folder contains a sample program that -shows how to use gRPC interface of the CLI. diff --git a/README.rst b/README.rst new file mode 100644 index 00000000000..afd432ae0e8 --- /dev/null +++ b/README.rst @@ -0,0 +1,547 @@ +arduino-cli +=========== + +|Tests passing| |Nightly build| |codecov| + +``arduino-cli`` is an all-in-one solution that provides builder, +boards/library manager, uploader, discovery and many other tools needed +to use any Arduino compatible board and platforms. + +This software is currently under active development: anything can change +at any time, API and UI must be considered unstable. + +How to contribute +----------------- + +Contributions are welcome! + +Please read the document `How to contribute `__ which +will guide you through how to build the source code, run the tests, and +contribute your changes to the project. + +:sparkles: Thanks to all our +`contributors `__! +:sparkles: + +How to install +-------------- + +Get the latest package +~~~~~~~~~~~~~~~~~~~~~~ + +You have several options to install the latest version of the Arduino +CLI on your system. + +Install via Homebrew (macOS/Linux) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Arduino CLI is available as a Homebrew formula since version +``0.5.0``: + +.. code:: console + + brew update + brew install arduino-cli + +Use the install script +^^^^^^^^^^^^^^^^^^^^^^ + +The easiest way to get the latest version of ``arduino-cli`` on any +supported platform is using the ``install.sh`` script: + +.. code:: console + + curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh + +The script will install ``arduino-cli`` at ``$PWD/bin``, if you want to +target a different directory, for example ``~/local/bin``, set the +``BINDIR`` environment variable like this: + +.. code:: console + + curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/local/bin sh + +Download the latest packages from Arduino CDN +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to get the latest stable release for your platform you can use +the following links: + +- `Linux 64 + bit `__ +- `Linux 32 + bit `__ +- `Linux ARM 64 + bit `__ +- `Linux ARM 32 + bit `__ +- `Windows 64 + bit `__ +- `Windows 32 + bit `__ +- `Mac + OSX `__ + +These links return a ``302: Found`` response, redirecting to latest +generated builds by replacing ``latest`` with the latest available +stable release. Once downloaded, place the executable ``arduino-cli`` +into a directory which is in your ``PATH``. + +**Deprecation notice:** Links in the form +``http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-.tar.bz2`` +won’t be further updated. That URL will provide arduino-cli +0.3.7-alpha.preview, regardless of further releases. + +Download the latest package from the release page on GitHub +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Alternatively you can download one of the pre-built binaries for the +supported platforms from the `release +page `__. Once +downloaded, place the executable ``arduino-cli`` into a directory which +is in your ``PATH``. + +Get a nightly build +~~~~~~~~~~~~~~~~~~~ + +These builds are generated once a day from ``master`` branch starting at +01:00 GMT. In order to get the latest nightly build for your platform, +use the following links: + +- `Linux 64 + bit `__ +- `Linux 32 + bit `__ +- `Linux ARM 64 + bit `__ +- `Linux ARM 32 + bit `__ +- `Windows 64 + bit `__ +- `Windows 32 + bit `__ +- `Mac + OSX `__ + +These links return a ``302: Found`` response, redirecting to latest +generated builds by replacing ``latest`` with the latest available build +date, using the format YYYYMMDD (i.e for 2019/Aug/06 ``latest`` is +replaced with ``20190806`` ) + +Checksums for the nightly builds are available at +``https://downloads.arduino.cc/arduino-cli/nightly/nightly--checksums.txt`` + +Once downloaded, place the executable ``arduino-cli`` into a directory +which is in your ``PATH``. + +Build from source using Docker +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you don’t have a working Golang environment or if you want to build +``arduino-cli`` targeting different platforms, you can use Docker to get +a binary directly from sources. From the project folder run: + +.. code:: console + + docker run -v $PWD:/arduino-cli -w /arduino-cli -e PACKAGE_NAME_PREFIX='snapshot' arduino/arduino-cli:builder-1 goreleaser --rm-dist --snapshot --skip-publish + +Once the build is over, you will find a ``./dist/`` folder containing +the packages built out of the current source tree. + +Build from source +~~~~~~~~~~~~~~~~~ + +If you’re familiar with Golang or if you want to contribute to the +project, you will probably build the ``arduino-cli`` locally with your +Go compiler. Please refer to the `contributing `__ doc +for setup instructions. + +Getting Started +--------------- + +The goal of the Arduino CLI is to be used by either including it in +Makefile or in any kind of script for the Command Line. The Arduino CLI +aims to replace the majority of features the Arduino IDE has without the +graphical UI. + +Step 1. Create a new sketch +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The command will create a new empty sketch named ``MyFirstSketch`` in +the current directory + +.. code:: console + + $ arduino-cli sketch new MyFirstSketch + Sketch created in: /home/luca/MyFirstSketch + + $ cat /home/luca/MyFirstSketch/MyFirstSketch.ino + void setup() { + } + + void loop() { + } + +Step 2. Modify your sketch +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use your favourite file editor or IDE to modify the .ino file, in this +example under: ``$HOME/MyFirstSketch/MyFirstSketch.ino`` and change the +file to look like this one: + +.. code:: c + + void setup() { + pinMode(LED_BUILTIN, OUTPUT); + } + + void loop() { + digitalWrite(LED_BUILTIN, HIGH); + delay(1000); + digitalWrite(LED_BUILTIN, LOW); + delay(1000); + } + +Step 3. Connect the board to your PC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are running a fresh install of the arduino-cli you probably need +to update the platform indexes by running: + +.. code:: console + + $ arduino-cli core update-index + Updating index: package_index.json downloaded + +Now, just connect the board to your PCs by using the USB cable. +(**Note**: Connecting through an FTDI adapter chip will show Unknown for +the Board Name because the VID/PID is generic. Uploading should still +work as long as you identify the correct FQBN). In this example we will +use the MKR1000 board: + +.. code:: console + + $ arduino-cli board list + Port Type Board Name FQBN Core + /dev/ttyACM1 Serial Port (USB) Arduino/Genuino MKR1000 arduino:samd:mkr1000 arduino:samd + +the board has been discovered but we need the correct core to program +it, let’s install it! + +Step 4. Install the core for your board +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +From the output of the ``board list`` command, the right platform for +the Arduino MKR1000 is ``arduino:samd``, we can install it with: + +.. code:: console + + $ arduino-cli core install arduino:samd + Downloading tools... + arduino:arm-none-eabi-gcc@4.8.3-2014q1 downloaded + arduino:bossac@1.7.0 downloaded + arduino:openocd@0.9.0-arduino6-static downloaded + arduino:CMSIS@4.5.0 downloaded + arduino:CMSIS-Atmel@1.1.0 downloaded + arduino:arduinoOTA@1.2.0 downloaded + Downloading cores... + arduino:samd@1.6.19 downloaded + Installing tools... + Installing platforms... + Results: + arduino:samd@1.6.19 - Installed + arduino:arm-none-eabi-gcc@4.8.3-2014q1 - Installed + arduino:bossac@1.7.0 - Installed + arduino:openocd@0.9.0-arduino6-static - Installed + arduino:CMSIS@4.5.0 - Installed + arduino:CMSIS-Atmel@1.1.0 - Installed + arduino:arduinoOTA@1.2.0 - Installed + +Now verify we have installed the core properly by running + +.. code:: console + + $ arduino-cli core list + ID Installed Latest Name + arduino:samd 1.6.19 1.6.19 Arduino SAMD Boards (32-bits ARM Cortex-M0+) + +If the board is not detected for any reason, you can list all the +supported boards with ``arduino-cli board listall`` and also search for +a specific board: + +.. code:: console + + $ arduino-cli board listall mkr + Board Name FQBN + Arduino MKR FOX 1200 arduino:samd:mkrfox1200 + Arduino MKR GSM 1400 arduino:samd:mkrgsm1400 + Arduino MKR WAN 1300 arduino:samd:mkrwan1300 + Arduino MKR WiFi 1010 arduino:samd:mkrwifi1010 + Arduino MKRZERO arduino:samd:mkrzero + Arduino/Genuino MKR1000 arduino:samd:mkr1000 + +Great! Now we are ready to compile and upload the sketch. + +Adding 3rd party cores +^^^^^^^^^^^^^^^^^^^^^^ + +To use 3rd party core packages, pass a link to the the additional +package index file with the ``--additional-urls`` option to any command +that supports additional cores: + +.. code:: console + + $ arduino-cli core update-index --additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json + $ + $ arduino-cli core search esp8266 --additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json + ID Version Name + esp8266:esp8266 2.5.2 esp8266 + +To avoid passing the ``--additional-urls`` option every time you run a +command, you can list the URLs to additional package indexes in the CLI +configuration file. If you don’t have a configuration file yet (it’s the +case of a fresh install) you can create one with the command: + +.. code:: console + + $ arduino-cli config init + Config file PATH: /home/user/.arduino15/arduino-cli.yaml + +This will create a configuration file in its default location for the +current operating system and will print the full path to the file. + +For example, to add the ESP8266 core, edit the configration file and add +the following: + +.. code:: yaml + + board_manager: + additional_urls: + - http://arduino.esp8266.com/stable/package_esp8266com_index.json + +From now on, commands supporting custom cores will automatically use the +additional URL from the configuration file: + +.. code:: console + + $ arduino-cli core update-index + Updating index: package_index.json downloaded + Updating index: package_esp8266com_index.json downloaded + Updating index: package_index.json downloaded + + $ arduino-cli core search esp8266 + ID Version Name + esp8266:esp8266 2.5.2 esp8266 + +Step 5. Compile the sketch +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To compile the sketch we have to run the ``compile`` command with the +proper FQBN we just got in the previous command. + +.. code:: console + + $ arduino-cli compile --fqbn arduino:samd:mkr1000 MyFirstSketch + Sketch uses 9600 bytes (3%) of program storage space. Maximum is 262144 bytes. + +Step 6. Upload your sketch +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We can finally upload the sketch and see our board blinking, we now have +to specify the serial port used by our board other than the FQBN: + +.. code:: console + + $ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 MyFirstSketch + No new serial port detected. + Atmel SMART device 0x10010005 found + Device : ATSAMD21G18A + Chip ID : 10010005 + Version : v2.0 [Arduino:XYZ] Dec 20 2016 15:36:43 + Address : 8192 + Pages : 3968 + Page Size : 64 bytes + Total Size : 248KB + Planes : 1 + Lock Regions : 16 + Locked : none + Security : false + Boot Flash : true + BOD : true + BOR : true + Arduino : FAST_CHIP_ERASE + Arduino : FAST_MULTI_PAGE_WRITE + Arduino : CAN_CHECKSUM_MEMORY_BUFFER + Erase flash + done in 0.784 seconds + + Write 9856 bytes to flash (154 pages) + [==============================] 100% (154/154 pages) + done in 0.069 seconds + + Verify 9856 bytes of flash with checksum. + Verify successful + done in 0.009 seconds + CPU reset. + +Step 7. Add libraries +~~~~~~~~~~~~~~~~~~~~~ + +Now we can try to add a useful library to our sketch. We can at first +look at the name of a library, our favourite one is the wifi101, here +the command to get more info: + +.. code:: console + + $ arduino-cli lib search wifi101 + Name: "WiFi101OTA" + Author: Arduino + Maintainer: Arduino + Sentence: Update sketches to your board over WiFi + Paragraph: Requires an SD card and SAMD board + Website: http://www.arduino.cc/en/Reference/WiFi101OTA + Category: Other + Architecture: samd + Types: Arduino + Versions: [1.0.2, 1.0.0, 1.0.1] + Name: "WiFi101" + Author: Arduino + Maintainer: Arduino + Sentence: Network driver for ATMEL WINC1500 module (used on Arduino/Genuino Wifi Shield 101 and MKR1000 boards) + Paragraph: This library implements a network driver for devices based on the ATMEL WINC1500 wifi module + Website: http://www.arduino.cc/en/Reference/WiFi101 + Category: Communication + Architecture: * + Types: Arduino + Versions: [0.5.0, 0.6.0, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.15.2, 0.8.0, 0.9.0, 0.12.1, 0.14.1, 0.14.4, 0.14.5, 0.15.1, 0.7.0, 0.14.0, 0.14.2, 0.14.3, 0.9.1, 0.13.0, 0.15.0, 0.5.1] + +We are now ready to install it! Please be sure to use the full name of +the lib as specified in the “Name:” section previously seen: + +.. code:: console + + $ arduino-cli lib install "WiFi101" + Downloading libraries... + WiFi101@0.15.2 downloaded + Installed WiFi101@0.15.2 + +Inline Help +----------- + +``arduino-cli`` is a container of commands, to see the full list just +run: + +.. code:: console + + $ arduino-cli + Arduino Command Line Interface (arduino-cli). + + Usage: + arduino-cli [command] + + Examples: + arduino [flags...] + + Available Commands: + board Arduino board commands. + compile Compiles Arduino sketches. + config Arduino Configuration Commands. + core Arduino Core operations. + help Help about any command + lib Arduino commands about libraries. + sketch Arduino CLI Sketch Commands. + upload Upload Arduino sketches. + version Shows version number of Arduino CLI. + .... + +Each command has his own specific help that can be obtained with the +``help`` command, for example: + +.. code:: console + + $ arduino-cli help core + Arduino Core operations. + + Usage: + arduino-cli core [command] + + Examples: + arduino-cli core update-index # to update the package index file. + + Available 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 cores. + update-index Updates the index of cores. + + Flags: + -h, --help help for core + + Global Flags: + --config-file string The custom config file (if not specified the default one will be used). + --debug Enables debug output (super verbose, used to debug the CLI). + --format string The output format, can be [text|json]. (default "text") + + Use "arduino-cli core [command] --help" for more information about a command. + +FAQ +--- + +Why the Arduino Uno/Mega/Duemilanove is not detected when I run ``arduino-cli board list``? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Because: + +- Your board is a cheaper clone, or +- It mounts a USB2Serial converter like FT232 or CH320: these chips + always reports the same USB VID/PID to the operating system, so the + only thing that we know is that the board mounts that specific + USB2Serial chip, but we don’t know which board is. + +What is the core for the Uno/Mega/Nano/Duemilanove? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``arduino:avr`` + +What is the FQBN for …? +~~~~~~~~~~~~~~~~~~~~~~~ + +- Arduino UNO: ``arduino:avr:uno`` +- Arduino Mega: ``arduino:avr:mega`` +- Arduino Nano: ``arduino:avr:nano`` or + ``arduino:avr:nano:cpu=atmega328old`` if you have the old bootloader + +How can I find the core/FQBN for a board? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Update the core index to have latest boards informations: + +.. code:: console + + $ arduino-cli core update-index + Updating index: package_index.json downloaded + +See: +https://github.com/arduino/arduino-cli#step-4-find-and-install-the-right-core + +Further help can be found in `this +comment `__ +in `#138 `__. + +For a deeper understanding of how FQBN works, you should understand +Arduino Hardware specification. You can find more information in this +`arduino/Arduino wiki +page `__ + +Using the gRPC interface +------------------------ + +The `client_example <./client_example>`__ folder contains a sample +program that shows how to use gRPC interface of the CLI. + +.. |Tests passing| image:: https://github.com/Arduino/arduino-cli/workflows/test/badge.svg + :target: https://github.com/Arduino/arduino-cli/actions?workflow=test +.. |Nightly build| image:: https://github.com/Arduino/arduino-cli/workflows/nightly/badge.svg + :target: https://github.com/Arduino/arduino-cli/actions?workflow=nightly +.. |codecov| image:: https://codecov.io/gh/arduino/arduino-cli/branch/master/graph/badge.svg + :target: https://codecov.io/gh/arduino/arduino-cli From d689c31fcd2c3e5a106bf57cb7d42f0c86dabc0b Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 10:19:48 +0100 Subject: [PATCH 02/10] fix emojis --- README.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.rst b/README.rst index afd432ae0e8..2eca87ccd61 100644 --- a/README.rst +++ b/README.rst @@ -19,9 +19,7 @@ Please read the document `How to contribute `__ which will guide you through how to build the source code, run the tests, and contribute your changes to the project. -:sparkles: Thanks to all our -`contributors `__! -:sparkles: +:sparkles: Thanks to all our `contributors `__! :sparkles: How to install -------------- From 240b264909665d1d5094ba9e013e908eafe3a75e Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 10:27:23 +0100 Subject: [PATCH 03/10] fix emojis 2 --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 2eca87ccd61..56db65f9b93 100644 --- a/README.rst +++ b/README.rst @@ -19,7 +19,7 @@ Please read the document `How to contribute `__ which will guide you through how to build the source code, run the tests, and contribute your changes to the project. -:sparkles: Thanks to all our `contributors `__! :sparkles: +`:sparkles:` Thanks to all our `contributors `__! `:sparkles:` How to install -------------- From 0d09f2c916e3bebfd70fcac070d56aa8698a43e3 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 10:48:39 +0100 Subject: [PATCH 04/10] downloads links in table --- README.rst | 39 +++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 56db65f9b93..ff831bc4c74 100644 --- a/README.rst +++ b/README.rst @@ -7,8 +7,12 @@ arduino-cli boards/library manager, uploader, discovery and many other tools needed to use any Arduino compatible board and platforms. -This software is currently under active development: anything can change -at any time, API and UI must be considered unstable. + This software is currently under active development: anything can change + at any time, API and UI must be considered unstable until we release version + 1.0.0. + +.. contents:: **Table of Contents** + :backlinks: none How to contribute ----------------- @@ -65,20 +69,23 @@ Download the latest packages from Arduino CDN In order to get the latest stable release for your platform you can use the following links: -- `Linux 64 - bit `__ -- `Linux 32 - bit `__ -- `Linux ARM 64 - bit `__ -- `Linux ARM 32 - bit `__ -- `Windows 64 - bit `__ -- `Windows 32 - bit `__ -- `Mac - OSX `__ ++---------------+---------------------+---------------------+ +| **Linux** | `Linux 32 bit`_ | `Linux 64 bit`_ | ++---------------+---------------------+---------------------+ +| **Linux ARM** | `Linux ARM 32 bit`_ | `Linux ARM 64 bit`_ | ++---------------+---------------------+---------------------+ +| **Windows** | `Windows 32 bit`_ | `Windows 64 bit`_ | ++---------------+---------------------+---------------------+ +| **Mac OSX** | | `Mac OSX`_ | ++---------------+---------------------+---------------------+ + +.. _`Linux 64 bit`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_64bit.tar.gz +.. _`Linux 32 bit`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_32bit.tar.gz +.. _`Linux ARM 64 bit`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_ARM64.tar.gz +.. _`Linux ARM 32 bit`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Linux_ARMv7.tar.gz +.. _`Windows 64 bit`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.zip +.. _`Windows 32 bit`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_32bit.zip +.. _`Mac OSX`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_macOS_64bit.tar.gz These links return a ``302: Found`` response, redirecting to latest generated builds by replacing ``latest`` with the latest available From 5c3cc040f861a5e86ec5b96981395566e9278606 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 13:04:30 +0100 Subject: [PATCH 05/10] refactored the walkthrough --- README.rst | 400 ++++++++++++++++++++++++----------------------------- 1 file changed, 184 insertions(+), 216 deletions(-) diff --git a/README.rst b/README.rst index ff831bc4c74..8cab0278cb8 100644 --- a/README.rst +++ b/README.rst @@ -13,6 +13,7 @@ to use any Arduino compatible board and platforms. .. contents:: **Table of Contents** :backlinks: none + :depth: 2 How to contribute ----------------- @@ -113,20 +114,23 @@ These builds are generated once a day from ``master`` branch starting at 01:00 GMT. In order to get the latest nightly build for your platform, use the following links: -- `Linux 64 - bit `__ -- `Linux 32 - bit `__ -- `Linux ARM 64 - bit `__ -- `Linux ARM 32 - bit `__ -- `Windows 64 - bit `__ -- `Windows 32 - bit `__ -- `Mac - OSX `__ ++---------------+-----------------------------+-----------------------------+ +| **Linux** | `Nightly Linux 32 bit`_ | `Nightly Linux 64 bit`_ | ++---------------+-----------------------------+-----------------------------+ +| **Linux ARM** | `Nightly Linux ARM 32 bit`_ | `Nightly Linux ARM 64 bit`_ | ++---------------+-----------------------------+-----------------------------+ +| **Windows** | `Nightly Windows 32 bit`_ | `Nightly Windows 64 bit`_ | ++---------------+-----------------------------+-----------------------------+ +| **Mac OSX** | | `Nightly Mac OSX`_ | ++---------------+-----------------------------+-----------------------------+ + +.. _`Nightly Linux 64 bit`: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_64bit.tar.gz +.. _`Nightly Linux 32 bit`: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_32bit.tar.gz +.. _`Nightly Linux ARM 64 bit`: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_ARM64.tar.gz +.. _`Nightly Linux ARM 32 bit`: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_ARMv7.tar.gz +.. _`Nightly Windows 64 bit`: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Windows_64bit.zip +.. _`Nightly Windows 32 bit`: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Windows_32bit.zip +.. _`Nightly Mac OSX`: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_macOS_64bit.tar.gz These links return a ``302: Found`` response, redirecting to latest generated builds by replacing ``latest`` with the latest available build @@ -139,8 +143,13 @@ Checksums for the nightly builds are available at Once downloaded, place the executable ``arduino-cli`` into a directory which is in your ``PATH``. -Build from source using Docker -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Build from source +~~~~~~~~~~~~~~~~~ + +If you’re familiar with Golang or if you want to contribute to the +project, you will probably build the ``arduino-cli`` locally with your +Go compiler. Please refer to the `contributing `__ doc +for setup instructions. If you don’t have a working Golang environment or if you want to build ``arduino-cli`` targeting different platforms, you can use Docker to get @@ -153,46 +162,54 @@ a binary directly from sources. From the project folder run: Once the build is over, you will find a ``./dist/`` folder containing the packages built out of the current source tree. -Build from source -~~~~~~~~~~~~~~~~~ +How to use +---------- -If you’re familiar with Golang or if you want to contribute to the -project, you will probably build the ``arduino-cli`` locally with your -Go compiler. Please refer to the `contributing `__ doc -for setup instructions. +Despite there's no feature parity at the moment, Arduino CLI provides many of +the features you can find in the Arduino IDE, let's see some examples. -Getting Started ---------------- +Create a configuration file +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The goal of the Arduino CLI is to be used by either including it in -Makefile or in any kind of script for the Command Line. The Arduino CLI -aims to replace the majority of features the Arduino IDE has without the -graphical UI. +Arduino CLI doesn't strictly require a configuration file to work because the +command line interface any possible functionality. However, having one +can spare you a lot of typing when issuing a command, so let's create it +right ahead with: -Step 1. Create a new sketch -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. code:: console + + $ arduino-cli config init + Config file written: /home/luca/.arduino15/arduino-cli.yaml + +If you inspect ``arduino-cli.yaml`` contents, you'll find out the available +options with their respective default values. -The command will create a new empty sketch named ``MyFirstSketch`` in -the current directory +Create a new sketch +~~~~~~~~~~~~~~~~~~~ + +To create a new sketch named ``MyFirstSketch`` in the current directory, run +the following command: .. code:: console - $ arduino-cli sketch new MyFirstSketch - Sketch created in: /home/luca/MyFirstSketch + $ arduino-cli sketch new MyFirstSketch + Sketch created in: /home/luca/MyFirstSketch - $ cat /home/luca/MyFirstSketch/MyFirstSketch.ino - void setup() { - } +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: - void loop() { - } +.. code:: console + + $ cat $HOME/MyFirstSketch/MyFirstSketch.ino + void setup() { + } -Step 2. Modify your sketch -~~~~~~~~~~~~~~~~~~~~~~~~~~ + void loop() { + } -Use your favourite file editor or IDE to modify the .ino file, in this -example under: ``$HOME/MyFirstSketch/MyFirstSketch.ino`` and change the -file to look like this one: +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: .. code:: c @@ -207,22 +224,19 @@ file to look like this one: delay(1000); } -Step 3. Connect the board to your PC -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Connect the board to your PC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you are running a fresh install of the arduino-cli you probably need -to update the platform indexes by running: +The first thing to do upon a fresh install is to update the local cache of +available platforms and libraries by running: .. code:: console $ arduino-cli core update-index Updating index: package_index.json downloaded -Now, just connect the board to your PCs by using the USB cable. -(**Note**: Connecting through an FTDI adapter chip will show Unknown for -the Board Name because the VID/PID is generic. Uploading should still -work as long as you identify the correct FQBN). In this example we will -use the MKR1000 board: +After connecting the board to your PCs by using the USB cable, you should be +able to check whether it's been recognized by running: .. code:: console @@ -230,14 +244,30 @@ use the MKR1000 board: Port Type Board Name FQBN Core /dev/ttyACM1 Serial Port (USB) Arduino/Genuino MKR1000 arduino:samd:mkr1000 arduino:samd -the board has been discovered but we need the correct core to program -it, let’s install it! +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: + +.. code:: console + + $ arduino-cli board listall mkr + Board Name FQBN + Arduino MKR FOX 1200 arduino:samd:mkrfox1200 + Arduino MKR GSM 1400 arduino:samd:mkrgsm1400 + Arduino MKR WAN 1300 arduino:samd:mkrwan1300 + Arduino MKR WiFi 1010 arduino:samd:mkrwifi1010 + Arduino MKRZERO arduino:samd:mkrzero + Arduino/Genuino MKR1000 arduino:samd:mkr1000 -Step 4. Install the core for your board -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Install the core for your board +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -From the output of the ``board list`` command, the right platform for -the Arduino MKR1000 is ``arduino:samd``, we can install it with: +To install the ``arduino:samd`` platform core, run the following: .. code:: console @@ -262,7 +292,7 @@ the Arduino MKR1000 is ``arduino:samd``, we can install it with: arduino:CMSIS-Atmel@1.1.0 - Installed arduino:arduinoOTA@1.2.0 - Installed -Now verify we have installed the core properly by running +Now verify we have installed the core properly by running: .. code:: console @@ -270,29 +300,14 @@ Now verify we have installed the core properly by running ID Installed Latest Name arduino:samd 1.6.19 1.6.19 Arduino SAMD Boards (32-bits ARM Cortex-M0+) -If the board is not detected for any reason, you can list all the -supported boards with ``arduino-cli board listall`` and also search for -a specific board: - -.. code:: console - - $ arduino-cli board listall mkr - Board Name FQBN - Arduino MKR FOX 1200 arduino:samd:mkrfox1200 - Arduino MKR GSM 1400 arduino:samd:mkrgsm1400 - Arduino MKR WAN 1300 arduino:samd:mkrwan1300 - Arduino MKR WiFi 1010 arduino:samd:mkrwifi1010 - Arduino MKRZERO arduino:samd:mkrzero - Arduino/Genuino MKR1000 arduino:samd:mkr1000 - Great! Now we are ready to compile and upload the sketch. Adding 3rd party cores ^^^^^^^^^^^^^^^^^^^^^^ -To use 3rd party core packages, pass a link to the the additional -package index file with the ``--additional-urls`` option to any command -that supports additional cores: +If your board requires 3rd party core packages to work, you can pass a link to +the the additional package index file with the ``--additional-urls`` option to +any command that require a platform core to work: .. code:: console @@ -302,21 +317,12 @@ that supports additional cores: ID Version Name esp8266:esp8266 2.5.2 esp8266 -To avoid passing the ``--additional-urls`` option every time you run a -command, you can list the URLs to additional package indexes in the CLI -configuration file. If you don’t have a configuration file yet (it’s the -case of a fresh install) you can create one with the command: - -.. code:: console +To avoid passing the ``--additional-urls`` option every time you run a command, +you can list the URLs to additional package indexes in the Arduino CLI +configuration file. - $ arduino-cli config init - Config file PATH: /home/user/.arduino15/arduino-cli.yaml - -This will create a configuration file in its default location for the -current operating system and will print the full path to the file. - -For example, to add the ESP8266 core, edit the configration file and add -the following: +For example, to add the ESP8266 core, edit the configration file and change the +``board_manager`` settings as follows: .. code:: yaml @@ -338,22 +344,19 @@ additional URL from the configuration file: ID Version Name esp8266:esp8266 2.5.2 esp8266 -Step 5. Compile the sketch -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Compile and upload the sketch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To compile the sketch we have to run the ``compile`` command with the -proper FQBN we just got in the previous command. +To compile the sketch you run the ``compile`` command passing the proper FQBN +string: .. code:: console $ arduino-cli compile --fqbn arduino:samd:mkr1000 MyFirstSketch Sketch uses 9600 bytes (3%) of program storage space. Maximum is 262144 bytes. -Step 6. Upload your sketch -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We can finally upload the sketch and see our board blinking, we now have -to specify the serial port used by our board other than the FQBN: +To upload the sketch to your board, run the following command, this time also +providing the serial port where the board is connected: .. code:: console @@ -389,113 +392,106 @@ to specify the serial port used by our board other than the FQBN: done in 0.009 seconds CPU reset. -Step 7. Add libraries -~~~~~~~~~~~~~~~~~~~~~ - -Now we can try to add a useful library to our sketch. We can at first -look at the name of a library, our favourite one is the wifi101, here -the command to get more info: +Add libraries +~~~~~~~~~~~~~ -.. code:: console - - $ arduino-cli lib search wifi101 - Name: "WiFi101OTA" - Author: Arduino - Maintainer: Arduino - Sentence: Update sketches to your board over WiFi - Paragraph: Requires an SD card and SAMD board - Website: http://www.arduino.cc/en/Reference/WiFi101OTA - Category: Other - Architecture: samd - Types: Arduino - Versions: [1.0.2, 1.0.0, 1.0.1] - Name: "WiFi101" - Author: Arduino - Maintainer: Arduino - Sentence: Network driver for ATMEL WINC1500 module (used on Arduino/Genuino Wifi Shield 101 and MKR1000 boards) - Paragraph: This library implements a network driver for devices based on the ATMEL WINC1500 wifi module - Website: http://www.arduino.cc/en/Reference/WiFi101 - Category: Communication - Architecture: * - Types: Arduino - Versions: [0.5.0, 0.6.0, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.15.2, 0.8.0, 0.9.0, 0.12.1, 0.14.1, 0.14.4, 0.14.5, 0.15.1, 0.7.0, 0.14.0, 0.14.2, 0.14.3, 0.9.1, 0.13.0, 0.15.0, 0.5.1] - -We are now ready to install it! Please be sure to use the full name of -the lib as specified in the “Name:” section previously seen: +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: .. code:: console - $ arduino-cli lib install "WiFi101" - Downloading libraries... - WiFi101@0.15.2 downloaded - Installed WiFi101@0.15.2 - -Inline Help ------------ - -``arduino-cli`` is a container of commands, to see the full list just -run: + $ arduino-cli lib search debouncer + Name: "Debouncer" + Author: hideakitai + Maintainer: hideakitai + Sentence: Debounce library for Arduino + Paragraph: Debounce library for 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 library for Arduino + 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. + Website: https://github.com/ubidefeo/FTDebouncer + Category: Uncategorized + Architecture: * + Types: Contributed + Versions: [1.3.0] + Name: "SoftTimer" + Author: Balazs Kelemen + Maintainer: Balazs Kelemen + Sentence: SoftTimer is a lightweight pseudo multitasking solution for Arduino. + 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. + 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 is ``FTDebouncer``, can install it by running: .. code:: console - $ arduino-cli - Arduino Command Line Interface (arduino-cli). - - Usage: - arduino-cli [command] + $ arduino-cli lib install FTDebouncer + FTDebouncer depends on FTDebouncer@1.3.0 + Downloading FTDebouncer@1.3.0... + FTDebouncer@1.3.0 downloaded + Installing FTDebouncer@1.3.0... + Installed FTDebouncer@1.3.0 - Examples: - arduino [flags...] +Getting help +------------ - Available Commands: - board Arduino board commands. - compile Compiles Arduino sketches. - config Arduino Configuration Commands. - core Arduino Core operations. - help Help about any command - lib Arduino commands about libraries. - sketch Arduino CLI Sketch Commands. - upload Upload Arduino sketches. - version Shows version number of Arduino CLI. - .... - -Each command has his own specific help that can be obtained with the -``help`` command, for example: +``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: .. code:: console - $ arduino-cli help core - Arduino Core operations. + $ arduino-cli help core + Arduino Core operations. - Usage: - arduino-cli core [command] + Usage: + arduino-cli core [command] - Examples: - arduino-cli core update-index # to update the package index file. + Examples: + ./arduino-cli core update-index - Available 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 cores. - update-index Updates the index of cores. + Available 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 the package index. + 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 core + Flags: + -h, --help help for core - Global Flags: - --config-file string The custom config file (if not specified the default one will be used). - --debug Enables debug output (super verbose, used to debug the CLI). - --format string The output format, can be [text|json]. (default "text") + Global Flags: + --additional-urls strings Additional URLs for the board 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. + Use "arduino-cli core [command] --help" for more information about a command. -FAQ ---- +Troubleshooting +--------------- -Why the Arduino Uno/Mega/Duemilanove is not detected when I run ``arduino-cli board list``? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Arduino Uno/Mega/Duemilanove is not detected when you + run ``arduino-cli board list`` -Because: +Possible causes: - Your board is a cheaper clone, or - It mounts a USB2Serial converter like FT232 or CH320: these chips @@ -503,35 +499,7 @@ Because: only thing that we know is that the board mounts that specific USB2Serial chip, but we don’t know which board is. -What is the core for the Uno/Mega/Nano/Duemilanove? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``arduino:avr`` - -What is the FQBN for …? -~~~~~~~~~~~~~~~~~~~~~~~ - -- Arduino UNO: ``arduino:avr:uno`` -- Arduino Mega: ``arduino:avr:mega`` -- Arduino Nano: ``arduino:avr:nano`` or - ``arduino:avr:nano:cpu=atmega328old`` if you have the old bootloader - -How can I find the core/FQBN for a board? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Update the core index to have latest boards informations: - -.. code:: console - - $ arduino-cli core update-index - Updating index: package_index.json downloaded - -See: -https://github.com/arduino/arduino-cli#step-4-find-and-install-the-right-core - -Further help can be found in `this -comment `__ -in `#138 `__. + What's the FQBN string? For a deeper understanding of how FQBN works, you should understand Arduino Hardware specification. You can find more information in this From ba6f66e583dbe141ad4473d752bb885cc3a2a7db Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 13:08:41 +0100 Subject: [PATCH 06/10] minor fix to cmd example --- README.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.rst b/README.rst index 8cab0278cb8..a51ec6a0f49 100644 --- a/README.rst +++ b/README.rst @@ -311,8 +311,6 @@ any command that require a platform core to work: .. code:: console - $ arduino-cli core update-index --additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json - $ $ arduino-cli core search esp8266 --additional-urls http://arduino.esp8266.com/stable/package_esp8266com_index.json ID Version Name esp8266:esp8266 2.5.2 esp8266 From 9dc3ec68628b28eacf5c1769ac1a66d71e983282 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 13:17:59 +0100 Subject: [PATCH 07/10] slim down install instructions --- README.rst | 40 ++++++++++++++-------------------------- 1 file changed, 14 insertions(+), 26 deletions(-) diff --git a/README.rst b/README.rst index a51ec6a0f49..bfa1ee331a5 100644 --- a/README.rst +++ b/README.rst @@ -64,11 +64,13 @@ target a different directory, for example ``~/local/bin``, set the curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/local/bin sh -Download the latest packages from Arduino CDN -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Download the latest packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to get the latest stable release for your platform you can use -the following links: +You can download the latest version of the pre-built binaries for the supported +platforms from the `release page `__ +or following the links in the following table. Once downloaded, extract the +binary ``arduino-cli`` into a directory which is in your ``PATH``. +---------------+---------------------+---------------------+ | **Linux** | `Linux 32 bit`_ | `Linux 64 bit`_ | @@ -88,31 +90,17 @@ the following links: .. _`Windows 32 bit`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_32bit.zip .. _`Mac OSX`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_macOS_64bit.tar.gz -These links return a ``302: Found`` response, redirecting to latest -generated builds by replacing ``latest`` with the latest available -stable release. Once downloaded, place the executable ``arduino-cli`` -into a directory which is in your ``PATH``. - **Deprecation notice:** Links in the form ``http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-.tar.bz2`` -won’t be further updated. That URL will provide arduino-cli -0.3.7-alpha.preview, regardless of further releases. - -Download the latest package from the release page on GitHub -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +won’t be further updated. That URL will provide the version +``0.3.7-alpha.preview``, regardless of further releases. -Alternatively you can download one of the pre-built binaries for the -supported platforms from the `release -page `__. Once -downloaded, place the executable ``arduino-cli`` into a directory which -is in your ``PATH``. - -Get a nightly build -~~~~~~~~~~~~~~~~~~~ +Download a nightly build +~~~~~~~~~~~~~~~~~~~~~~~~ -These builds are generated once a day from ``master`` branch starting at -01:00 GMT. In order to get the latest nightly build for your platform, -use the following links: +These builds are generated everyday at 01:00 GMT from the ``master`` branch and +should be considered unstable. In order to get the latest nightly build +available for the supported platform, use the following links: +---------------+-----------------------------+-----------------------------+ | **Linux** | `Nightly Linux 32 bit`_ | `Nightly Linux 64 bit`_ | @@ -140,7 +128,7 @@ replaced with ``20190806`` ) Checksums for the nightly builds are available at ``https://downloads.arduino.cc/arduino-cli/nightly/nightly--checksums.txt`` -Once downloaded, place the executable ``arduino-cli`` into a directory +Once downloaded, extract the executable ``arduino-cli`` into a directory which is in your ``PATH``. Build from source From e5ba599702b0841638df6e832cf8085a7cfd4c31 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 13:19:18 +0100 Subject: [PATCH 08/10] reword --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index bfa1ee331a5..f03a92945b6 100644 --- a/README.rst +++ b/README.rst @@ -29,7 +29,7 @@ contribute your changes to the project. How to install -------------- -Get the latest package +Get the latest version ~~~~~~~~~~~~~~~~~~~~~~ You have several options to install the latest version of the Arduino @@ -95,8 +95,8 @@ binary ``arduino-cli`` into a directory which is in your ``PATH``. won’t be further updated. That URL will provide the version ``0.3.7-alpha.preview``, regardless of further releases. -Download a nightly build -~~~~~~~~~~~~~~~~~~~~~~~~ +Get a nightly build +~~~~~~~~~~~~~~~~~~~ These builds are generated everyday at 01:00 GMT from the ``master`` branch and should be considered unstable. In order to get the latest nightly build From fd6f86efa04189cea73eafce811210729a26c356 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 13:20:38 +0100 Subject: [PATCH 09/10] highlight deprecation notice --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index f03a92945b6..4eb234e2fd1 100644 --- a/README.rst +++ b/README.rst @@ -90,10 +90,10 @@ binary ``arduino-cli`` into a directory which is in your ``PATH``. .. _`Windows 32 bit`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_32bit.zip .. _`Mac OSX`: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_macOS_64bit.tar.gz -**Deprecation notice:** Links in the form -``http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-.tar.bz2`` -won’t be further updated. That URL will provide the version -``0.3.7-alpha.preview``, regardless of further releases. + Deprecation notice: links in the form + ``http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-.tar.bz2`` + won’t be further updated. That URL will provide the version + ``0.3.7-alpha.preview``, regardless of further releases. Get a nightly build ~~~~~~~~~~~~~~~~~~~ From 61bca41b3363b3b5891bdbf4fac3d97c101fe146 Mon Sep 17 00:00:00 2001 From: Massimiliano Pippi Date: Fri, 20 Dec 2019 14:43:47 +0100 Subject: [PATCH 10/10] missing verb --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 4eb234e2fd1..b9a87b13751 100644 --- a/README.rst +++ b/README.rst @@ -160,7 +160,7 @@ Create a configuration file ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Arduino CLI doesn't strictly require a configuration file to work because the -command line interface any possible functionality. However, having one +command line interface provides any possible functionality. However, having one can spare you a lot of typing when issuing a command, so let's create it right ahead with: