-
-
Notifications
You must be signed in to change notification settings - Fork 7k
Arduino IDE 1.5 3rd party Hardware specification
WARNING
This specification is a proposal of a new 3rd party Hardware format to be used in Arduino IDE starting from 1.5 series.
The correct implementation of this specification allows a 3rd party vendor/maintainer to add support for his boards to the Arduino IDE just by unzipping a file into the hardware folder of Arduino. It should be possible also to make a singlefile-hardware-addon that means adding a new 3rd party board(s) to Arduino IDE by providing just one configuration file.
New hardware folders are structured in two levels: the first level is the vendor/mantainer name; the second level is the name of supported architecture(s).
In the example below we have three hardware vendors called respectively "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
as already said, each vendor folder contains a second level of folders that are the architectures supported: in the example above the vendor "arduino" has two supported architecures (avr and sam), while "xxxxx" and "yyyyy" have only avr.
Each architecture of each vendor must be configured through a set of configuration files:
- boards.txt contains definitions of the boards (board's metadata, parameters for building and uploading sketches, etc.)
- platform.txt contains definitions for the CPU architecture used on the boards (compiler, build process parameters, tools used for upload, etc.)
- programmers.txt contains definitions variables for external programmers (typically used to burn bootloaders or sketches on a blank CPU/board)
Before looking at the content of these file one by one, let's explain their format.
The configuration files are a list of "variable=value" properties. The value of a variable can be expressed using the value of another variable putting his 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 variable 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 variables compiler.path and compiler.c.cmd.
Lines starting with # are treated as comments and will be ignored
# Like in this example
# --------------------
# I'm a comment!
We can specify an OS-specific value for a variable. For example the following snippet:
tools.bossac.cmd=bossac
tools.bossac.cmd.windows=bossac.exe
will set the variable tools.bossac.cmd to the value bossac on linux and macos and bossac.exe on windows.
The Arduino IDE sets the following variables that can be used in all configurations files:
{runtime.hardware.path} - the absolute path to the *hardware* folder
{runtime.ide.path} - the absolute path to the Arduino IDE folder
{runtime.ide.version} - the version number of the Arduino IDE as a number (for example "152" for Arduino IDE 1.5.2)
{runtime.os} - the running OS ("linux", "windows", "macosx")
The platform.txt file contains information about platform's specific aspects (compilers command line flags, path, system libraries, etc.). The following meta-data must be defined:
name=Arduino AVR Boards
version=1.5.3
The name variable will be shown in the Boards menu of the Arduino IDE. The version variable is currently unused, but its useful to keep track of revisions of the platform file.
As we already said, 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 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, generates a list of files to compile that is composed by:
- the user's Sketch
- the selected board's Core
- the Libraries used in the sketch
A temporary folder to store the build artifacts is created and its path is available through the global variable build.path. A variable with the name of the project is set as well.
The Arduino IDE sets the following variables available in every step of the build process:
{build.path} - The path to the temporary folder to store build artifacts
{build.project_name} - The project name
We said that the Arduino IDE determine a list of files to compile. Each file could be source code 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 variables set by the IDE (for each file compiled):
{ide_version} - the IDE version (ex. "152" for Arduino IDE 1.5.2)
{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: the variables build.XXXX are taken from the boards.txt file, we will look how the IDE do this later.
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 variables set by the IDE:
{ide_version} - the IDE version (ex. "152" for Arduino IDE 1.5.2)
{object_file} - the object file to include in the archive
{archive_file} - the name of the resulting archive (ex. "core.a")
For example the following is used for AVR:
compiler.ar.cmd=avr-ar
compiler.ar.flags=rcs
[......]
## Create archives
recipe.ar.pattern="{compiler.path}{compiler.ar.cmd}" {compiler.ar.flags} "{build.path}/{archive_file}" "{object_file}"
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 variables set by the IDE:
{ide_version} - the IDE version (ex. "152" for Arduino IDE 1.5.2)
{object_files} - the list of object files to include in the archive ("file1.o file2.o ....")
{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} "{build.path}/{archive_file}" "-L{build.path}" -lm
Two extra steps are performed by the IDE at the end of objects linking:
recipe.objcopy.eep.pattern=[.....]
recipe.objcopy.hex.pattern=[.....]
There are no specific variables set by the IDE here. These steps can be used to extract binary data to be used for upload (.hex files or .bin files to upload into the microcontroller, or .eep files for eeprom data, etc.)
AVR platform uses the following settings:
## 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"
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 recipe is parsed through the regular expression in the variable recipe.size.regex. The regular expression is applied to the output and 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]+).*
This file contains definitions and meta-data for the supported boards. Every board must be referred through its short name, the board ID. The settings for a board are defined through a set of variables whose name begins with the board ID as prefix.
For example: the board ID chosen for the "Arduino Uno" board is "uno", an extract of the Uno configuration (in boards.txt file) 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
[......]
the uno.name variable contains the extended name of the board shown in the Boards menu of the Arduino IDE.
The other variables are used to override the global configuration of the IDE when the user selects the board. These variables will be globally available (in other configuration files too) without the board ID prefix: this explains the presence of {build.mcu} or {build.board} in the platform.txt recipes.
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 - Arduino Core
hardware/arduino/avr/cores/rtos - an hypotetical RTOS Core
The board's variable build.core is used by the Arduino IDE to find the core that must be compiled and linked with the sketch. 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 inlcude files search path.
Sometime a board needs some tweaking on default core configuration (different pin mapping is a typical example). A 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 variant folder in the current architecture. For example Arduino AVR uses:
hardware/arduino/avr/variant/ - Variant folder for "avr" architecture, "arduino" package
hardware/arduino/avr/variant/standard - mega328 based variants
hardware/arduino/avr/variant/leonardo - mega32u4 based variants
for example, the uno board needs the standard variant, so his build.variant variable is set to:
[.....]
uno.build.core=arduino
uno.build.variant=standard
[.....]
another example: the leonardo board needs the leonardo variant:
[.....]
leonardo.build.core=arduino
leonardo.build.variant=leonardo
[.....]
In any case the contents of the selected variant folder are compiled and the folder path is added to the include search path before the core folder (this means that if the same include file is present in both core folder and variant folder the variant folder has priority).
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 as for the compilers.
Tools are configured inside the platform.txt file. Every Tool is identified by a short name, the Tool ID, and its configuration is done through variable whose name starts with tool.ToolID prefix.
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:
[....]
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).
Let's look how the upload action is defined for avrdude:
tools.avrdude.cmd.path={runtime.ide.path}/hardware/tools/avr/bin/avrdude
tools.avrdude.config.path={runtime.ide.path}/hardware/tools/avr/etc/avrdude.conf
tools.avrdude.cmd.path.linux={runtime.ide.path}/hardware/tools/avrdude
tools.avrdude.config.path.linux={runtime.ide.path}/hardware/tools/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"
The Arduino IDE makes the tool configuration variables available globally without the prefix, so, for example, the tools.avrdude.cmd.path variable can be used as {cmd.path} inside the recipe, and the same happens for all the other avrdude configuration variables.
The Arduino IDE selects the tool to be used for upload by looking the upload.tool variable. A specific upload.tool variable is defined for every board in boards.txt file:
[......]
uno.upload.tool=avrdude
[......]
leonardo.upload.tool=avrdude
[......]
Also some other upload parameter is defined together, for example in the 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
[.....]
The 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" [.....]
TODO....