From b744f863cb8effa706e0f56208ab54f38fcb890b Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Wed, 20 Nov 2024 09:04:29 +0100 Subject: [PATCH 1/7] Cleared usage of identification properties --- docs/pluggable-discovery-specification.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/pluggable-discovery-specification.md b/docs/pluggable-discovery-specification.md index 4854fa1968e..759dd86eea1 100644 --- a/docs/pluggable-discovery-specification.md +++ b/docs/pluggable-discovery-specification.md @@ -312,7 +312,8 @@ The `properties` associated to a port can be used to identify the board attached "candidate" board attached to that port. Some port `properties` may not be precise enough to uniquely identify a board, in that case more boards may match the -same set of `properties`, that's why we called it "candidate". +same set of `properties`, that's why we called it "candidate". The board identification properties should be used only +if they allows to match the board model beyond any doubt. Let's see an example to clarify things a bit, let's suppose that we have the following `properties` coming from the serial discovery: @@ -392,6 +393,13 @@ myboard.upload_port.1.apples=40 will match on both `pears=20, apples=30` and `pears=30, apples=40` but not `pears=20, apples=40`, in that sense each "set" of identification properties is independent from each other and cannot be mixed for port matching. +#### An important note about `vid` and `pid` + +The board identification properties should be used only if they allows to match the board model beyond any doubt. +Sometimes a board do not expose a unique vid/pid combination, this is the case for example if a USB-2-serial converter +chip is used (like the omnipresent FT232 or CH340): those chips exposes their specific vid/pid that will be the same for +all the other boards using the same chip. In such cases the board identification properties should NOT be used. + #### Identification of board options [Custom board options](platform-specification.md#custom-board-options) can also be identified. From bd3c7848b24b19fe311a76ae4b01dd3c6629a042 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Thu, 21 Nov 2024 11:34:23 +0100 Subject: [PATCH 2/7] Expanded docs on default directories configuration --- docs/configuration.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index ecbc25d65a5..dc6b8be5ab3 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -8,7 +8,8 @@ - `data` - directory used to store Boards/Library Manager index files and Boards Manager platform installations. - `downloads` - directory used to stage downloaded archives during Boards/Library Manager installations. - `user` - the equivalent of the Arduino IDE's ["sketchbook" directory][sketchbook directory]. Library Manager - installations are made to the `libraries` subdirectory of the user directory. + installations are made to the `libraries` subdirectory of the user directory. Users can manually install 3rd party + platforms in the `hardware` subdirecotry of the user directory. - `builtin.libraries` - the libraries in this directory will be available to all platforms without the need for the user to install them, but with the lowest priority over other installed libraries with the same name, it's the equivalent of the Arduino IDE's bundled libraries directory. @@ -45,6 +46,25 @@ - `network` - configuration options related to the network connection. - `proxy` - URL of the proxy server. +### Default directories + +The following are the default directories selected by the Arduino CLI if alternatives are not specified in the +configuration file. + +- The `directories.data` default is OS-dependent: + + - on Linux (and other Unix-based OS) is: `{HOME}/.arduino15` + - on Windows is: `{HOME}/AppData/Local/Arduino15` + - on MacOS is: `{HOME}/Library/Arduino15` + +- The `directories.download` default is `{directories.data}/staging`. If the value of `{directories.data}` is changed in + the configuration the user-specified value will be used. + +- The `directories.user` default is OS-dependent: + - on Linux (and other Unix-based OS) is: `{HOME}/Arduino` + - on Windows is: `{DOCUMENTS}/Arduino` + - on MacOS is: `{HOME}/Documents/Arduino` + ## Configuration methods Arduino CLI may be configured in three ways: From dbd24989979f5ec63f487b425e45a476b785a9d7 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Thu, 21 Nov 2024 11:52:30 +0100 Subject: [PATCH 3/7] Refined platform specification on installation folder for platforms --- docs/platform-specification.md | 61 +++++++++++++++++++++++++--------- 1 file changed, 46 insertions(+), 15 deletions(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 8d01bb098dd..b85286d9029 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -5,31 +5,62 @@ Platforms add support for new boards to the Arduino development software. They a [Boards Manager](package_index_json-specification.md) or manual installation to the _hardware_ folder of Arduino's sketchbook folder (AKA "user directory").
A platform may consist of as little as a single configuration file. -## Hardware Folders structure +## Platform installation directories -The new hardware folders have a hierarchical structure organized in two levels: +If the platforms are installed using the Board Manager the installation directory location will be as follow: -- the first level is the vendor/maintainer -- the second level is the supported architecture +`{directories.data}/packages/{VENDOR_NAME}/hardware/{ARCHITECTURE}/{VERSION}/...` -A vendor/maintainer can have multiple supported architectures. For example, below we have three hardware vendors called -"arduino", "yyyyy" and "xxxxx": +- `{directories.data}` is the data directory as specified in the + [configuration file](configuration.md#default-directories). +- `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform. +- `{ARCHITECTURE}` is the architecture of the CPU used in the platform. +- `{VERSION}` is the platform version. +Alternatively, a platform may be manually installed by the user inside the Sketchbook/user directory as follows: + +`{directories.user}/hardware/{VENDOR_NAME}/{ARCHITECTURE}/...` + +- `{directories.user}` is the user directory as specified in the + [configuration file](configuration.md#default-directories). +- `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform. +- `{ARCHITECTURE}` is the architecture of the CPU used in the platform. + +A vendor/maintainer can have multiple supported architectures. + +For example, below we have four platforms downloaded from three hypothetical hardware vendors called "arduino", "foo" +and "bar", and installed using the Board Manager: + +``` +{directories.data}/packages/arduino/hardware/avr/1.2.3/... +{directories.data}/packages/arduino/hardware/sam/1.4.5/... +{directories.data}/packages/foo/hardware/avr/1.0.2/... +{directories.data}/packages/bar/hardware/avr/1.1.0/... ``` -hardware/arduino/avr/... - Arduino - AVR Boards -hardware/arduino/sam/... - Arduino - SAM (32bit ARM) Boards -hardware/yyyyy/avr/... - Yyy - AVR -hardware/xxxxx/avr/... - Xxx - AVR + +If the same platform were manually installed by the user, he should have unpacked them inside the following directories: + +``` +{directories.user}/hardware/arduino/avr/... +{directories.user}/hardware/arduino/sam/... +{directories.user}/hardware/foo/avr/... +{directories.user}/hardware/bar/avr/... ``` -The vendor "arduino" has two supported architectures (AVR and SAM), while "xxxxx" and "yyyyy" have only AVR. +In this latter case the version is omitted. + +We can also see that the vendor "arduino" has two supported architectures (AVR and SAM), while "foo" and "bar" have only +AVR. + +### Notes about the choosing the architecture name Architecture values are case sensitive (e.g. `AVR` != `avr`). -If possible, follow existing architecture name conventions when creating hardware packages. Use the vendor folder name -to differentiate your package. The architecture folder name is used to determine library compatibility and to permit -referencing resources from another core of the same architecture, so use of a non-standard architecture name can have a -harmful effect. +Platform developers should follow the existing architecture name conventions when creating hardware packages, if you +need to differentiate your package use the vendor/maintainer folder name to do so. + +The architecture name is used to determine the libraries compatibility and to permit referencing resources from another +platform of the same architecture. Use of a non-standard architecture name can have a harmful effect. ## Architecture configurations From 195977bbb1305a266d1e39b197fd95b5043d6e4c Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Thu, 21 Nov 2024 16:46:37 +0100 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Alessio Perugini --- docs/configuration.md | 2 +- docs/platform-specification.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index dc6b8be5ab3..921554d4ceb 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -9,7 +9,7 @@ - `downloads` - directory used to stage downloaded archives during Boards/Library Manager installations. - `user` - the equivalent of the Arduino IDE's ["sketchbook" directory][sketchbook directory]. Library Manager installations are made to the `libraries` subdirectory of the user directory. Users can manually install 3rd party - platforms in the `hardware` subdirecotry of the user directory. + platforms in the `hardware` subdirectory of the user directory. - `builtin.libraries` - the libraries in this directory will be available to all platforms without the need for the user to install them, but with the lowest priority over other installed libraries with the same name, it's the equivalent of the Arduino IDE's bundled libraries directory. diff --git a/docs/platform-specification.md b/docs/platform-specification.md index b85286d9029..dfd85422902 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -52,7 +52,7 @@ In this latter case the version is omitted. We can also see that the vendor "arduino" has two supported architectures (AVR and SAM), while "foo" and "bar" have only AVR. -### Notes about the choosing the architecture name +### Notes about choosing the architecture name Architecture values are case sensitive (e.g. `AVR` != `avr`). From ddaf0a07268aa5372913b4158b43211bf089c8b4 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Mon, 25 Nov 2024 14:54:19 +0100 Subject: [PATCH 5/7] Use real platforms in example --- docs/platform-specification.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index dfd85422902..63f4fea4cc6 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -26,31 +26,34 @@ Alternatively, a platform may be manually installed by the user inside the Sketc - `{VENDOR_NAME}` is the identifier of the vendor/maintainer of the platform. - `{ARCHITECTURE}` is the architecture of the CPU used in the platform. -A vendor/maintainer can have multiple supported architectures. +A vendor/maintainer may have multiple supported architectures. -For example, below we have four platforms downloaded from three hypothetical hardware vendors called "arduino", "foo" -and "bar", and installed using the Board Manager: +Let's see an example, below we have a bunch of platforms downloaded from three hardware vendors `arduino`, `adafruit` +and `esp32`, and installed using the Board Manager: ``` -{directories.data}/packages/arduino/hardware/avr/1.2.3/... -{directories.data}/packages/arduino/hardware/sam/1.4.5/... -{directories.data}/packages/foo/hardware/avr/1.0.2/... -{directories.data}/packages/bar/hardware/avr/1.1.0/... +{directories.data}/packages/arduino/hardware/avr/1.8.6/... +{directories.data}/packages/arduino/hardware/esp32/2.0.18-arduino.5/... +{directories.data}/packages/arduino/hardware/nrf52/1.4.5/... +{directories.data}/packages/adafruit/hardware/nrf52/1.6.1/... +{directories.data}/packages/esp32/hardware/esp32/3.0.7/... ``` -If the same platform were manually installed by the user, he should have unpacked them inside the following directories: +In this example three architectures have been installed from the vendor `arduino` (`avr`, `esp32` and `nrf52`), and one +from `adafruit` and `esp32` (`nrf52` and `esp32` respectively). Note that the vendor `esp32` has the same name of the +architecture `esp32`. + +If the user manually installed the same platforms, they should have unpacked them in the following directories: ``` {directories.user}/hardware/arduino/avr/... -{directories.user}/hardware/arduino/sam/... -{directories.user}/hardware/foo/avr/... -{directories.user}/hardware/bar/avr/... +{directories.user}/hardware/arduino/esp32/... +{directories.user}/hardware/arduino/nrf52/... +{directories.user}/hardware/adafruit/nrf52/... +{directories.user}/hardware/esp32/esp32/... ``` -In this latter case the version is omitted. - -We can also see that the vendor "arduino" has two supported architectures (AVR and SAM), while "foo" and "bar" have only -AVR. +In this latter case the version must be omitted. ### Notes about choosing the architecture name From ab0cbe4217e0128a6e800fbebccf6bfad466395e Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Wed, 27 Nov 2024 09:40:41 +0100 Subject: [PATCH 6/7] Apply code review suggestions --- docs/platform-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 63f4fea4cc6..47fbc2a62bc 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -40,7 +40,7 @@ and `esp32`, and installed using the Board Manager: ``` In this example three architectures have been installed from the vendor `arduino` (`avr`, `esp32` and `nrf52`), and one -from `adafruit` and `esp32` (`nrf52` and `esp32` respectively). Note that the vendor `esp32` has the same name of the +from `adafruit` and `esp32` (`nrf52` and `esp32` respectively). Note that the vendor `esp32` has the same name as the architecture `esp32`. If the user manually installed the same platforms, they should have unpacked them in the following directories: From f250df907993be10b13ddd63a37b70d90a31fab5 Mon Sep 17 00:00:00 2001 From: Cristian Maglie Date: Wed, 27 Nov 2024 09:56:48 +0100 Subject: [PATCH 7/7] Fixed doc formatting, after upgrade of 'prettier' --- docs/CONTRIBUTING.md | 4 ++-- docs/integration-options.md | 22 +++++++++++----------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index bb7a0832ea4..3d801613a01 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -321,8 +321,8 @@ changes in the generated code. ### 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. +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 commit message and PR title with the string **[skip changelog]** diff --git a/docs/integration-options.md b/docs/integration-options.md index 01f32893759..fe476365407 100644 --- a/docs/integration-options.md +++ b/docs/integration-options.md @@ -4,8 +4,8 @@ The Arduino CLI is an open source Command Line Application written in [Golang] t compile, verify and upload sketches to Arduino boards and that’s capable of managing all the software and tools needed in the process. But don’t get fooled by its name: Arduino CLI can do much more than the average console application, as 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 -completely different way from the other. In this article we introduce the three pillars of the Arduino CLI, explaining how -we designed the software so that it can be effectively leveraged under different scenarios. +completely different way from the other. In this article we introduce the three pillars of the Arduino CLI, explaining +how we designed the software so that it can be effectively leveraged under different scenarios. ## The first pillar: command line interface @@ -132,17 +132,18 @@ $ arduino-cli lib search FlashStorage --format json | jq .libraries[0].latest ``` Even if not related to software design, one last feature that’s worth mentioning is the availability of a one-line -[installation script] that can be used to make the latest version of the Arduino CLI available on most systems with an HTTP -client like curl or wget and a shell like bash. +[installation script] that can be used to make the latest version of the Arduino CLI available on most systems with an +HTTP client like curl or wget and a shell like bash. For more information on Arduino CLI's command line interface, see the [command reference]. ## The second pillar: gRPC interface [gRPC] is a high performance [RPC] framework that can efficiently connect client and server applications. The Arduino -CLI can act as a gRPC server (we call it [daemon mode]), exposing a set of procedures that implement the very same set of -features of the command line interface and waiting for clients to connect and use them. To give an idea, the following is -some [Golang] code capable of retrieving the version number of a remote running Arduino CLI server instance: +CLI can act as a gRPC server (we call it [daemon mode]), exposing a set of procedures that implement the very same set +of features of the command line interface and waiting for clients to connect and use them. To give an idea, the +following is some [Golang] code capable of retrieving the version number of a remote running Arduino CLI server +instance: ```go // 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 offered by the Arduino CLI, so that when we provide a fix or a new feature, they are automatically available to both the command line and gRPC interfaces. The source modules implementing this API are implemented through the `commands` package, and it can be imported in other Golang programs to embed a full-fledged Arduino CLI. For example, this is how -some backend services powering [Arduino Cloud] can compile sketches and manage libraries. Just to give you a taste of what -it means to embed the Arduino CLI, here is how to search for a core using the API: +some backend services powering [Arduino Cloud] can compile sketches and manage libraries. Just to give you a taste of +what it means to embed the Arduino CLI, here is how to search for a core using the API: ```go // This file is part of arduino-cli. @@ -296,8 +297,7 @@ use and provide support for. You can start playing with the Arduino CLI right away. The code is open source and [the repo][arduino cli repository] contains [example code showing how to implement a gRPC client][grpc client example]. If you’re curious about how we designed the low level API, have a look at the [commands package] and don’t hesitate to leave feedback on the [issue -tracker] -if you’ve got a use case that doesn’t fit one of the three pillars. +tracker] if you’ve got a use case that doesn’t fit one of the three pillars. [golang]: https://go.dev/ [arduino ide 2.x]: https://github.com/arduino/arduino-ide