Unverified Commit bdcfd89e authored by Massimiliano Pippi's avatar Massimiliano Pippi Committed by GitHub

[skip changelog] Revamp the README (#603)

* fix builds when merging PRs

* move contributing guidelines into docs

* restore markdown format for the README

* move away documentation from the README, use dedicated pages

* add logo
parent 07e05203
...@@ -2,6 +2,10 @@ name: docs ...@@ -2,6 +2,10 @@ name: docs
on: on:
pull_request: pull_request:
types:
- opened
- synchronize
- closed
paths: paths:
- 'docs/**' - 'docs/**'
- 'docsgen/**' - 'docsgen/**'
......
# arduino-cli
![cli-logo](./docs/img/featured-CLI.png)
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.
[![tests-badge]](https://github.com/Arduino/arduino-cli/actions?workflow=test)
[![nightly-badge]](https://github.com/Arduino/arduino-cli/actions?workflow=nightly)
[![codecov-badge]](https://codecov.io/gh/arduino/arduino-cli)
> **Note:** 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.
## Docs
For guidance on installation and development, see the [User documentation].
## Quickstart
1. [Install] the Arduino CLI
2. Follow the [Getting Started] guide to check out what the CLI can do
3. Browse the [Commands reference] to see all the available commands
4. Should you have an issue, read the [FAQ] page
## How to contribute
Contributions are welcome!
Please read the document [How to contribute] which will show you how to build
the source code, run the tests, and contribute your changes to the project.
:sparkles: Thanks to all our [contributors]! :sparkles:
[tests-badge]: https://github.com/Arduino/arduino-cli/workflows/test/badge.svg
[nightly-badge]: https://github.com/Arduino/arduino-cli/workflows/nightly/badge.svg
[codecov-badge]: https://codecov.io/gh/arduino/arduino-cli/branch/master/graph/badge.svg
[User documentation]: https://arduino.github.io/arduino-cli/
[Getting Started]: https://arduino.github.io/arduino-cli/getting-started/
[Commands reference]: https://arduino.github.io/arduino-cli/commands/
[FAQ]: https://arduino.github.io/arduino-cli/FAQ/
[How to contribute]: https://arduino.github.io/arduino-cli/CONTRIBUTING/
[contributors]: https://github.com/arduino/arduino-cli/graphs/contributors
This diff is collapsed.
## Arduino Uno/Mega/Duemilanove is not detected
When you run `arduino-cli board list`, your board doesn't show up. Possible causes:
- 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'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
[arduino/Arduino wiki page][0].
[0]: https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5-3rd-party-Hardware-specification
Despite there's no feature parity at the moment, Arduino CLI provides many of 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. the features you can find in the Arduino IDE, let's see some examples.
## Before you start
`arduino-cli` is a container of commands and each command has its own
dedicated help text that can be shown with the `help` command like this:
```console
$ arduino-cli help core
Arduino Core operations.
Usage:
arduino-cli core [command]
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 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
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.
```
## Create a configuration file ## Create a configuration file
Arduino CLI doesn't strictly require a configuration file to work because the Arduino CLI doesn't strictly require a configuration file to work because the
......
...@@ -5,152 +5,21 @@ and platforms. ...@@ -5,152 +5,21 @@ and platforms.
## Installation ## Installation
You have several options to install the latest version of the Arduino You have several options to install the latest version of the Arduino
CLI on your system. CLI on your system, see the [installation] page.
### Install via Homebrew (macOS/Linux)
The Arduino CLI is available as a Homebrew formula since version
`0.5.0`:
```sh
brew update
brew install arduino-cli
```
### Use the install script
The easiest way to get the latest version of the Arduino CLI on any
supported platform is using the `install.sh` script:
```sh
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
```
The script will install `arduino-cli` at `$PWD/bin` but if you want to target a
different directory, for example `~/local/bin`, set the `BINDIR` environment
variable like this:
```sh
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/local/bin sh
```
### Download the latest packages
You can download the latest version of the pre-built binaries for the supported
platforms from the [release page](https://github.com/arduino/arduino-cli/releases)
or following the links in the following table. Once downloaded, extract the
binary `arduino-cli` into a directory that's is in your `PATH`.
Platform | | |
--------- | ------------------ | ------------------ |
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
> **Deprecation notice**: links in the form
`http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-<platform>.tar.bz2`
won’t be further updated. That URL will provide the version
`0.3.7-alpha.preview`, regardless of further releases.
### Download 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
available for the supported platform, use the following links:
Platform | | |
--------- | -------------------------- | -------------------------- |
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 | | [Mac OSX] |
[Nightly Linux 64 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_64bit.tar.gz
[Nightly Windows 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
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-<DATE>-checksums.txt`
Once downloaded, extract the executable `arduino-cli` into a directory
which is in your ``PATH``.
### 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 toolchain. Please refer to the [contributing] document 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
a binary directly from sources. From the project folder run:
```sh
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.
## Getting started ## Getting started
`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:
```console
$ arduino-cli help core
Arduino Core operations.
Usage:
arduino-cli core [command]
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 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
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.
```
Follow the [Getting started guide](/getting-started/) to see how to use the most Follow the [Getting started guide](/getting-started/) to see how to use the most
common CLI commands available. common CLI commands available.
## Using the gRPC interface
The [client_example] folder contains a sample program that shows how to use gRPC
interface of the CLI. Available services and messages are detailed in the
[gRPC reference] pages.
[installation]: /installation/
[contributing]: https://github.com/arduino/arduino-cli/blob/master/CONTRIBUTING.md [contributing]: https://github.com/arduino/arduino-cli/blob/master/CONTRIBUTING.md
[client_example]: https://github.com/arduino/arduino-cli/blob/master/client_example
[gRPC reference]: /rpc/commands
\ No newline at end of file
### Install via Homebrew (macOS/Linux)
The Arduino CLI is available as a Homebrew formula since version
`0.5.0`:
```sh
brew update
brew install arduino-cli
```
### Use the install script
The easiest way to get the latest version of the Arduino CLI on any
supported platform is using the `install.sh` script:
```sh
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
```
The script will install `arduino-cli` at `$PWD/bin` but if you want to target a
different directory, for example `~/local/bin`, set the `BINDIR` environment
variable like this:
```sh
curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/local/bin sh
```
### Download the latest packages
You can download the latest version of the pre-built binaries for the supported
platforms from the [release page](https://github.com/arduino/arduino-cli/releases)
or following the links in the following table. Once downloaded, extract the
binary `arduino-cli` into a directory that's is in your `PATH`.
Platform | | |
--------- | ------------------ | ------------------ |
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
> **Deprecation notice**: links in the form
`http://downloads.arduino.cc/arduino-cli/arduino-cli-latest-<platform>.tar.bz2`
won’t be further updated. That URL will provide the version
`0.3.7-alpha.preview`, regardless of further releases.
### Download 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
available for the supported platform, use the following links:
Platform | | |
--------- | -------------------------- | -------------------------- |
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 | | [Mac OSX] |
[Nightly Linux 64 bit]: https://downloads.arduino.cc/arduino-cli/nightly/arduino-cli_nightly-latest_Linux_64bit.tar.gz
[Nightly Windows 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
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-<DATE>-checksums.txt`
Once downloaded, extract the executable `arduino-cli` into a directory
which is in your ``PATH``.
### 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 toolchain. Please refer to the [contributing] document 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
a binary directly from sources. From the project folder run:
```sh
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.
...@@ -58,7 +58,10 @@ markdown_extensions: ...@@ -58,7 +58,10 @@ markdown_extensions:
# Navigation # Navigation
nav: nav:
- Documentation Home: 'index.md' - Documentation Home: 'index.md'
- installation.md
- getting-started.md - getting-started.md
- CONTRIBUTING.md
- FAQ.md
- Command reference: - Command reference:
- commands/arduino-cli.md - commands/arduino-cli.md
- board: commands/arduino-cli_board.md - board: commands/arduino-cli_board.md
...@@ -95,7 +98,7 @@ nav: ...@@ -95,7 +98,7 @@ nav:
- sketch new: commands/arduino-cli_sketch_new.md - sketch new: commands/arduino-cli_sketch_new.md
- upload: commands/arduino-cli_upload.md - upload: commands/arduino-cli_upload.md
- version: commands/arduino-cli_version.md - version: commands/arduino-cli_version.md
- gRPC services: - gRPC reference:
- commands: rpc/commands.md - commands: rpc/commands.md
- monitor: rpc/monitor.md - monitor: rpc/monitor.md
- settings: rpc/settings.md - settings: rpc/settings.md
......
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