Updated and refined documentation (#2760) · arduino/arduino-cli@a9597d6 (original) (raw)
`@@ -5,31 +5,65 @@ Platforms add support for new boards to the Arduino development software. They a
`
5
5
`Boards Manager or manual installation to the hardware folder of Arduino's
`
6
6
`sketchbook folder (AKA "user directory").
A platform may consist of as little as a single configuration file.
`
7
7
``
8
``
`-
Hardware Folders structure
`
``
8
`+
Platform installation directories
`
9
9
``
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:
`
11
11
``
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}/...
``
14
13
``
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
`+
`
``
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.
``
17
19
``
``
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
`+
`
``
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/...
`
18
40
```` ```
`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`
`+`
`23`
`48`
```` ```
``
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.
`
24
57
``
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
`
26
59
``
27
60
`` Architecture values are case sensitive (e.g. AVR != avr).
``
28
61
``
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.
`
33
67
``
34
68
`## Architecture configurations
`
35
69
``