Skip to content

GitLab

A
arduino-cli
Unverified Commit f5b6c24d authored by Massimiliano Pippi's avatar Massimiliano Pippi
Browse files
Options

add how to contribute

parent a36e3502
Hide whitespace changes
Inline Side-by-side
Showing with 232 additions and 96 deletions
CONTRIBUTING.md 0 → 100644
View file @ f5b6c24d
# How to contribute
First of all, thanks for contributing!
This document provides some basic guidelines for contributing to this repository. To propose
improvements or fix a bug, feel free to submit a PR.
## Legal requirements
Before we can accept your contributions you have to sign the [Contributor License Agreement][0]
## Prerequisites
To build the Arduino CLI from sources you need the following tools to be available in your local
enviroment:
* [Go][1] version 1.12 or later
* [Taskfile][2] to help you run the most common tasks from the command line
If you want to run integration tests you will also need:
* A serial port with an Arduino device attached
* A working [Python][3] environment, version 3.5 or later
## Building the source code
From the project folder root, just run:
```shell
task build
```
The project uses Go modules so dependencies will be downloaded automatically, you should end with
an `arduino-cli` executable in the same folder.
## Running the tests
There are several checks and test suites in place to ensure the code works as expected but also it
is written in a way that's consistent across the whole codebase. Such tests can be run one after
another by running the command:
```shell
task test
```
If you want to only run unit tests and skip other checks, you can run:
```shell
task test-unit
```
Similarly, if you're only interested in running integration tests, you can do (be sure to read the
part dedicated to integration tests if something doesn't work):
```shell
task test-integration
```
### Integration tests
Being a command line interface, Arduino CLI is heavily interactive and it has to stay consistent
in accepting the user input and providing the expected output and proper exit codes. On top of this,
many Arduino CLI features involve communicating with external devices, most likely through a serial
port, so unit tests can only put our confidence that the code is working so far.
For these reasons, in addition to regular unit tests the project has a suite of integration tests
that actually run Arduino CLI in a different process and assess the options are correctly
understood and the output is what we expect.
To run the full suite of integration tests you need an Arduino device attached to a serial port and
a working Python environment. Chances are that you already have Python installed in your system, if
this is not the case you can [download][3] the official distribution or use the package manager
provided by your Operating System.
Some dependencies need to be installed before running the tests and to avoid polluting your global
Python enviroment with dependencies that might be only used by the Arduino CLI, you can use a
[virtual environment][4]. There are many ways to manage virtual environments, for example you can
use a productivity tool called [hatch][5]. First you need to install it (you might need to `sudo`
the following command):
```shell
pip3 install --user hatch
```
Then you can create a virtual environment to be used while working on Arduino CLI:
```shell
hatch env arduino-cli
```
At this point the virtual environment was created and you need to make it active every time you
open a new terminal session with the following command:
```shell
hatch shell arduino-cli
```
From now on, every package installed by Python will be confined to the `arduino-cli` virtual
environment, so you can proceed installing the dependencies required with:
```shell
pip install -r test/requirements.txt
```
If the last step was successfull, you should be able to run the tests with:
```shell
task test-integration
```
## Pull Requests
In order to ease code reviews and have your contributions merged faster, here is a list of items
you can check before submitting a PR:
* Create small PRs that are narrowly focused on addressing a single concern.
* PR titles indirectly become part of the CHANGELOG so it's crucial to provide a good
record of **what** change is being made in the title; **why** it was made will go in the
PR description, along with a link to a GitHub issue if it exists.
* write tests for the code you wrote.
* open your PR against the `master` branch.
* Maintain **clean commit history** and use **meaningful commit messages**.
PRs with messy commit history are difficult to review and require a lot of work to be merged.
* Your PR must pass all CI tests before we will merge it. If you're seeing an error and don't think
it's your fault, it may not be! The reviewer will help you if there are test failures that seem
not related to the change you are making.
## Additional settings
If you need to push a commit that's only shipping documentation changes or example files, thus a
complete no-op for the test suite, please start the commit message with the string **[skip ci]**
to skip the build and give that slot to someone else who does need it.
If your PR doesn't need to be included in the changelog, please start the PR title with the string
**[skip changelog]**
[0]: https://cla-assistant.io/arduino/arduino-cli
[1]: https://golang.org/doc/install
[2]: https://taskfile.dev/#/installation
[3]: https://www.python.org/downloads/
[4]: https://docs.python.org/3/tutorial/venv.html
[5]: https://github.com/ofek/hatch
README.md
View file @ f5b6c24d
......@@ -2,12 +2,20 @@
[![Build Status](https://cloud.drone.io/api/badges/arduino/arduino-cli/status.svg)](https://cloud.drone.io/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.
`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 in alpha state: new features will be added and some may be changed.
It will be soon used as a building block in the Arduino IDE and Arduino Create.
## 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.
## How to install
### Download the latest stable release
......@@ -16,8 +24,8 @@ This is **not yet available** until the first stable version is released.
#### Download the latest unstable "alpha" preview
Please note that these are **preview** build, they may have bugs, some features may not work or may be changed without notice,
the latest preview version is `0.3.7-alpha.preview`:
Please note that these are **preview** builds, they may have bugs, some features may not work or may
be changed without notice, the latest preview version is `0.3.7-alpha.preview`:
- [Linux 64 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-linux64.tar.bz2)
- [Linux 32 bit](https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-linux32.tar.bz2)
......@@ -26,7 +34,8 @@ the latest preview version is `0.3.7-alpha.preview`:
- [Windows](https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-windows.zip)
- [Mac OSX](https://downloads.arduino.cc/arduino-cli/arduino-cli-latest-macosx.zip)
Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH` environment variable.
Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH`
environment variable.
#### Download the nightly build
......@@ -39,7 +48,8 @@ These builds are generated once a day from `master` branch starting at 23:00 UTC
- [Windows](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli-nightly-latest-windows.zip)
- [Mac OSX](https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli-nightly-latest-macosx.zip)
Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH` environment variable.
Once downloaded, place the executable `arduino-cli` into a directory which is in your `PATH`
environment variable.
### Build the latest "bleeding-edge" from source
......@@ -52,8 +62,9 @@ You may want to copy the executable into a directory which is in your `PATH` env
## Usage
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.
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.
## Getting Started
......@@ -89,22 +100,26 @@ and change the file to look like this one:
### 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:
If you are running a fresh install of the arduino-cli you probably need to update the platform
indexes by running:
$ arduino-cli core update-index
Updating index: package_index.json downloaded
Now, just connect the board to your PCs by using the USB cable. In this example we will use the MKR1000 board.
Now, just connect the board to your PCs by using the USB cable. In this example we will use the
MKR1000 board:
$ arduino-cli board list
FQBN Port ID Board Name
/dev/ttyACM0 2341:804E unknown
the board has been discovered but we do not have the correct core to program it yet. Let's install it!
the board has been discovered but we do not have the correct core to program it yet.
Let's install it!
### Step 4. Find and install the right core
We have to look at the core available with the `core search` command. It will provide a list of available cores matching the name arduino
We have to look at the core available with the `core search` command. It will provide a list of
available cores matching the name arduino:
$ arduino-cli core search arduino
Searching for platforms matching 'arduino'
......@@ -165,13 +180,13 @@ If the board is not detected for any reason, you can list all the supported boar
with `arduino-cli board listall` and also search for a specific board:
$ 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
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 have the Board FQBN (Fully Qualified Board Name) `arduino:samd:mkr1000`
and the Board Name look good, we are ready to compile and upload the sketch
......@@ -193,14 +208,16 @@ And then run:
### 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.
To compile the sketch we have to run the `compile` command with the proper FQBN we just got in the
previous command.
$ arduino-cli compile --fqbn arduino:samd:mkr1000 Arduino/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:
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:
$ arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:samd:mkr1000 Arduino/MyFirstSketch
No new serial port detected.
......@@ -236,7 +253,8 @@ We can finally upload the sketch and see our board blinking, we now have to spec
### 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
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:
$ arduino-cli lib search wifi101
Name: "WiFi101OTA"
......@@ -260,7 +278,8 @@ Now we can try to add a useful library to our sketch. We can at first look at th
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
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:
$ arduino-cli lib install "WiFi101"
Downloading libraries...
......@@ -271,110 +290,85 @@ We are now ready to install it! Please be sure to use the full name of the lib a
`arduino-cli` is a container of commands, to see the full list just run:
```bash
$ arduino-cli
Arduino Command Line Interface (arduino-cli).
Usage:
arduino-cli [command]
Examples:
arduino <command> [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.
....
```
$ arduino-cli
Arduino Command Line Interface (arduino-cli).
Each command has his own specific help that can be obtained with the `help` command, for example:
Usage:
arduino-cli [command]
```bash
$ arduino-cli help core
Arduino Core operations.
Examples:
arduino <command> [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:
Usage:
arduino-cli core [command]
$ arduino-cli help core
Arduino Core operations.
Examples:
arduino-cli core update-index # to update the package index file.
Usage:
arduino-cli core [command]
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.
Examples:
arduino-cli core update-index # to update the package index file.
Flags:
-h, --help help for core
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.
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")
Flags:
-h, --help help for core
Use "arduino-cli core [command] --help" for more information about a command.
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
## FAQ
#### Why the Arduino Uno/Mega/Duemilanove is not detected when I run `arduino-cli board list`?
### 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.
- 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?
### What is the core for the Uno/Mega/Nano/Duemilanove?
`arduino:avr`
#### What is the FQBN for ...?
### 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?
### How can I find the core/FQBN for a board?
Update the core index to have latest boards informations:
$ 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
See: <https://github.com/arduino/arduino-cli#step-4-find-and-install-the-right-core>
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)
# Testing
Currently Unit and Integration test are available for launch in 2 ways:
1. classic `go test ./...` to launch both unit and integration test
2. via [task](https://taskfile.dev) that includes the following options:
```
* build: Build the project
* check: Check fmt and lint, `legacy` will be skipped
* check-legacy: Check fmt and lint for the `legacy` package
* protoc: Compile protobuf definitions
* rpc-client: Run the rpc client test routine (server must be already started)
* test: Run the full testsuite, `legacy` will be skipped
* test-integration: Run integration tests only
* test-legacy: Run tests for the `legacy` package
* test-unit: Run unit tests only
* test-unit-race: Run unit tests only with race condition detection
```
For Example to launch unit tests only run: `task test-unit`
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)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment