-
-
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 - Definitions of the boards (board's metadata, parameters for building and uploading sketches, etc.)
platform.txt - Definitions for the CPU architecture used on the boards (compiler, build process parameters, tools used for upload, etc.)
programmers.txt - Definitions for external programmers (typically used to burn bootloaders on a blank CPU/board)
Before looking at the content of these file one by one, let's explain the format of these files.
The configuration files are a list of "variable=value" properties. The value of every variable can be expressed using the value of another variable by 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 comments and will be ignored.
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")
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 platform.txt file contains information about a bunch of platform's specific aspects (compilers command line flags, path, system libraries, etc.). In addition it defines also the following meta-data:
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 currently unused but it will be available for future extensions.
The platform.txt file is used to configure the build process performed by the Arduino IDE through a list of recipes. Each recipe specify how to call the compiler or tools for every build step and which parameter should be passed from command line.
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 variables can be built concatenating utility variables set by the IDE for each file:
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.something are taken from the boards.txt, we will look at this later.
The list of files to compile is composed by:
- the user's Sketch
- the selected board's Core
- the Libraries used in the sketch
The selected board's Core is compiled as described in the previous paragraph, but the object files obtained are also archived using the recipe.ar.pattern.
the recipe can be built concatenating the following utility variables set by the IDE for each file:
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 and libraries object files and core.a archive) are linked together using the recipe.c.combine.pattern
the recipe can be built concatenating the following utility 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 and recipe.objcopy.hex.pattern.
There are no specific variables set by the IDE.
AVR platform has the following:
## 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 should match the output part that shows the sketch size.
For AVR we have:
## 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 a 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" and 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 variable uno.name is the extended name of the board that will be shown in the Boards menu of the Arduino IDE. The other variables are used to override the global configuration of the IDE when the use selects the board. The value of these variables will be available in other configuration files (this explains the presence of {build.mcu} or {build.board} in the recipes of platform.txt).
TODO....