The Arduino IDE files...

When the Arduino IDE is started it builds an inventory of all the platforms, boards, libraries and sketches it finds within the Arduino environment. The Arduino environment is basically all the folders and files that the IDE is aware of and can include external files and folders if they are specified in the "Preferences" window. The inventory lets the IDE know where everything resides which is very important as the IDE has to tell other applications such as the compiler and AVRDUDE where files can be found.

"hardware",  "libraries" and "sketches" are the three folders that are of most interest to the user but we'll leave "sketches" for now. The "libraries" folder contains all the libraries shipped with the IDE and no additional libraries should be added to this folder by the user!

Platforms...

I would like to introduce the concept of the "Platform" which is the definition that Arduino have given to a collection of files and folders supporting a specific device or hardware. Platforms are contained in the "hardware" folder of the IDE installation as shown below where the default Platform is "arduino".

C:\arduino-1.6.x  
hardware  
arduino   // The Platform Type for Arduino boards
avr   // The Processor Type
bootloaders   // The actual HEX files programmed onto the device during "Burn Bootloader"
cores   // The basic header and cpp files included by default during compiling such as Arduino.h
firmwares   // Specific firmware files for peripherals such as the USB USART (ATmega8U2/16U2) on the Arduino board
variants   // Specific device configuration data for mapping actual MCU pins to Digital I/O pins
boards.txt   // Configuration data for board types. Specifies protocols, programmers, bootloaders, baud rates etc.
platform.txt   // Describes the type of micro-controllers/boards and defines how the IDE should deal with them
programmers.txt   // Configuration data for programmer types. Specifies protocols, programmer types, baud rates etc.

The "arduino" folder contains a processor type sub folder called "avr" which itself contains all the data that defines the range of Arduino boards such as the UNO and MEGA2650 that use the ATmel AVR range of processors. Put simply, the "arduino" folder contains Arduino related definitions and the micro-controller type is specified by the "avr" folder. Prior to IDE 1.5.0, the "avr" folder did not exist as no distinction was made within the IDE folders as to the MCU type. The folders within the "avr" folder were simply under the "arduino" folder.

IDE 1.5.0 onwards allowed the definition of separate Platforms as the next example shows where a Platform for the ATmega1284 has been added:

C:\arduino-1.6.x  
hardware  
arduino   // The Platform Type for Arduino boards
    atmega1284   // The Platform Type for the ATmega1284 MCU which is not included with the Arduino definitions
avr   // The MCU Type
bootloaders   // The actual HEX files programmed onto the device during "Burn Bootloader"
cores   // The basic header and cpp files included by default during compiling such as Arduino.h
variants   // Specific device configuration data for mapping actual MCU pins to Digital I/O pins
boards.txt   // Configuration data for board types. Specifies protocols, programmers, bootloaders, baud rates etc.
platform.txt   // Describes the type of micro-controllers/boards and defines how the IDE should deal with them

Please Note: The ATmega1284 Platform does not include a "firmware" folder or "programmers.txt" file because these are already present in the "arduino" Platform folder. Only files and definitions specific to the ATmega1284 MCU are included in the Platform definitions.

Board/AVR definitions in other platforms that make use of the standard "arduino" cores can specify them within the "boards.txt" file by simply adding the platform/core like this: "uno328.build.core=arduino:arduino". The "arduino:" segment says "use this core from this platform".

Sketches and Libraries...

As previously discussed, a folder called "sketches" is created in the "portable" folder of the Arduino environment and it is here that user sketches will be saved. The built-in sketches such as "Blink" are within the folder called "examples" in the Arduino environment. The user "sketches" folder also contains a folder called "libraries" and it is here that the user can save any downloaded libraries. We will look at another way to store sketches and libraries later.

C:\arduino-1.6.x  
portable  
sketches   // The user's Sketches are saved here
      libraries   // The user's download Libraries are saved here
      preferences.txt   // The application Preferences file

The files that the IDE uses...

Warning Sign
Do not make any changes to the boards.txt file entries unless you are sure that you realise the implications. This is especially true for the Fuse entries as an error could render the MCU device unusable!

The IDE makes use of certain files to define what it should do and how it should do its job. The most interesting of these files is the "boards.txt" file which is specific to each Platform. Here is the boards.txt entry for the Arduino/Genuino UNO board which is located in the "arduino/avr" folder:

uno.name=Arduino/Genuino Uno> The name of this unique board entry that will be shown in the selection menu
uno.vid.0=0x2341 These entries are specific to Arduino boards using USB UART devices and allow the IDE to recognise genuine Vendor and Hardware. They can be ignored if you are creating your own AVR definitions.
uno.pid.0=0x0043
uno.vid.1=0x2341
uno.pid.1=0x0001
uno.vid.2=0x2A03
uno.pid.2=0x0043
uno.vid.3=0x2341
uno.pid.3=0x0243
#UPLOAD  
uno.upload.tool=avrdude The "tool" to use when uploading a sketch
uno.upload.protocol=arduino The protocol to use when uploading a sketch
uno.upload.maximum_size=32256 The maximum size of the upload to the board (Flash memory size - bootloader size)
uno.upload.maximum_data_size=2048 The size of the SRAM installed on the target device
uno.upload.speed=115200 The baud rate to use when communicating to the board using AVRDUDE
#BOOTLOAD  
uno.bootloader.tool=avrdude The "tool" to use when burning a bootloader
uno.bootloader.low_fuses=0xFF The byte to write to the low fuses of the microcontroller when burning the bootloader
uno.bootloader.high_fuses=0xDE The byte to write to the high fuses of the microcontroller when burning the bootloader
uno.bootloader.extended_fuses=0xFD The byte to write to the extended fuses
uno.bootloader.unlock_bits=0x3F The byte to write to the lock fuses of the microcontroller to unlock it before burning the bootloader
uno.bootloader.lock_bits=0x0F The byte to write to the lock fuses of the microcontroller to lock it after burning the bootloader
uno.bootloader.file=optiboot/optiboot_atmega328.hex The "bootloader" file to use including the Path to its location. If left blank, only the Fuses will be set/reset
#BUILD  
uno.build.mcu=atmega328p The microcontroller on the board (e.g. "atmega328" or "atmega1280")
uno.build.f_cpu=16000000L The clock speed at which the microcontroller operates, in Hertz
uno.build.board=AVR_UNO This property is used to set a compile-time variable ARDUINO_{build.board} to allow use of conditional code between #ifdefs
uno.build.core=arduino The location of the core to link sketches against when compiling for the board
uno.build.variant=standard The folder under the 'hardware/arduino' path where the compiler will search for the pins_arduino.h file

Each entry in "boards.txt" has a unique name which is the first part of each line before the first full stop (uno in the example).

The "programmers.txt" file entry example:

ArduinoISP Programmer Definition Description
arduinoasisp.name=Arduino as ISP The name of the definition "arduinoasisp" is used to prefix all entries
arduinoasisp.communication=serial The interface used to communicate with the progammer
arduinoasisp.protocol=stk500v1 The protocol to use when communicating with the programmer
arduinoasisp.speed=19200 The baud rate to use when communicating with the programmer
arduinoasisp.program.protocol=stk500v1 The protocol used when creating the AVRDUDE command line
arduinoasisp.program.speed=19200 The baud rate used when creating the AVRDUDE command line
arduinoasisp.program.tool=avrdude The programming tool used when creating the AVRDUDE command line
arduinoasisp.program.extra_params=-P{serial.port} -b{program.speed} Additional parameters for the AVRDUDE command line

As you can see, the entries in the programmers.txt file are very simple and just provide the basic information for the purpose. Also note the similarity to the boards.txt file definitions.

Platform.txt...

The "platform.txt" file looks (and is) quite complex when first viewed. There is no need to go into detail about this file but it is worth knowing what it is for. When the IDE is commanded to compile or program a device it has to communicate with the compiler and AVRDUDE using command line commands.Prior to IDE 1.5.0 the IDE core application took care of If your Preferences are set to allow verbose output during uploading you will see the multiple command lines, here are the first three:

