Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit a9597d6

Browse filesBrowse files
cmagliealessio-perugini
cmaglie
and
alessio-perugini
authored
Updated and refined documentation (#2760)
* Cleared usage of identification properties * Expanded docs on default directories configuration * Refined platform specification on installation folder for platforms * Apply suggestions from code review Co-authored-by: Alessio Perugini <alessio@perugini.xyz> * Use real platforms in example * Apply code review suggestions * Fixed doc formatting, after upgrade of 'prettier' --------- Co-authored-by: Alessio Perugini <alessio@perugini.xyz>
1 parent 6f34a68 commit a9597d6
Copy full SHA for a9597d6

5 files changed

+92
-30
lines changed

‎docs/CONTRIBUTING.md

Copy file name to clipboardExpand all lines: docs/CONTRIBUTING.md
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -321,8 +321,8 @@ changes in the generated code.
321321
### Additional settings
322322

323323
If you need to push a commit that's only shipping documentation changes or example files, thus a complete no-op for the
324-
test suite, please start the commit message with the string **[skip ci]** to skip the build and give that slot to someone
325-
else who does need it.
324+
test suite, please start the commit message with the string **[skip ci]** to skip the build and give that slot to
325+
someone else who does need it.
326326

327327
If your PR doesn't need to be included in the changelog, please start the commit message and PR title with the string
328328
**[skip changelog]**

‎docs/configuration.md

Copy file name to clipboardExpand all lines: docs/configuration.md
+21-1Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@
88
- `data` - directory used to store Boards/Library Manager index files and Boards Manager platform installations.
99
- `downloads` - directory used to stage downloaded archives during Boards/Library Manager installations.
1010
- `user` - the equivalent of the Arduino IDE's ["sketchbook" directory][sketchbook directory]. Library Manager
11-
installations are made to the `libraries` subdirectory of the user directory.
11+
installations are made to the `libraries` subdirectory of the user directory. Users can manually install 3rd party
12+
platforms in the `hardware` subdirectory of the user directory.
1213
- `builtin.libraries` - the libraries in this directory will be available to all platforms without the need for the
1314
user to install them, but with the lowest priority over other installed libraries with the same name, it's the
1415
equivalent of the Arduino IDE's bundled libraries directory.
@@ -45,6 +46,25 @@
4546
- `network` - configuration options related to the network connection.
4647
- `proxy` - URL of the proxy server.
4748

49+
### Default directories
50+
51+
The following are the default directories selected by the Arduino CLI if alternatives are not specified in the
52+
configuration file.
53+
54+
- The `directories.data` default is OS-dependent:
55+
56+
- on Linux (and other Unix-based OS) is: `{HOME}/.arduino15`
57+
- on Windows is: `{HOME}/AppData/Local/Arduino15`
58+
- on MacOS is: `{HOME}/Library/Arduino15`
59+
60+
- The `directories.download` default is `{directories.data}/staging`. If the value of `{directories.data}` is changed in
61+
the configuration the user-specified value will be used.
62+
63+
- The `directories.user` default is OS-dependent:
64+
- on Linux (and other Unix-based OS) is: `{HOME}/Arduino`
65+
- on Windows is: `{DOCUMENTS}/Arduino`
66+
- on MacOS is: `{HOME}/Documents/Arduino`
67+
4868
## Configuration methods
4969

5070
Arduino CLI may be configured in three ways:

‎docs/integration-options.md

Copy file name to clipboardExpand all lines: docs/integration-options.md
+11-11Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ The Arduino CLI is an open source Command Line Application written in [Golang] t
44
compile, verify and upload sketches to Arduino boards and that’s capable of managing all the software and tools needed
55
in the process. But don’t get fooled by its name: Arduino CLI can do much more than the average console application, as
66
shown by [Arduino IDE 2.x][arduino ide 2.x] and [Arduino Cloud], which rely on it for similar purposes but each one in a
7-
completely different way from the other. In this article we introduce the three pillars of the Arduino CLI, explaining how
8-
we designed the software so that it can be effectively leveraged under different scenarios.
7+
completely different way from the other. In this article we introduce the three pillars of the Arduino CLI, explaining
8+
how we designed the software so that it can be effectively leveraged under different scenarios.
99

1010
## The first pillar: command line interface
1111

@@ -132,17 +132,18 @@ $ arduino-cli lib search FlashStorage --format json | jq .libraries[0].latest
132132
```
133133

134134
Even if not related to software design, one last feature that’s worth mentioning is the availability of a one-line
135-
[installation script] that can be used to make the latest version of the Arduino CLI available on most systems with an HTTP
136-
client like curl or wget and a shell like bash.
135+
[installation script] that can be used to make the latest version of the Arduino CLI available on most systems with an
136+
HTTP client like curl or wget and a shell like bash.
137137

138138
For more information on Arduino CLI's command line interface, see the [command reference].
139139

140140
## The second pillar: gRPC interface
141141

142142
[gRPC] is a high performance [RPC] framework that can efficiently connect client and server applications. The Arduino
143-
CLI can act as a gRPC server (we call it [daemon mode]), exposing a set of procedures that implement the very same set of
144-
features of the command line interface and waiting for clients to connect and use them. To give an idea, the following is
145-
some [Golang] code capable of retrieving the version number of a remote running Arduino CLI server instance:
143+
CLI can act as a gRPC server (we call it [daemon mode]), exposing a set of procedures that implement the very same set
144+
of features of the command line interface and waiting for clients to connect and use them. To give an idea, the
145+
following is some [Golang] code capable of retrieving the version number of a remote running Arduino CLI server
146+
instance:
146147

147148
```go
148149
// This file is part of arduino-cli.
@@ -210,8 +211,8 @@ a common Golang API, based on the gRPC protobuf definitions: a set of functions
210211
offered by the Arduino CLI, so that when we provide a fix or a new feature, they are automatically available to both the
211212
command line and gRPC interfaces. The source modules implementing this API are implemented through the `commands`
212213
package, and it can be imported in other Golang programs to embed a full-fledged Arduino CLI. For example, this is how
213-
some backend services powering [Arduino Cloud] can compile sketches and manage libraries. Just to give you a taste of what
214-
it means to embed the Arduino CLI, here is how to search for a core using the API:
214+
some backend services powering [Arduino Cloud] can compile sketches and manage libraries. Just to give you a taste of
215+
what it means to embed the Arduino CLI, here is how to search for a core using the API:
215216

216217
```go
217218
// This file is part of arduino-cli.
@@ -296,8 +297,7 @@ use and provide support for.
296297
You can start playing with the Arduino CLI right away. The code is open source and [the repo][arduino cli repository]
297298
contains [example code showing how to implement a gRPC client][grpc client example]. If you’re curious about how we
298299
designed the low level API, have a look at the [commands package] and don’t hesitate to leave feedback on the [issue
299-
tracker]
300-
if you’ve got a use case that doesn’t fit one of the three pillars.
300+
tracker] if you’ve got a use case that doesn’t fit one of the three pillars.
301301

302302
[golang]: https://go.dev/
303303
[arduino ide 2.x]: https://github.com/arduino/arduino-ide

‎docs/platform-specification.md

Copy file name to clipboardExpand all lines: docs/platform-specification.md
+49-15Lines changed: 49 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,31 +5,65 @@ Platforms add support for new boards to the Arduino development software. They a
55
[Boards Manager](package_index_json-specification.md) or manual installation to the _hardware_ folder of Arduino's
66
sketchbook folder (AKA "user directory").<br> A platform may consist of as little as a single configuration file.
77

8-
## Hardware Folders structure
8+
## Platform installation directories
99

10-
The new hardware folders have a hierarchical structure organized in two levels:
10+
If the platforms are installed using the Board Manager the installation directory location will be as follow:
1111

12-
- the first level is the vendor/maintainer
13-
- the second level is the supported architecture
12+
`{directories.data}/packages/{VENDOR_NAME}/hardware/{ARCHITECTURE}/{VERSION}/...`
1413

15-
A vendor/maintainer can have multiple supported architectures. For example, below we have three hardware vendors called
16-
"arduino", "yyyyy" and "xxxxx":
14+
- `{directories.data}` is the data directory as specified in the
15+
[configuration file](configuration.md#default-directories).
16+
- `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform.
17+
- `{ARCHITECTURE}` is the architecture of the CPU used in the platform.
18+
- `{VERSION}` is the platform version.
1719

20+
Alternatively, a platform may be manually installed by the user inside the Sketchbook/user directory as follows:
21+
22+
`{directories.user}/hardware/{VENDOR_NAME}/{ARCHITECTURE}/...`
23+
24+
- `{directories.user}` is the user directory as specified in the
25+
[configuration file](configuration.md#default-directories).
26+
- `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform.
27+
- `{ARCHITECTURE}` is the architecture of the CPU used in the platform.
28+
29+
A vendor/maintainer may have multiple supported architectures.
30+
31+
Let's see an example, below we have a bunch of platforms downloaded from three hardware vendors `arduino`, `adafruit`
32+
and `esp32`, and installed using the Board Manager:
33+
34+
```
35+
{directories.data}/packages/arduino/hardware/avr/1.8.6/...
36+
{directories.data}/packages/arduino/hardware/esp32/2.0.18-arduino.5/...
37+
{directories.data}/packages/arduino/hardware/nrf52/1.4.5/...
38+
{directories.data}/packages/adafruit/hardware/nrf52/1.6.1/...
39+
{directories.data}/packages/esp32/hardware/esp32/3.0.7/...
1840
```
19-
hardware/arduino/avr/... - Arduino - AVR Boards
20-
hardware/arduino/sam/... - Arduino - SAM (32bit ARM) Boards
21-
hardware/yyyyy/avr/... - Yyy - AVR
22-
hardware/xxxxx/avr/... - Xxx - AVR
41+
42+
In this example three architectures have been installed from the vendor `arduino` (`avr`, `esp32` and `nrf52`), and one
43+
from `adafruit` and `esp32` (`nrf52` and `esp32` respectively). Note that the vendor `esp32` has the same name as the
44+
architecture `esp32`.
45+
46+
If the user manually installed the same platforms, they should have unpacked them in the following directories:
47+
2348
```
49+
{directories.user}/hardware/arduino/avr/...
50+
{directories.user}/hardware/arduino/esp32/...
51+
{directories.user}/hardware/arduino/nrf52/...
52+
{directories.user}/hardware/adafruit/nrf52/...
53+
{directories.user}/hardware/esp32/esp32/...
54+
```
55+
56+
In this latter case the version must be omitted.
2457

25-
The vendor "arduino" has two supported architectures (AVR and SAM), while "xxxxx" and "yyyyy" have only AVR.
58+
### Notes about choosing the architecture name
2659

2760
Architecture values are case sensitive (e.g. `AVR` != `avr`).
2861

29-
If possible, follow existing architecture name conventions when creating hardware packages. Use the vendor folder name
30-
to differentiate your package. The architecture folder name is used to determine library compatibility and to permit
31-
referencing resources from another core of the same architecture, so use of a non-standard architecture name can have a
32-
harmful effect.
62+
Platform developers should follow the existing architecture name conventions when creating hardware packages, if you
63+
need to differentiate your package use the vendor/maintainer folder name to do so.
64+
65+
The architecture name is used to determine the libraries compatibility and to permit referencing resources from another
66+
platform of the same architecture. Use of a non-standard architecture name can have a harmful effect.
3367

3468
## Architecture configurations
3569

‎docs/pluggable-discovery-specification.md

Copy file name to clipboardExpand all lines: docs/pluggable-discovery-specification.md
+9-1Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -312,7 +312,8 @@ The `properties` associated to a port can be used to identify the board attached
312312
"candidate" board attached to that port.
313313

314314
Some port `properties` may not be precise enough to uniquely identify a board, in that case more boards may match the
315-
same set of `properties`, that's why we called it "candidate".
315+
same set of `properties`, that's why we called it "candidate". The board identification properties should be used only
316+
if they allows to match the board model beyond any doubt.
316317

317318
Let's see an example to clarify things a bit, let's suppose that we have the following `properties` coming from the
318319
serial discovery:
@@ -392,6 +393,13 @@ myboard.upload_port.1.apples=40
392393
will match on both `pears=20, apples=30` and `pears=30, apples=40` but not `pears=20, apples=40`, in that sense each
393394
"set" of identification properties is independent from each other and cannot be mixed for port matching.
394395

396+
#### An important note about `vid` and `pid`
397+
398+
The board identification properties should be used only if they allows to match the board model beyond any doubt.
399+
Sometimes a board do not expose a unique vid/pid combination, this is the case for example if a USB-2-serial converter
400+
chip is used (like the omnipresent FT232 or CH340): those chips exposes their specific vid/pid that will be the same for
401+
all the other boards using the same chip. In such cases the board identification properties should NOT be used.
402+
395403
#### Identification of board options
396404

397405
[Custom board options](platform-specification.md#custom-board-options) can also be identified.

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.