Customizing the Arduino IDE

NOTE: Due to a lack of documentation from the developers, MOST of this information has been derived from my hacking experience with the IDE. Please don't hesitate to correct anything you find to be in error.

The Arduino IDE (at least since 1.05) has the wonderful capability of being customizable for new types of hardware. You can add code that supports pin/port assignments or even new kinds of processors (such as the xmega) by re-writing the core libraries and headers and placing them into new directories within the Arduino environment directories.

The 'boards' file "boards.txt"

The most important single file is the 'boards.txt' file, located in the following directory:

{ARDUINO}/hardware/arduino/boards.txt

where '{ARDUINO}' represents the directory into which the Arduino IDE and supporting files have been installed. This may be '/usr/local/arduino' or '/usr/share/arduino' or one of many OTHER possible choices depending on your operating system.

A typical entry for a processor may look as follows:

uno.name=Arduino Uno
uno.upload.protocol=arduino
uno.upload.maximum_size=32256
uno.upload.speed=115200
uno.bootloader.low_fuses=0xff
uno.bootloader.high_fuses=0xde
uno.bootloader.extended_fuses=0x05
uno.bootloader.path=optiboot
uno.bootloader.file=optiboot_atmega328.hex
uno.bootloader.unlock_bits=0x3F
uno.bootloader.lock_bits=0x0F
uno.build.mcu=atmega328p
uno.build.f_cpu=16000000L
uno.build.core=arduino
uno.build.variant=standard

The prefix ('uno' in this case) is unique for a particular board. So if you create a new board, you would write a similar section and add it to 'boards.txt', with 'myboard' (or whatever) in place of 'uno' at the beginning of each string, and modify the description accordingly. Keep in mind that this is COMMON FOR ALL USERS (important for Linux and BSD), most likely requires a privileged user to edit the file, and will probably be overwritten when you update the IDE (so save a backup copy of your changes).

Some of these entries allow you to flash a particular bootloader onto your device. You might want to compile a custom bootloader using the available source. The source and output files are located in:

{ARDUINO}/hardware/arduino/bootloaders

Some of the entries may be obvious, but I'll explain them anyway.

  • name - the name of your board (required)
  • upload.maximum_size - the maximum size of your compiled binary (important)
  • build.mcu - the CPU you build for. This will be the parameter for -mmcu so make sure your compiler knows what that is (in my case I had to patch avr-gcc, avr-binutils, and avr-libc for that particular processor).
  • build.f_cpu - the CPU frequency (in HZ).
  • build.core - the 'core' files for your board. These are in {ARDUINO}/hardware/arduino/cores
  • build.variant - the 'pins_arduino.h' file for your board. These are in {ARDUINO}/hardware/arduino/variants

Custom Libraries

Sometimes you will need to customize a standard library for your own use. Unfortunately this may be due to the fact that, all too often, the libraries don't support your hardware properly, and/or do NOT have the common decency to mark members as 'protected' rather than 'private' (forcing you to edit the library or clone it, rather than creating a derived class). Fortunately, the Arduino IDE allows you to put your own libraries into a user-specific location:

{SKETCHBOOK}/libraries

Where '{SKETCHBOOK}' is the location of your default sketchbook repository (as specified in 'preferences').

The Arduino IDE will look in {SKETCHBOOK}/libraries for matching library names when you '#include' a header file in the main 'INO' (or PDE) file. So you will always need to specify the header file in the main 'INO' file so that the Arduino IDE can locate it (along with any source files).

Additional information about custom libraries can be found here: http://arduino.cc/en/Guide/Libraries

Custom Core and Variants

The {ARDUINO}/hardware/arduino/cores and {ARDUINO}/hardware/arduino/variants trees contain 'core' and 'variant' source and header files that are specific to a particular piece of hardware. As an example,

{ARDUINO}/hardware/arduino/cores/arduino

contains the core library and startup source specific to a standard Arduino, whereas

{ARDUINO}/hardware/arduino/cores/robot

contains the same files but for the 'robot' implementation. You could add your own by 'cloning' the files from a similar project and creating a new directory, such as 'myboard' within the 'cores' directory structure.

Similarly, the {ARDUINO}/hardware/arduino/variants directory tree contains 'pins_arduino.h' files that are specific to a particular piece of hardware. The standard variant is, well, 'standard'. A typical variant that you might use might be 'mega' (for the MEGA2560) or 'eightanaloginputs' (when your project uses an ATmega328 rather than an ATmega328p, as the 328 has 2 additional analog inputs available).

Share