C:\arduino-1.0.6\hardware\tools\avr\bin\avr-g++ -c -g -Os -Wall -fno-exceptions -ffunction-sections -fdata-sections -mmcu=atmega328p -DF_CPU=16000000L -MMD -DUSB_VID=null -DUSB_PID=null -DARDUINO=106 -IC:\arduino-1.0.6\hardware\arduino\cores\arduino -IC:\arduino-1.0.6\hardware\arduino\variants\standard C:\arduino-1.0.6\build\Blink13.cpp -o

C:\arduino-1.0.6\build\Blink13.cpp.o

C:\arduino-1.0.6\hardware\tools\avr\bin\avr-gcc -c -g -Os -Wall -ffunction-sections -fdata-sections -mmcu=atmega328p -DF_CPU=16000000L -MMD -DUSB_VID=null -DUSB_PID=null -DARDUINO=106 -IC:\arduino-1.0.6\hardware\arduino\cores\arduino -IC:\arduino-1.0.6\hardware\arduino\variants\standard

"platform.txt" contains "recipes" which describe and provide templates for a multitude of operations to control the compilation process. Once the sketch is compiled and a HEX (binary) file is generated, "tools" define how the code is uploaded or burnt to the AVR device.

The "HEX" file uses the Intel Hex format and is actually a text file. If you open a Hex file you will see something like this:

:107800000C94343C0C94513C0C94513C0C94513CE1
:107810000C94513C0C94513C0C94513C0C94513CB4
:107820000C94513C0C94513C0C94513C0C94513CA4
:107830000C94513C0C94513C0C94513C0C94513C94
:107840000C94513C0C94513C0C94513C0C94513C84
:107850000C94513C0C94513C0C94513C0C94513C74
:107860000C94513C0C94513C11241FBECFEFD8E036
:10787000DEBFCDBF11E0A0E0B1E0EAE8FFE702C063
:1078800005900D92A230B107D9F712E0A2E0B1E065
:1078900001C01D92AD30B107E1F70E942D3D0C945F
:1078A000C33F0C94003C982F95959595959595958B
:1078B000905D8F708A307CF0282F295A8091C0000B

Each line contains specific information which is used to determine where in the MCU's Flash memory the data will be placed and how much data is to be placed. Here is a break-down of the first line of the code above:

Start
Mark
Data
Count
(16)
Address
(0x7800)
Data
Type
Data Checksum
: 10 7800 00 C94343C0C94513C0C94513C0C94513C E1

The example is actually part of a bootloader file for the ATmega328. Each line contains 16 Bytes of actual data and it is to be placed in Flash memory starting at address 0x7800 which is the upper area of Flash memory reserved for bootloader code. More on this later!

Here is an example of the command line sent to AVRDUDE to upload a sketch called "Blink13" which the compiler has converted into a file called "Bilnk13.cpp.hex"

C:\arduino-1.0.6\hardware/tools/avr/bin/avrdude -CC:\arduino-1.0.6\hardware/tools/avr/etc/avrdude.conf -v -v -v -v -patmega328p -carduino -P\\.\COM3 -b115200 -D -Uflash:w:C:\arduino-1.0.6\build\Blink13.cpp.hex:i

Prior to IDE 1.5.0, the above command lines were generated totally within the IDE application and were fixed in their format. The "platform.txt" file was introduced to allow the command lines to be customised which was necessary for the IDE to be able to handle MCUs other than the AVR. The "platform.txt" file also allows the definition of "tools" to assist with uploading/programming. Take a look at the "platform.txt" file and see what it controls/defines.

Please Note: The "Upload Using Programmer" option in the "Sketch" menu still appears to use the original built-in command line format and it cannot be overridden in "platfrom.txt". This also applies when the "Upload" button is designated for use with a programmer (more on this later).

Workman