Skip to content

GitLab

A
arduino-cli
Unverified Commit 97c4f004 authored by per1234's avatar per1234 Committed by GitHub
Browse files
Options

[skip changelog] Migrate relevant documentation pages from arduino/Arduino wiki (#616) 

* Migrate relevant documentation from arduino/Arduino wiki

* Trim trailing whitespace

* Add newline to end of file

* Increase heading levels so that the minimum level is h2

This is required for table of contents generation.

* Use supported line break markup

The backslash at end of line to cause line break is not supported by the documentation build system.

* Update links to migrated pages

* Fix list markup

The documentation build system requires a blank line before the start of a list
parent 0866d99f
Hide whitespace changes
Inline Side-by-side
Showing with 1206 additions and 3 deletions
docs/FAQ.md
View file @ 97c4f004
......@@ -11,8 +11,8 @@ When you run `arduino-cli board list`, your board doesn't show up. Possible caus
## 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].
Arduino Hardware specification. You can find more information in the
[Arduino platform specification][0].
[0]: https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5-3rd-party-Hardware-specification
[0]: platform-specification.md
docs/library-specification.md 0 → 100644
View file @ 97c4f004
This is the specification for the 3rd party library format to be used with Arduino IDE 1.5.x onwards.
* rev.1 has been implemented starting with IDE version 1.5.3 (now superseded by rev.2)
* rev.2 will be implemented starting from version 1.5.6
* rev.2.1 will be implemented starting from version 1.6.10
* rev.2.2 will be implemented starting from version 1.8.10
This new library format is intended to be used in tandem with the Arduino IDE"s **Library Manager**, available since version 1.6.2. The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy to use graphic interface. It doesn't yet take care of dependencies between libraries.
More information about how Library Manager works are available [here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).
Arduino IDE 1.5.x+ supports multiple microcontroller architectures (e.g. AVR, SAM, etc), meaning that libraries may need to work on multiple architectures. The new 1.5 library format doesn’t contain special support for cross-architecture libraries, but it does provide a preprocessor based mechanism for libraries to target sections of code to specific architectures.
## See also
The Arduino library style guide is here : http://arduino.cc/en/Reference/APIStyleGuide
The style guide for examples is here : http://arduino.cc/en/Reference/StyleGuide
## 1.5 library format (rev. 2.2)
### Library metadata
The most significant addition to the format is the ability to add information about the library itself through a properties file called **library.properties**.
This file allows the *Library Manager* to search and install a library and its dependencies in an easy and automated way. It must be located in the root of the library folder.
#### library.properties file format
The library.properties file is a key=value properties list. Every field in this file is UTF-8 encoded. Unless noted otherwise below, **all fields are required**. The available fields are:
* **name** - the name of the library. Library names must contain only basic letters (`A`-`Z` or `a`-`z`) and numbers (`0`-`9`), spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). It cannot start or end with a space, and also it cannot start with a number. Note that libraries with a `name` value starting with `Arduino` will no longer be allowed [addition to the Library Manager index](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) as these names are now reserved for official Arduino libraries.
* **version** - version of the library. Version should be [semver](http://semver.org/) compliant. 1.2.0 is correct; 1.2 is accepted; r5, 003, 1.1c are invalid
* **author** - name/nickname of the authors and their email addresses (not mandatory) separated by comma ","
* **maintainer** - name and email of the maintainer
* **sentence** - a sentence explaining the purpose of the library
* **paragraph** - a longer description of the library. The value of **sentence** always will be prepended, so you should start by writing the second sentence here
* **category** - (defaults to `Uncategorized`) if present, one of these:
* Display
* Communication
* Signal Input/Output
* Sensors
* Device Control
* Timing
* Data Storage
* Data Processing
* Other
* **url** - the URL of the library project, for a person to visit. For example, the library's GitHub page. This is used for the "More info" links in Library Manager
* **architectures** - (defaults to `*`) a comma separated list of architectures supported by the library. If the library doesn’t contain architecture specific code use `*` to match all architectures. This field is used as one factor in determining priority when multiple libraries match an `#include` directive and to provide a warning message when the library is compiled for a board of an architecture that doesn't match any on the list.
* **depends** - **(available from Arduino IDE 1.8.10)** (optional) a comma-separated list of dependencies (libraries that are needed to build the current library). Library Manager will offer to install the dependencies during installation of the library. Since spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the name without ambiguity for example:
`depends=Very long library name, Another library with long-name`
* **dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to `true`, the library will be compiled using a .a (archive) file. First, all source files are compiled into .o files as normal. Then instead of including all .o files in the linker command directly, all .o files are saved into a .a file, which is then included in the linker command. [1.5 format library folder structure](#layout-of-folders-and-files) is required.
* **includes** - **(available from Arduino IDE 1.6.10)** (optional) a comma separated list of files to be added to the sketch as `#include <...>` lines. This property is used with the "Include library" command in the IDE. If the `includes` property is missing all the headers files (.h) on the root source folder are included.
* **precompiled** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) set to `true` to allow the use of .a (archive) and .so (shared object) files. The .a/.so file must be located at `src/{build.mcu}` where `{build.mcu}` is the architecture name of the target the file was compiled for. Ex: `cortex-m3` for the Arduino DUE. The static library should be linked as an ldflag.
* **ldflags** - **(available from Arduino IDE 1.8.6/arduino-builder 1.4.0)** (optional) the linker flags to be added. Ex: `ldflags=-lm`
Example:
name=WebServer
version=1.0.0
author=Cristian Maglie <c.maglie@example.com>, Pippo Pluto <pippo@example.com>
maintainer=Cristian Maglie <c.maglie@example.com>
sentence=A library that makes coding a Webserver a breeze.
paragraph=Supports HTTP1.1 and you can do GET and POST.
category=Communication
url=http://example.com/
architectures=avr
includes=WebServer.h
depends=ArduinoHttpClient
### Layout of folders and files
Each folder has a specific purpose (sources, examples, documentation, etc). Folders not covered in this specification may be added as needed to future revisions.
#### Library Root folder
The library root folder name must start with a basic letter (`A`-`Z` or `a`-`z`) or number (`0`-`9`), followed by basic letters, numbers, spaces (` `), underscores (`_`), dots (`.`) and dashes (`-`). The maximum length is 63 characters.
#### Source code
For 1.5.x+-only libraries, the source code resides in the **src** folder. For example:
Servo/src/Servo.h
Servo/src/Servo.cpp
The source code found in **src** folder and *all its subfolders* is compiled and linked in the user’s sketch. Only the *src* folder is added to the include search path (both when compiling the sketch and the library). When the user imports a library into their sketch (from the "Tools > Import Library" menu), an #include statement will be added for all header (.h) files in the src/ directory (but not its subfolders). As a result, these header files form something of a de facto interface to your library; in general, the only header files in the root src/ folder should be those that you want to expose to the user's sketch and plan to maintain compatibility with in future versions of the library. Place internal header files in a subfolder of the src/ folder.
For backward compatibility with Arduino 1.0.x, the library author may opt to place source code into the root folder, instead of the folder called **src**. In this case the 1.0 library format is applied and the source code is searched from the **library root folder** and the **utility** folder, for example:
Servo/Servo.h
Servo/Servo.cpp
Servo/utility/ServoTimers.h
Servo/utility/ServoTimers.cpp
This will allow existing 1.0.x libraries to compile under 1.5.x+ as well and vice-versa. If a library only needs to run on 1.5.x+, we recommend placing all source code in the src/ folder. If a library requires recursive compilation of nested source folders, its code must be in the src/ folder (since 1.0.x doesn’t support recursive compilation, backwards compatibility wouldn’t be possible anyway).
#### Library Examples
Library examples must be placed in the **examples** folder. Note that the **examples** folder must be written exactly like that (with lower case letters).
Servo/examples/...
Sketches contained inside the examples folder will be shown in the Examples menu of the IDE.
#### Extra documentation
An **extras** folder can be used by the developer to put documentation or other items to be bundled with the library. Remember that files placed inside this folder will increase the size of the library, so putting a 20MB PDF in a library that weights a few kilobytes may not be such a good idea.
The content of the *extras* folder is totally ignored by the IDE; you are free to put anything inside such as supporting documentation, etc.
### Keywords
A list of keywords for the library may be specified in a file named keywords.txt located in the root of the library folder. When a keyword of any installed library is used in a sketch the Arduino IDE colors it.
Servo/keywords.txt
An example keywords file:
```
# Syntax Coloring Map For ExampleLibrary
# Datatypes (KEYWORD1)
Test KEYWORD1
# Methods and Functions (KEYWORD2)
doSomething KEYWORD2
# Instances (KEYWORD2)
# Constants (LITERAL1)
```
This keywords file would cause the Arduino IDE to highlight `Test` as a DataType, and `doSomething` as a method / function.
#### keywords.txt format
keywords.txt is formatted in four fields which are separated by a single true tab (not spaces):
```
KEYWORD KEYWORD_TOKENTYPE REFERENCE_LINK RSYNTAXTEXTAREA_TOKENTYPE
```
It is permitted to leave a field empty.
##### `KEYWORD_TOKENTYPE`
KEYWORD_TOKENTYPE | Use for | Theme property
---|---|---
`KEYWORD1` | datatypes | `editor.data_type.style`
`KEYWORD2` | functions | `editor.function.style`
`KEYWORD3` | structures | `editor.function.style`
`LITERAL1` | constants | `editor.reserved_word_2.style`
`LITERAL2` | ? | `editor.function.style`
##### `REFERENCE_LINK`
This field specifies the [Arduino Language Reference](https://www.arduino.cc/reference/en) page to open via **Right Click > Find in Reference** or **Help > Find in Reference** when the cursor is on that keyword. Generally it does not make sense to define the `REFERENCE_LINK` field for 3rd party library keywords since they are not likely to be in the Arduino Language Reference.
##### `RSYNTAXTEXTAREA_TOKENTYPE`
In Arduino IDE 1.6.5 and newer this field overrides `KEYWORD_TOKENTYPE`. In previous IDE versions the `RSYNTAXTEXTAREA_TOKENTYPE` field is ignored and `KEYWORD_TOKENTYPE` is used instead.
RSYNTAXTEXTAREA_TOKENTYPE | Theme property | KEYWORD_TOKENTYPE equivalent
---|---|---
`RESERVED_WORD` | `editor.reserved_word.style` | `KEYWORD3`
`RESERVED_WORD_2` | `editor.reserved_word_2.style` | `LITERAL1`
`DATA_TYPE` | `editor.data_type.style` | `KEYWORD1`
`PREPROCESSOR` | `editor.preprocessor.style` | `KEYWORD3`
`LITERAL_BOOLEAN` | `editor.literal_boolean.style` | `LITERAL1`
### Development flag file
Normally the Arduino IDE treats the contents of the library folder as read-only. This is to prevent users from accidentally modifying example sketches. During the library development process you may want to edit example sketches in place using the Arduino IDE. With Arduino IDE 1.6.6 and newer, the read-only behavior can be disabled by adding a file named .development to the root of the library folder. A [library.properties](#libraryproperties-file-format) file must also be present. The [Library Manager indexer](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ) will not pick up releases that contain a .development file so be sure not to push this file to your remote repository.
### A complete example
A hypothetical library named "Servo" that adheres to the specification follows:
Servo/
Servo/library.properties
Servo/keywords.txt
Servo/src/
Servo/src/Servo.h
Servo/src/Servo.cpp
Servo/src/ServoTimers.h
Servo/examples/
Servo/examples/Sweep/Sweep.ino
Servo/examples/Pot/Pot.ino
Servo/extras/
Servo/extras/Servo_Connectors.pdf
## Working with multiple architectures
In 1.5.x+, libraries placed in the user’s sketchbook folder (in the libraries/ subfolder) will be made available for all boards, which may include multiple different processor architectures. To provide architecture-specific code or optimizations, library authors can use the ARDUINO_ARCH_XXX preprocessor macro (#define), where XXX is the name of the architecture (as determined by the name of the folder containing it), e.g. ARDUINO_ARCH_AVR will be defined when compiling for AVR-based boards. For example,
#if defined(ARDUINO_ARCH_AVR)
// AVR-specific code
#elif defined(ARDUINO_ARCH_SAM)
// SAM-specific code
#else
// generic, non-platform specific code
#endif
Alternatively, if a library only works on certain architectures, you can provide an explicit error message (instead of allowing the compilation to fail in a difficult to understand way):
#if defined(ARDUINO_ARCH_AVR)
// AVR-specific code
#elif defined(ARDUINO_ARCH_SAM)
// SAM-specific code
#else
#error “This library only supports boards with an AVR or SAM processor.”
#endif
## Old library format (pre-1.5)
In order to support old libraries (from Arduino 1.0.x), Arduino 1.5.x+ will also compile libraries missing a library.properties metadata file. As a result, these libraries should behave as they did in Arduino 1.0.x, although they will be available for all boards, including non-AVR ones (which wouldn’t have been present in 1.0.x).
docs/package_index_json-specification.md 0 → 100644
View file @ 97c4f004
Starting from version 1.6.4 the Boards Manager of the Arduino IDE can be used to automatically install support for **3rd party hardware** by simply entering an URL in the **File > Preferences** dialog. The URL must be provided by the 3rd party hardware producer and should point to a JSON file that contains an index of the boards available to install and the location of the installation archives. Boards Manager also allows easy updates of installed Boards when new versions are released.
## Naming of the JSON index file
The IDE may use many different index files coming from different vendors, so each vendor should name his own index file in a way that won't conflict with others. The file must be named as follows:
`package_YOURNAME_PACKAGENAME_index.json`
The prefix `package_` and the postfix `_index.json` are **mandatory** (otherwise the index file is not recognised by the IDE) while the choice of `YOURNAME_PACKAGENAME` is left to the packager.
We suggest using a domain name owned by the packager. For example:
`package_arduino.cc_index.json`
or
`package_example.com_avr_boards_index.json`
The index URL is periodically checked for updates so expect a constant flow of downloads (proportional to the number of active users).
## JSON Index file contents
The root of the JSON index is an array of `packages`:
```json
{
"packages": [
PACKAGE_XXXX
]
}
```
3rd party vendors should use a single `PACKAGE_XXXX` that is a dictionary map with the vendor's metadata, a list of `PLATFORMS` and a list of `TOOLS`. For example:
```json
{
"name": "arduino",
"maintainer": "Arduino LLC",
"websiteURL": "http://www.arduino.cc/",
"email": "packages@arduino.cc",
"platforms": [
PLATFORM_AVR,
PLATFORM_ARM,
PLATFORM_XXXXX,
PLATFORM_YYYYY,
],
"tools": [
TOOLS_COMPILER_AVR,
TOOLS_UPLOADER_AVR,
TOOLS_COMPILER_ARM,
TOOLS_XXXXXXX,
TOOLS_YYYYYYY,
],
}
```
The metadata fields are:
* `name`: the folder used for the installed cores. The [vendor folder](platform-specification.md#hardware-folders-structure) name of the installed package is determined by this field
* `maintainer`: the extended name of the vendor that is displayed on the Boards Manager GUI
* `websiteURL`: the URL to the vendor's website, appears on the Boards Manager as a "More info" link
* `email`: the email of the vendor/maintainer
Now, before looking at `PLATFORMS`, let's explore first how `TOOLS` are made.
### Tools definitions
Each tool describes a binary distribution of a command line tool. A tool can be:
* a compiler toolchain
* an uploader
* a file preprocessor
* a debugger
* a program that performs a firmware upgrade
basically anything that can run on the user's host PC and do something useful.
For example, Arduino uses two command line tools for the AVR boards: avr-gcc (the compiler) and avrdude (the uploader).
Tools are mapped as JSON in this way:
```json
{
"name": "avr-gcc",
"version": "4.8.1-arduino5",
"systems": [
{
"host": "i386-apple-darwin11",
"url": "http://downloads.arduino.cc/tools/avr-gcc-4.8.1-arduino5-i386-apple-darwin11.tar.bz2",
"archiveFileName": "avr-gcc-4.8.1-arduino5-i386-apple-darwin11.tar.bz2",
"size": "24437400",
"checksum": "SHA-256:111b3ef00d737d069eb237a8933406cbb928e4698689e24663cffef07688a901"
},
{
"host": "x86_64-linux-gnu",
"url": "http://downloads.arduino.cc/tools/avr-gcc-4.8.1-arduino5-x86_64-pc-linux-gnu.tar.bz2",
"archiveFileName": "avr-gcc-4.8.1-arduino5-x86_64-pc-linux-gnu.tar.bz2",
"size": "27093036",
"checksum": "SHA-256:9054fcc174397a419ba56c4ce1bfcbcad275a6a080cc144905acc9b0351ee9cc"
},
{
"host": "i686-linux-gnu",
"url": "http://downloads.arduino.cc/tools/avr-gcc-4.8.1-arduino5-i686-pc-linux-gnu.tar.bz2",
"archiveFileName": "avr-gcc-4.8.1-arduino5-i686-pc-linux-gnu.tar.bz2",
"size": "25882375",
"checksum": "SHA-256:7648b7f549b37191da0b0be53bae791b652f82ac3cb4e7877f85075aaf32141f"
},
{
"host": "i686-mingw32",
"url": "http://downloads.arduino.cc/tools/avr-gcc-4.8.1-arduino5-i686-mingw32.zip",
"archiveFileName": "avr-gcc-4.8.1-arduino5-i686-mingw32.zip",
"size": "46044779",
"checksum": "SHA-256:d4303226a7b41d3c445d901b5aa5903458def3fc7b7ff4ffef37cabeb37d424d"
}
]
},
```
The field `name` and `version` are respectively the name and version of the tool.
Each tool is uniquely identified by the triple (`vendor`, `name`, `version`) and there can be many different versions of the same tool available at the same time, for example:
* (`arduino`, `avr-gcc`, `4.8.1-arduino2`)
* (`arduino`, `avr-gcc`, `4.8.1-arduino3`)
* (`arduino`, `avr-gcc`, `4.8.1-arduino5`)
* (`arduino`, `avrdude`, `5.11`)
* (`arduino`, `avrdude`, `6.0`)
* (`arduino`, `avrdude`, `6.1`)
* .....
Each tool version may come in different build flavours for different OS. Each flavour is listed under the `systems` array. In the example above `avr-gcc` comes with builds for:
* Linux 64-bit (`x86_64-linux-gnu`),
* Linux 32-bit (`i686-linux-gnu`),
* Windows (`i686-mingw32`),
* Mac (`i386-apple-darwin11`)
The IDE will take care to install the right flavour based on the `host` value, or fail if a needed flavour is missing.<br>
Note that the IDE does not use this information to select the toolchain during verify. If you want the IDE to use this specific version you should use the notation {runtime.tools.TOOLNAME-VERSION.path} in the platform.txt.
The other fields are:
* `url`: the download URL of the tool's archive
* `archiveFileName`: the name of the file saved to disk after the download (some web servers don't provide the filename through the HTTP request)
* `size`: the size of the archive in bytes
* `checksum`: the checksum of the archive, used to check if the file has been corrupted. The format is `ALGORITHM:CHECKSUM`, currently `MD5`, `SHA-1`,`SHA-256` algorithm are supported, we recommend `SHA-256`. On *nix or MacOSX you may be able to use the command `shasum -a 256 filename` to generate SHA-256 checksums. There are many free options for Windows including md5deep, there are also online utilities for generating checksums.
##### How a tool's path is determined in platform.txt
When the IDE needs a tool it downloads the corresponding archive file and unpacks the content into
a private folder that can be referenced from `platform.txt` using one of the following properties:
* `{runtime.tools.TOOLNAME-VERSION.path}`
* `{runtime.tools.TOOLNAME.path}`
For example to obtain the avr-gcc 4.8.1 folder we can use `{runtime.tools.avr-gcc-4.8.1-arduino5.path}` or `{runtime.tools.avr-gcc.path}`.
### Platforms definitions
Finally, let's see how `PLATFORMS` are made.
```json
{
"name": "Arduino AVR Boards",
"architecture": "avr",
"version": "1.6.6",
"category": "Arduino",
"help": {
"online": "http://www.arduino.cc/en/Reference/HomePage"
},
"url": "http://downloads.arduino.cc/cores/avr-1.6.6.tar.bz2",
"archiveFileName": "avr-1.6.6.tar.bz2",
"checksum": "SHA-256:08ad5db4978ebea22344edc5d77dce0923d8a644da7a14dc8072e883c76058d8",
"size": "4876916",
"boards": [
{"name": "Arduino Yún"},
{"name": "Arduino Uno"},
{"name": "Arduino Diecimila"},
{"name": "Arduino Nano"},
{"name": "Arduino Mega"},
{"name": "Arduino MegaADK"},
{"name": "Arduino Leonardo"},
],
"toolsDependencies": [
{ "packager": "arduino", "name": "avr-gcc", "version": "4.8.1-arduino5" },
{ "packager": "arduino", "name": "avrdude", "version": "6.0.1-arduino5" }
]
},
```
Each PLATFORM describes a core for a specific architecture. The fields needed are:
* `name`: the extended name of the platform that is displayed on the Boards Manager GUI
* `architecture`: is the architecture of the plaftorm (avr, sam, etc...). It must match the architecture of the core as explained in the [Arduino platform specification](platform-specification.md#hardware-folders-structure)
* `version`: the version of the platform.
* `category`: this field is reserved, a 3rd party core must set it to `Contributed`
* `help`/`online`: is a URL that is displayed on the Boards Manager as an "Online Help" link
* `url`, `archiveFileName`, `size` and `checksum`: metadata of the core archive file. The meaning is the same as for the TOOLS
* `boards`: the list of boards supported (note: just the names to display on the GUI! the real boards definitions are inside `boards.txt` inside the core archive file)
* `toolsDependencies`: the tools needed by this core. Each tool is referenced by the triple (`packager`, `name`, `version`) as previously said. Note that you can reference tools available in other packages as well.
The `version` field is validated by both Arduino IDE and [JSemVer](https://github.com/zafarkhaja/jsemver). Here are the rules Arduino IDE follows for parsing versions ([source](https://github.com/arduino/Arduino/blob/master/arduino-core/src/cc/arduino/contributions/VersionHelper.java)):
* Split the version at the - character and continue with the first part.
* If there are no dots (`.`), parse `version` as an integer and form a Version from that integer using `Version.forIntegers`
* If there is one dot, split `version` into two, parse each part as an integer, and form a Version from those integers using `Version.forIntegers`
* Otherwise, simply parse `version` into a Version using `Version.valueOf`
Note: if you miss a bracket in the JSON index, then add the URL to your Preferences, and open Boards Manager it can cause the Arduino IDE to no longer load until you have deleted the file from your arduino15 folder.
### Example JSON index file
```json
{
"packages": [
{
"name": "myboard",
"maintainer": "Jane Developer",
"websiteURL": "https://github.com/janedeveloper/myboard",
"email": "jane@janedeveloper.org",
"help": {
"online": "http://janedeveloper.org/forum/myboard"
},
"platforms": [
{
"name": "My Board",
"architecture": "avr",
"version": "1.0.0",
"category": "Contributed",
"help": {
"online": "http://janedeveloper.org/forum/myboard"
},
"url": "https://janedeveloper.github.io/myboard/myboard-1.0.0.zip",
"archiveFileName": "myboard-1.0.0.zip",
"checksum": "SHA-256:ec3ff8a1dc96d3ba6f432b9b837a35fd4174a34b3d2927de1d51010e8b94f9f1",
"size": "15005",
"boards": [
{"name": "My Board"},
{"name": "My Board Pro"}
],
"toolsDependencies": [
{
"packager": "arduino",
"name": "avr-gcc",
"version": "4.8.1-arduino5"
},
{
"packager": "arduino",
"name": "avrdude",
"version": "6.0.1-arduino5"
}
]
},
{
"name": "My Board",
"architecture": "avr",
"version": "1.0.1",
"category": "Contributed",
"help": {
"online": "http://janedeveloper.org/forum/myboard"
},
"url": "https://janedeveloper.github.io/myboard/myboard-1.0.1.zip",
"archiveFileName": "myboard-1.0.1.zip",
"checksum": "SHA-256:9c86ee28a7ce9fe33e8b07ec643316131e0031b0d22e63bb398902a5fdadbca9",
"size": "15125",
"boards": [
{"name": "My Board"},
{"name": "My Board Pro"}
],
"toolsDependencies": [
{
"packager": "arduino",
"name": "avr-gcc",
"version": "4.8.1-arduino5"
},
{
"packager": "arduino",
"name": "avrdude",
"version": "6.0.1-arduino5"
}
]
}
],
"tools":[]
}
]
}
```
In the example there is one `PACKAGE`, My Board. The package is compatible with the AVR architecture. There are two versions of the `PACKAGE`, 1.0.0 and 1.0.1. No `TOOLS` needed to be installed so that section was left blank.
Here is the Boards Manager entry created by the example:
![Boards Manager screenshot](img/boards-manager-screenshot.png)
## Installation archive structure
The installation archives contain the Board support files. Supported formats are .zip, .tar.bz2, and .tar.gz.
The folder structure of the core archive is slightly different from the standard manually installed Arduino 1.5+ compatible hardware folder structure. You must remove the architecture folder(e.g., `avr` or `arm`), moving all the files and folders within the architecture folder up a level.
***
After adding Boards Manager support for your boards, please share the JSON index file URL on the [Unofficial list of 3rd party boards support urls](https://github.com/arduino/Arduino/wiki/Unofficial-list-of-3rd-party-boards-support-urls).
docs/platform-specification.md 0 → 100644
View file @ 97c4f004
This specification is a 3rd party Hardware format to be used in Arduino IDE starting from 1.5.x series.<br>
This specification allows a 3rd party vendor/maintainer to add support for new boards inside the Arduino IDE by providing a file to unzip into the *hardware* folder of Arduino's sketchbook folder.<br>
It is also possible to add new 3rd party boards by providing just one configuration file.
## Hardware Folders structure
The new hardware folders have a hierarchical structure organized in two levels:
- the first level is the vendor/maintainer
- the second level is the supported architecture
A vendor/maintainer can have multiple supported architectures. For example, below we have three hardware vendors called "arduino", "yyyyy" and "xxxxx":
hardware/arduino/avr/... - Arduino - AVR Boards
hardware/arduino/sam/... - Arduino - SAM (32bit ARM) Boards
hardware/yyyyy/avr/... - Yyy - AVR
hardware/xxxxx/avr/... - Xxx - AVR
The vendor "arduino" has two supported architectures (AVR and SAM), while "xxxxx" and "yyyyy" have only AVR.
If possible, follow existing architecture name conventions when creating hardware packages. The architecture folder name is used to determine library compatibility and also to permit referencing resources from another core of the same architecture so using a non-standard architecture name can only be harmful to your users. Architecture values are case sensitive (e.g. `AVR` != `avr`). Use the vendor folder name to differentiate your package, **NOT** the architecture name.
## Architecture configurations
Each architecture must be configured through a set of configuration files:
* **platform.txt** contains definitions for the CPU architecture used (compiler, build process parameters, tools used for upload, etc.)
* **boards.txt** contains definitions for the boards (board name, parameters for building and uploading sketches, etc.)
* **programmers.txt** contains definitions for external programmers (typically used to burn bootloaders or sketches on a blank CPU/board)
### Configuration files format
A configuration file is a list of "key=value" properties. The **value** of a property can be expressed using the value of another property by putting its name inside brackets "{" "}". For example:
compiler.path=/tools/g++_arm_none_eabi/bin/
compiler.c.cmd=arm-none-eabi-gcc
[....]
recipe.c.o.pattern={compiler.path}{compiler.c.cmd}
In this example the property **recipe.c.o.pattern** will be set to **/tools/g++_arm_none_eabi/bin/arm-none-eabi-gcc** that is the composition of the two properties **compiler.path** and **compiler.c.cmd**.
#### Comments
Lines starting with **#** are treated as comments and will be ignored.
# Like in this example
# --------------------
# I'm a comment!
#### Automatic property override for specific OS
We can specify an OS-specific value for a property. For example the following file:
tools.bossac.cmd=bossac
tools.bossac.cmd.windows=bossac.exe
will set the property **tools.bossac.cmd** to the value **bossac** on Linux and Mac OS and **bossac.exe** on Windows. Suffixes [supported](https://github.com/arduino/Arduino/blob/1.8.12/arduino-core/src/processing/app/helpers/PreferencesMap.java#L110-L112) are `.linux`, `.windows` and `.macosx`.
#### Global Predefined properties
The Arduino IDE sets the following properties that can be used globally in all configurations files:
* `{runtime.platform.path}`: the absolute path of the [board platform](#platform-terminology) folder (i.e. the folder containing boards.txt)
* `{runtime.hardware.path}`: the absolute path of the hardware folder (i.e. the folder containing the [board platform](#platform-terminology) folder)
* `{runtime.ide.path}`: the absolute path of the Arduino IDE folder
* `{runtime.ide.version}`: the version number of the Arduino IDE as a number (this uses two digits per version number component, and removes the points and leading zeroes, so Arduino IDE 1.8.3 becomes `01.08.03` which becomes `runtime.ide.version=10803`).
* `{ide_version}`: Compatibility alias for `{runtime.ide.version}`
* `{runtime.os}`: the running OS ("linux", "windows", "macosx")
Compatibility note: Versions before 1.6.0 only used one digit per version number component in `{runtime.ide.version}` (so 1.5.9 was `159`, not `10509`).
## platform.txt
The platform.txt file contains information about a platform's specific aspects (compilers
command line flags, paths, system libraries, etc.).
The following meta-data must be defined:
name=Arduino AVR Boards
version=1.5.3
The **name** will be shown in the Boards menu of the Arduino IDE.<br>
The **version** is currently unused, it is reserved for future use (probably together with the libraries manager to handle dependencies on cores).
### Build process
The platform.txt file is used to configure the build process performed by the Arduino IDE. This is done through a list of **recipes**. Each recipe is a command line expression that explains how to call the compiler (or other tools) for every build step and which parameter should be passed.
The Arduino IDE, before starting the build, determines the list of files to compile. The list is composed by:
- the user's Sketch
- source code in the selected board's Core
- source code in the Libraries used in the sketch
The IDE creates a temporary folder to store the build artifacts whose path is available through the global property **{build.path}**. A property **{build.project_name}** with the name of the project and a property **{build.arch}** with the name of the architecture is set as well.
* `{build.path}`: The path to the temporary folder to store build artifacts
* `{build.project_name}`: The project name
* `{build.arch}`: The MCU architecture (avr, sam, etc...)
There are some other **{build.xxx}** properties available, that are explained in the boards.txt section of this guide.
#### Recipes to compile source code
We said that the Arduino IDE determines a list of files to compile. Each file can be source code written in C (.c files), C++ (.cpp files) or Assembly (.S files). Every language is compiled using its respective **recipe**:
* `recipe.c.o.pattern`: for C files
* `recipe.cpp.o.pattern`: for CPP files
* `recipe.S.o.pattern`: for Assembly files
The recipes can be built concatenating other properties set by the IDE (for each file compiled):
* `{includes}`: the list of include paths in the format "-I/include/path -I/another/path...."
* `{source_file}`: the path to the source file
* `{object_file}`: the path to the output file
For example the following is used for AVR:
## Compiler global definitions
compiler.path={runtime.ide.path}/tools/avr/bin/
compiler.c.cmd=avr-gcc
compiler.c.flags=-c -g -Os -w -ffunction-sections -fdata-sections -MMD
[......]
## Compile c files
recipe.c.o.pattern="{compiler.path}{compiler.c.cmd}" {compiler.c.flags} -mmcu={build.mcu} -DF_CPU={build.f_cpu} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} {build.extra_flags} {includes} "{source_file}" -o "{object_file}"
Note that some properties, like **{build.mcu}** for example, are taken from the **boards.txt** file which is documented later in this specification.
#### Recipes to build the core.a archive file
The core of the selected board is compiled as described in the previous paragraph, but the object files obtained from the compile are also archived into a static library named *core.a* using the **recipe.ar.pattern**.
The recipe can be built concatenating the following properties set by the IDE:
* `{object_file}`: the object file to include in the archive
* `{archive_file_path}`: fully qualified archive file (ex. "/path/to/core.a"). This property was added in Arduino IDE 1.6.6/arduino builder 1.0.0-beta12 as a replacement for `{build.path}/{archive_file}`.
* `{archive_file}`: the name of the resulting archive (ex. "core.a")
For example, Arduino provides the following for AVR:
compiler.ar.cmd=avr-ar
compiler.ar.flags=rcs
[......]
## Create archives
recipe.ar.pattern="{compiler.path}{compiler.ar.cmd}" {compiler.ar.flags} "{archive_file_path}" "{object_file}"
#### Recipes for linking
All the artifacts produced by the previous steps (sketch object files, libraries object files and core.a archive) are linked together using the **recipe.c.combine.pattern**.
The recipe can be built concatenating the following properties set by the IDE:
* `{object_files}`: the list of object files to include in the archive ("file1.o file2.o ....")
* `{archive_file_path}`: fully qualified archive file (ex. "/path/to/core.a"). This property was added in Arduino IDE 1.6.6/arduino builder 1.0.0-beta12 as a replacement for `{build.path}/{archive_file}`.
* `{archive_file}`: the name of the core archive file (ex. "core.a")
For example the following is used for AVR:
compiler.c.elf.flags=-Os -Wl,--gc-sections
compiler.c.elf.cmd=avr-gcc
[......]
## Combine gc-sections, archives, and objects
recipe.c.combine.pattern="{compiler.path}{compiler.c.elf.cmd}" {compiler.c.elf.flags} -mmcu={build.mcu} -o "{build.path}/{build.project_name}.elf" {object_files} "{archive_file_path}" "-L{build.path}" -lm
#### Recipes for extraction of executable files and other binary data
An arbitrary number of extra steps can be performed by the IDE at the end of objects linking.
These steps can be used to extract binary data used for upload and they are defined by a set of recipes with the following format:
recipe.objcopy.FILE_EXTENSION_1.pattern=[.....]
recipe.objcopy.FILE_EXTENSION_2.pattern=[.....]
[.....]
`FILE_EXTENSION_x` must be replaced with the extension of the extracted file, for example the AVR platform needs two files a `.hex` and a `.eep`, so we made two recipes like:
recipe.objcopy.eep.pattern=[.....]
recipe.objcopy.hex.pattern=[.....]
There are no specific properties set by the IDE here.
A full example for the AVR platform can be:
## Create eeprom
recipe.objcopy.eep.pattern="{compiler.path}{compiler.objcopy.cmd}" {compiler.objcopy.eep.flags} "{build.path}/{build.project_name}.elf" "{build.path}/{build.project_name}.eep"
## Create hex
recipe.objcopy.hex.pattern="{compiler.path}{compiler.elf2hex.cmd}" {compiler.elf2hex.flags} "{build.path}/{build.project_name}.elf" "{build.path}/{build.project_name}.hex"
#### Recipes to compute binary sketch size
At the end of the build the Arduino IDE shows the final binary sketch size to the user. The size is calculated using the recipe **recipe.size.pattern**. The output of the command executed using the recipe is parsed through the regular expression set in the property **recipe.size.regex**. The regular expression must match the sketch size.
For AVR we have:
compiler.size.cmd=avr-size
[....]
## Compute size
recipe.size.pattern="{compiler.path}{compiler.size.cmd}" -A "{build.path}/{build.project_name}.hex"
recipe.size.regex=Total\s+([0-9]+).*
#### Recipes to export compiled binary
When you do a **Sketch > Export compiled Binary**, the compiled binary is copied from the build folder to the sketch folder. Two binaries are copied; the standard binary, and a binary that has been merged with the bootloader file (identified by the `.with_bootloader` in the filename).
Two recipes affect how **Export compiled Binary** works:
* **recipe.output.tmp_file**: Defines the binary's filename in the build folder.
* **recipe.output.save_file**: Defines the filename to use when copying the binary file to the sketch folder.
As with other processes, there are pre and post build hooks for **Export compiled Binary**.
The **recipe.hooks.savehex.presavehex.NUMBER.pattern** and **recipe.hooks.savehex.postsavehex.NUMBER.pattern** hooks (but not **recipe.output.tmp_file** and **recipe.output.save_file**) can be built concatenating the following properties set by the IDE:
{sketch_path} - the absolute path of the sketch folder
#### Recipe to run the preprocessor
For detecting what libraries to include in the build, and for generating function prototypes, the Arduino IDE must be able to run (just) the preprocessor. For this, the **recipe.preproc.macros** recipe exists. This recipe must run the preprocessor on a given source file, writing the preprocessed output to a given output file, and generate (only) preprocessor errors on standard output. This preprocessor run should happen with the same defines and other preprocessor-influencing-options as for normally compiling the source files.
The recipes can be built concatenating other properties set by the IDE (for each file compiled):
* `{includes}`: the list of include paths in the format "-I/include/path -I/another/path...."
* `{source_file}`: the path to the source file
* `{preprocessed_file_path}`: the path to the output file
For example the following is used for AVR:
preproc.macros.flags=-w -x c++ -E -CC
recipe.preproc.macros="{compiler.path}{compiler.cpp.cmd}" {compiler.cpp.flags} {preproc.macros.flags} -mmcu={build.mcu} -DF_CPU={build.f_cpu} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} {compiler.cpp.extra_flags} {build.extra_flags} {includes} "{source_file}" -o "{preprocessed_file_path}"
Note that the `{preprocessed_file_path}` might point to (your operating system's equivalent) of `/dev/null`. In this case, also passing `-MMD` to gcc is problematic, as it will try to generate a dependency file called `/dev/null.d`, which will usually result in a permission error. Since platforms typically include `{compiler.cpp.flags}` here, which includes `-MMD`, the Arduino IDE automatically filters out the `-MMD` option from the `recipe.preproc.macros` recipe to prevent this error.
Note that older IDE versions used the **recipe.preproc.includes** recipe to determine includes, which is undocumented here. Since Arduino IDE 1.6.7 (arduino-builder 1.2.0) this was changed and **recipe.preproc.includes** is no longer used.
#### Pre and post build hooks (since IDE 1.6.5)
You can specify pre and post actions around each recipe. These are called "hooks". Here is the complete list of available hooks:
* `recipe.hooks.sketch.prebuild.NUMBER.pattern` (called before sketch compilation)
* `recipe.hooks.sketch.postbuild.NUMBER.pattern` (called after sketch compilation)
* `recipe.hooks.libraries.prebuild.NUMBER.pattern` (called before libraries compilation)
* `recipe.hooks.libraries.postbuild.NUMBER.pattern` (called after libraries compilation)
* `recipe.hooks.core.prebuild.NUMBER.pattern` (called before core compilation)
* `recipe.hooks.core.postbuild.NUMBER.pattern` (called after core compilation)
* `recipe.hooks.linking.prelink.NUMBER.pattern` (called before linking)
* `recipe.hooks.linking.postlink.NUMBER.pattern` (called after linking)
* `recipe.hooks.objcopy.preobjcopy.NUMBER.pattern` (called before objcopy recipes execution)
* `recipe.hooks.objcopy.postobjcopy.NUMBER.pattern` (called after objcopy recipes execution)
* `recipe.hooks.savehex.presavehex.NUMBER.pattern` (called before savehex recipe execution)
* `recipe.hooks.savehex.postsavehex.NUMBER.pattern` (called after savehex recipe execution)
Example: you want to execute 2 commands before sketch compilation and 1 after linking. You'll add to your platform.txt
```
recipe.hooks.sketch.prebuild.1.pattern=echo sketch compilation started at
recipe.hooks.sketch.prebuild.2.pattern=date
recipe.hooks.linking.postlink.1.pattern=echo linking is complete
```
Warning: hooks recipes are sorted before execution. If you need to write more than 10 recipes for a single hook, pad the number with a zero, for example:
```
recipe.hooks.sketch.prebuild.01.pattern=echo 1
recipe.hooks.sketch.prebuild.02.pattern=echo 2
...
recipe.hooks.sketch.prebuild.11.pattern=echo 11
```
## Global platform.txt
Properties defined in a platform.txt created in the **hardware** subfolder of the IDE installation folder will be used for all platforms and will override local properties.
## platform.local.txt
Introduced in Arduino IDE 1.5.7. This file can be used to override properties defined in platform.txt or define new properties without modifying platform.txt (e.g. when platform.txt is tracked by a version control system). It should be placed in the architecture folder.
## boards.txt
This file contains definitions and meta-data for the boards supported. Every board must be referred through its short name, the board ID. The settings for a board are defined through a set of properties
with keys having the board ID as prefix.
For example the board ID chosen for the Arduino Uno board is "uno". An extract of the Uno board configuration in boards.txt looks like:
[......]
uno.name=Arduino Uno
uno.build.mcu=atmega328p
uno.build.f_cpu=16000000L
uno.build.board=AVR_UNO
uno.build.core=arduino
uno.build.variant=standard
[......]
Note that all the relevant keys start with the board ID **uno.xxxxx**.
The **uno.name** property contains the name of the board shown in the Board menu of the Arduino IDE.
The **uno.build.board** property is used to set a compile-time variable **ARDUINO_{build.board}** to allow use of conditional code between `#ifdef`s. The Arduino IDE automatically generates a **build.board** value if not defined. In this case the variable defined at compile time will be `ARDUINO_AVR_UNO`.
The other properties will override the corresponding global properties of the IDE when the user selects the board. These properties will be globally available, in other configuration files too, without the board ID prefix:
uno.build.mcu => build.mcu
uno.build.f_cpu => build.f_cpu
uno.build.board => build.board
uno.build.core => build.core
uno.build.variant => build.variant
This explains the presence of **{build.mcu}** or **{build.board}** in the platform.txt recipes: their value is overwritten respectively by **{uno.build.mcu}** and **{uno.build.board}** when the Uno board is selected!
Moreover the IDE automatically provides the following properties:
* `{build.core.path}`: The path to the selected board's core folder (inside the [core platform](#platform-terminology), for example hardware/arduino/avr/core/arduino)
* `{build.system.path}`: The path to the [core platform](#platform-terminology)'s system folder if available (for example hardware/arduino/sam/system)
* `{build.variant.path}`: The path to the selected board variant folder (inside the [variant platform](#platform-terminology), for example hardware/arduino/avr/variants/micro)
### Cores
Cores are placed inside the **cores** subfolder. Many different cores can be provided within a single platform. For example the following could be a valid platform layout:
* `hardware/arduino/avr/cores/`: Cores folder for "avr" architecture, package "arduino"
* `hardware/arduino/avr/cores/arduino`: the Arduino Core
* `hardware/arduino/avr/cores/rtos`: an hypothetical RTOS Core
The board's property **build.core** is used by the Arduino IDE to find the core that must be compiled and linked when the board is selected. For example if a board needs the Arduino core the **build.core** variable should be set to:
uno.build.core=arduino
or if the RTOS core is needed, to:
uno.build.core=rtos
In any case the contents of the selected core folder are compiled and the core folder path is added to the include files search path.
### Core Variants
Sometimes a board needs some tweaking on default core configuration (different pin mapping is a typical example). A core variant folder is an additional folder that is compiled together with the core and allows to easily add specific configurations.
Variants must be placed inside the **variants** folder in the current architecture.
For example, Arduino AVR Boards uses:
* `hardware/arduino/avr/cores`: Core folder for "avr" architecture, "arduino" package
* `hardware/arduino/avr/cores/arduino`: The Arduino core
* `hardware/arduino/avr/variants/`: Variant folder for "avr" architecture, "arduino" package
* `hardware/arduino/avr/variants/standard`: ATmega328 based variants
* `hardware/arduino/avr/variants/leonardo`: ATmega32U4 based variants
In this example, the Arduino Uno board needs the *standard* variant so the **build.variant** property is set to *standard*:
[.....]
uno.build.core=arduino
uno.build.variant=standard
[.....]
instead, the Arduino Leonardo board needs the *leonardo* variant:
[.....]
leonardo.build.core=arduino
leonardo.build.variant=leonardo
[.....]
In the example above, both Uno and Leonardo share the same core but use different variants.<br>
In any case, the contents of the selected variant folder path is added to the include search path and its contents are compiled and linked with the sketch.
The parameter **build.variant.path** is automatically found by the IDE.
## Tools
The Arduino IDE uses external command line tools to upload the compiled sketch to the board or to burn bootloaders using external programmers. Currently *avrdude* is used for AVR based boards and *bossac* for SAM based boards, but there is no limit, any command line executable can be used. The command line parameters are specified using **recipes** in the same way used for platform build process.
Tools are configured inside the platform.txt file. Every Tool is identified by a short name, the Tool ID.
A tool can be used for different purposes:
- **upload** a sketch to the target board (using a bootloader preinstalled on the board)
- **program** a sketch to the target board using an external programmer
- **erase** the target board's flash memory using an external programmer
- burn a **bootloader** into the target board using an external programmer
Each action has its own recipe and its configuration is done through a set of properties having key starting with **tools** prefix followed by the tool ID and the action:
[....]
tools.avrdude.upload.pattern=[......]
[....]
tools.avrdude.program.pattern=[......]
[....]
tools.avrdude.erase.pattern=[......]
[....]
tools.avrdude.bootloader.pattern=[......]
[.....]
A tool may have some actions not defined (it's not mandatory to define all four actions).<br>
Let's look at how the **upload** action is defined for avrdude:
tools.avrdude.path={runtime.tools.avrdude.path}
tools.avrdude.cmd.path={path}/bin/avrdude
tools.avrdude.config.path={path}/etc/avrdude.conf
tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" -p{build.mcu} -c{upload.protocol} -P{serial.port} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
A **{runtime.tools.TOOL_NAME.path}** and **{runtime.tools.TOOL_NAME-TOOL_VERSION.path}** property is generated for the tools of Arduino AVR Boards and any other platform installed via Boards Manager. **{runtime.tools.TOOL_NAME.path}** points to the latest version of the tool available.
The Arduino IDE makes the tool configuration properties available globally without the prefix. For example, the **tools.avrdude.cmd.path** property can be used as **{cmd.path}** inside the recipe, and the same happens for all the other avrdude configuration variables.
#### Verbose parameter
It is possible for the user to enable verbosity from the Arduino IDE's Preferences panel. This preference is transferred to the command line by the IDE using the **ACTION.verbose** property (where ACTION is the action we are considering).<br>
When the verbose mode is enabled the **tools.TOOL_ID.ACTION.params.verbose** property is copied into **ACTION.verbose**. When the verbose mode is disabled, the **tools.TOOL_ID.ACTION.params.quiet** property is copied into **ACTION.verbose**. Confused? Maybe an example will clear things:
tools.avrdude.upload.params.verbose=-v -v -v -v
tools.avrdude.upload.params.quiet=-q -q
tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" {upload.verbose} -p{build.mcu} -c{upload.protocol} -P{serial.port} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
In this example if the user enables verbose mode, then **{upload.params.verbose}** is used in **{upload.verbose}**:
tools.avrdude.upload.params.verbose => upload.verbose
If the user didn't enable verbose mode, the **{upload.params.quiet}** is used in **{upload.verbose}**:
tools.avrdude.upload.params.quiet => upload.verbose
### Sketch upload configuration
The Upload action is triggered when the user clicks on the "Upload" button on the IDE toolbar.
The Arduino IDE selects the tool to be used for upload by looking at the **upload.tool** property.
A specific **upload.tool** property should be defined for every board in boards.txt:
[......]
uno.upload.tool=avrdude
[......]
leonardo.upload.tool=avrdude
[......]
Also other upload parameters can be defined together, for example in the Arduino boards.txt we have:
[.....]
uno.name=Arduino Uno
uno.upload.tool=avrdude
uno.upload.protocol=arduino
uno.upload.maximum_size=32256
uno.upload.speed=115200
[.....]
leonardo.name=Arduino Leonardo
leonardo.upload.tool=avrdude
leonardo.upload.protocol=avr109
leonardo.upload.maximum_size=28672
leonardo.upload.speed=57600
leonardo.upload.use_1200bps_touch=true
leonardo.upload.wait_for_upload_port=true
[.....]
Most **{upload.XXXX}** variables are used later in the avrdude upload recipe in platform.txt:
[.....]
tools.avrdude.upload.pattern="{cmd.path}" "-C{config.path}" {upload.verbose} -p{build.mcu} -c{upload.protocol} -P{serial.port} -b{upload.speed} -D "-Uflash:w:{build.path}/{build.project_name}.hex:i"
[.....]
#### 1200bps bootloader reset
Most Arduino boards use a dedicated USB-to-serial chip, that takes care of restarting the main MCU (starting the bootloader) when the serial port is opened. However, boards that have a native USB connection (such as the Leonardo or Zero) will have to disconnect from USB when rebooting into the bootloader (after which the bootloader reconnects to USB and offers a new serial port for uploading). After the upload is complete, the bootloader disconnects from USB again, starts the sketch, which then reconnects to USB. Because of these reconnections, the standard restart-on-serial open will not work, since that would cause the serial port to disappear and be closed again. Instead, the sketch running on these boards interpret a bitrate of 1200bps as a signal the bootloader should be started.
To let the IDE perform these steps, two board parameters can be set:
* `use_1200bps_touch` causes the IDE to briefly open the selected serial port at 1200bps (8N1) before starting the upload.
* `wait_for_upload_port` causes the IDE to wait for the serial port to (re)appear before and after the upload. This is only used when `use_1200bps_touch` is also set. When set, after doing the 1200bps touch, the IDE will wait for a new serial port to appear and use that as the port for uploads. Alternatively, if the original port does not disappear within a few seconds, the upload continues with the original port (which can be the case if the board was already put into bootloader manually, or the IDE missed the disconnect and reconnect). Additionally, after the upload is complete, the IDE again waits for a new port to appear (or the originally selected port to be present).
Note that the IDE implementation of this 1200bps touch has some peculiarities, and the newer `arduino-cli` implementation also seems different (does not wait for the port after the reset, which is probably only needed in the IDE to prevent opening the wrong port on the serial monitor, and does not have a shorter timeout when the port never disappears).
### Serial port
The Arduino IDE auto-detects all available serial ports on the running system and lets the user choose one from the GUI. The selected port is available as a configuration property **{serial.port}**.
### Upload using an external programmer
**TODO...**
The platform.txt associated with the selected programmer will be used.
### Burn Bootloader
**TODO...**
The platform.txt associated with the selected board will be used.
## Custom board menus
The Arduino IDE allows adding extra menu items under the Tools menu. With these sub-menus the user can select different configurations for a specific board (for example a board could be provided in two or more variants with different CPUs, or may have different crystal speed based on the board model, and so on...).
Let's see an example of how a custom menu is implemented.
The board used in the example is the Arduino Duemilanove. This board was produced in two models, one with an ATmega168 CPU and another with an ATmega328P.<br>
We are going then to define a custom menu "Processor" that allows the user to choose between the two
different microcontrollers.
We must first define a set of **menu.MENU_ID=Text** properties. Text is what is displayed on the GUI for every custom menu we are going to create and must be declared at the beginning of the boards.txt file:
menu.cpu=Processor
[.....]
in this case we declare only one custom menu "Processor" which we refer using the "cpu" MENU_ID.<br>
Now let's add, always in the boards.txt file, the default configuration (common to all processors) for the duemilanove board:
menu.cpu=Processor
[.....]
duemilanove.name=Arduino Duemilanove
duemilanove.upload.tool=avrdude
duemilanove.upload.protocol=arduino
duemilanove.build.f_cpu=16000000L
duemilanove.build.board=AVR_DUEMILANOVE
duemilanove.build.core=arduino
duemilanove.build.variant=standard
[.....]
Now let's define the options to show in the "Processor" menu:
[.....]
duemilanove.menu.cpu.atmega328=ATmega328P
[.....]
duemilanove.menu.cpu.atmega168=ATmega168
[.....]
We have defined two options: "ATmega328P" and "ATmega168".<br>
Note that the property keys must follow the format **BOARD_ID.menu.MENU_ID.OPTION_ID=Text**.<br>
Finally, the specific configuration for every option:
[.....]
## Arduino Duemilanove w/ ATmega328P
duemilanove.menu.cpu.atmega328=ATmega328P
duemilanove.menu.cpu.atmega328.upload.maximum_size=30720
duemilanove.menu.cpu.atmega328.upload.speed=57600
duemilanove.menu.cpu.atmega328.build.mcu=atmega328p
## Arduino Duemilanove w/ ATmega168
duemilanove.menu.cpu.atmega168=ATmega168
duemilanove.menu.cpu.atmega168.upload.maximum_size=14336
duemilanove.menu.cpu.atmega168.upload.speed=19200
duemilanove.menu.cpu.atmega168.build.mcu=atmega168
[.....]
Note that when the user selects an option, all the "sub properties" of that option are copied in the global configuration. For example when the user selects "ATmega168" from the "Processor" menu the Arduino IDE makes the configuration under atmega168 available globally:
duemilanove.menu.cpu.atmega168.upload.maximum_size => upload.maximum_size
duemilanove.menu.cpu.atmega168.upload.speed => upload.speed
duemilanove.menu.cpu.atmega168.build.mcu => build.mcu
There is no limit to the number of custom menus that can be defined.
**TODO: add an example with more than one submenu**
## Referencing another core, variant or tool
Inside the boards.txt we can define a board that uses a core provided by another vendor/mantainer using the syntax **VENDOR_ID:CORE_ID**. For example, if we want to define a board that uses the "arduino" core from the "arduino" vendor we should write:
[....]
myboard.name=My Wonderful Arduino Compatible board
myboard.build.core=arduino:arduino
[....]
Note that we don't need to specify any architecture since the same architecture of "myboard" is used, so we just say "arduino:arduino" instead of "arduino:avr:arduino".
The platform.txt settings are inherited from the referenced core platform, thus there is no need to provide a platform.txt unless there are some specific properties that need to be overridden.
The libraries from the referenced platform are used, thus there is no need to provide a libraries. If libraries are provided the list of available libraries are the sum of the 2 libraries where the referencing platform has priority over the referenced platform.
In the same way we can use variants and tools defined on another platform:
[....]
myboard.build.variant=arduino:standard
myboard.upload.tool=arduino:avrdude
myboard.bootloader.tool=arduino:avrdude
[....]
Using this syntax allows us to reduce the minimum set of files needed to define a new "hardware" to just the boards.txt file.
Note that referencing a variant in another platform does *not* inherit any properties from that platform's platform.txt (like referencing a core does).
### Platform Terminology
Because boards can reference cores, variants and tools in different platforms, this means that a single build or upload can use data from up to four different platforms. To keep this clear, the following terminology is used:
* The "board platform" is the platform that defines the currently selected board (e.g. the platform that contains the board.txt the board is defined in.
* The "core platform" is the the platform that contains the core to be used.
* The "variant platform" is the platform that contains the variant to be used.
* The "tool platform" is the platform that contains the tool used for the current operation.
In the most common case, without any references, all of these will refer to the same platform.
Note that the above terminology is not in widespread use, but was invented for clarity within this document. In the actual arduino-cli code, the "board platform" is called `targetPlatform`, the "core platform" is called `actualPlatform`, the others are pretty much nameless.
## boards.local.txt
Introduced in Arduino IDE 1.6.6. This file can be used to override properties defined in boards.txt or define new properties without modifying boards.txt.
## keywords.txt
As of Arduino IDE 1.6.6, per-platform keywords can be defined by adding a keywords.txt file to the platform's architecture folder. These keywords are only highlighted when one of the boards of that platform are selected. This file follows the [same format](library-specification.md#keywords) as the keywords.txt used in libraries. Each keyword must be separated from the keyword identifier by a tab.
docs/sketch-build-process.md 0 → 100644
View file @ 97c4f004
The process the Arduino environment uses to build a sketch. More useful information can be found in the [Arduino platform specification](platform-specification.md). Note that the following refers specifically to the build process for AVR targets. Other architectures will have a similar build process.
## Overview
A number of things have to happen for your Arduino code to get onto the Arduino board. First, the Arduino environment performs some minor pre-processing to turn your sketch into a C++ program. Next, dependencies of the sketch are located. It then gets passed to a compiler (avr-gcc), which turns the human readable code into machine readable instructions (or object files). Then your code gets combined with (linked against) the standard Arduino libraries that provide basic functions like `digitalWrite()` or `Serial.print()`. The result is a single Intel hex file, which contains the specific bytes that need to be written to the program memory of the chip on the Arduino board. This file is then uploaded to the board: transmitted over the USB or serial connection via the bootloader already on the chip or with external programming hardware.
## Pre-Processing
The Arduino environment performs a few transformations to your sketch before passing it to the avr-gcc compiler:
- All .ino and .pde files in the sketch folder (shown in the IDE as tabs with no extension) are concatenated together, starting with the file that matches the folder name followed by the others in alphabetical order, and the .cpp extension is added to the filename.
- If not already present, `#include <Arduino.h>` is added to the sketch. This header file (found in the core folder for the currently selected board) includes all the definitions needed for the standard Arduino core.
- Prototypes are generated for all function definitions in .ino/.pde files that don't already have prototypes. In some rare cases prototype generation may fail for some functions. To work around this, you can provide your own prototypes for these functions.
- `#line` directives are added to make warning or error messages reflect the original sketch layout.
No pre-processing is done to files in a sketch with any extension other than .ino or .pde. Additionally, .h files in the sketch are not automatically #included from the main sketch file. Further, if you want to call functions defined in a .c file from a .cpp file (like one generated from your sketch), you'll need to wrap its declarations in an 'extern "C" {}' block that is defined only inside of C++ files.
## Dependency Resolution
The sketch is scanned recursively for dependencies. There are predefined include search paths:
1. Core library folder (as defined by [`{build.core}`](platform-specification.md#boardstxt))
1. Variant folder (as defined by [`{build.variant}`](platform-specification.md#boardstxt))
1. Standard system directories (e.g., [`{runtime.tools.avr-gcc.path}/avr/include`](platform-specification.md#tools))
1. Include search paths added to resolve prior dependencies
If the dependency is not present in any of those locations, the installed libraries are then searched (see the [**Location Priority** table](#location-priority) below for library locations). For information on the allowed library sub-folder structures see [the Arduino library specification](library-specification.md#source-code). `-I` options are generated for the path to each library dependency and appended to the [`includes` property](platform-specification.md#recipes-to-compile-source-code), to be used in [compilation recipes](platform-specification.md#recipes-to-compile-source-code) in platform.txt.
If multiple libraries contain a file that matches the `#include` directive, the priority is determined by applying the following rules, one by one in this order, until a rule determines a winner:
1. A library that is architecture compatible wins against a library that is not architecture compatible (see [**Architecture Matching**](#architecture-matching))
1. A library that has better "folder name priority" wins (see [**Folder Name Priority**](#folder-name-priority))
1. A library that is architecture optimized wins against a library that is not architecture optimized (see [**Architecture Matching**](#architecture-matching))
1. A library that has a better "location priority" wins (see [**Location Priority**](#location-priority))
1. A library that has a folder name with a better score using the "closest-match" algorithm wins
1. A library that has a folder name that comes first in alphanumeric order wins
### Architecture Matching
A library is considered **compatible** with architecture `X` if the `architectures` field in [library.properties](library-specification.md#library-metadata):
- explicitly contains the architecture `X`
- contains the catch-all `*`
- is not specified at all.
A library is considered **optimized** for architecture `X` only if the `architectures` field in library.properties explicitly contains the architecture `X`. This means that a library that is optimized for architecture `X` is also compatible with it.
Examples:
`architectures` field in `library.properties` | Compatible with `avr` | Optimized for `avr`
---|---|---
not specified | YES | NO
`architectures=*` | YES | NO
`architectures=avr` | YES | YES
`architectures=*,avr` | YES | YES
`architectures=*,esp8266` | YES | NO
`architectures=avr,esp8266` | YES | YES
`architectures=samd` | NO | NO
### Folder Name Priority
The "folder name priority" is determined as follows (in order of highest to lowest priority):
Rule | Example for `Servo.h`
---|---
The folder name matches the include 100% | `Servo`
The folder name matches the include 100%, except with a `-master` suffix | `Servo-master`
The folder name has a matching prefix | `ServoWhatever`
The folder name has a matching suffix | `AwesomeServo`
The folder name contains the include | `AnAwesomeServoForWhatever`
### Location Priority
The "location priority" is determined as follows (in order of highest to lowest priority):
1. The library is in the sketchbook (`{sketchbook path}/libraries`)
1. The library is bundled with the board platform/core ([`{runtime.platform.path}/libraries`](platform-specification.md#global-predefined-properties))
1. The library is bundled with the [referenced](platform-specification.md#referencing-another-core-variant-or-tool) board platform/core
1. The library is bundled with the IDE ([`{runtime.ide.path}/libraries`](platform-specification.md#global-predefined-properties))
## Compilation
Sketches are compiled by avr-gcc and avr-g++ according to the variables in the boards.txt file of the selected board's [platform](platform-specification.md).
The sketch is built in a temporary directory in the system-wide temporary directory (e.g. /tmp on Linux).
Files taken as source files for the build process are .S, .c and .cpp files (including the .cpp file generated from the sketch's .ino and .pde files during the sketch pre-processing step).
Source files of the target are compiled and output with .o extensions to this build directory, as are the main sketch files and any other source files in the sketch and any source files in any libraries which are #included in the sketch.
Before compiling a source file, an attempt is made to reuse the previously compiled .o file, which speeds up the build process. A special .d (dependency) file provides a list of all other files included by the source. The compile step is skipped if the .o and .d files exist and have timestamps newer than the source and all the dependent files. If the source or any dependent file has been modified, or any error occurs verifying the files, the compiler is run normally, writing a new .o & .d file. After a new board is selected from the Tools menu, all source files are rebuilt on the next compile.
These .o files are then linked together into a static library and the main sketch file is linked against this library. Only the parts of the library needed for your sketch are included in the final .hex file, reducing the size of most sketches.
The .hex file is the final output of the compilation which is then uploaded to the board.
If verbose output during compilation is checked in the Preferences dialog, the complete command line of each external command executed as part of the build process will be printed in the editor console.
## Uploading
Sketches are uploaded by avrdude. The upload process is also controlled by variables in the boards and main preferences files. See the [Arduino platform specification](platform-specification.md) page for details.
If verbose output during upload is checked in the Preferences dialog, debugging information will be output to the editor console, including avrdude command lines and verbose output.
mkdocs.yml
View file @ 97c4f004
......@@ -103,3 +103,7 @@ nav:
- monitor: rpc/monitor.md
- settings: rpc/settings.md
- debug: rpc/debug.md
- sketch-build-process.md
- library-specification.md
- platform-specification.md
- package_index.json specification: package_index_json-specification.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