IDE 1.0.x board definitions...

Every supported Arduino board has an entry in a file called "boards.txt" which is found in the "arduino" folder of your IDE's environment. The "boards.txt" entries tell the IDE everything it needs to know about the AVR device which is used on the board in question. Notice that I said AVR device and not board! The IDE doesn't actually care what board the AVR is on, the board type is for our sake to make our lives a little less complicated.

Because the AVR device is what is actually specified we can add AVR devices to the "boards.txt" file that have nothing to do with any Arduino board. The table below shows the original Arduino UNO entry in "boards.txt" and an entry for an ATmega328 which is not used in any Arduino board.

The original Arduino UNO board definition A definitions for an ATmega328 without a bootloader. The * character is for the note below, it is NOT incluced in the boards.txt definition
uno.name=Arduino Uno
# Upload
uno.upload.maximum_size=32256
uno.upload.protocol=arduino
uno.upload.speed=115200
# Bootload
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
# Build
uno.build.mcu=atmega328p
uno.build.f_cpu=16000000L
uno.build.core=arduino:arduino
uno.build.variant=standard
atmega328-8n.name=ATmega328 (8MHz - Without Bootloader - No BOD)
# Upload
atmega328-8n.upload.maximum_size=32768
atmega328-8n.upload.using=arduino:arduinoisp*
#atmega328-8n.upload.protocol=stk500v1*
#atmega328-8n.upload.speed=19200*
# Bootload
atmega328-8n.bootloader.low_fuses=0xE2
atmega328-8n.bootloader.high_fuses=0xDA
atmega328-8n.bootloader.extended_fuses=0x07
#atmega328-8n.bootloader.path=atmega
#atmega328-8n.bootloader.file=
#atmega328-8n.bootloader.unlock_bits=0x3F
#atmega328-8n.bootloader.lock_bits=0x3F
# Build
atmega328-8n.build.mcu=atmega328p
atmega328-8n.build.f_cpu=8000000L
atmega328-8n.build.core=arduino:arduino
atmega328-8n.build.variant=atmega328-22

The "#" character is the same as the "//" in C/C++ and it "comments-out" the following text. In the ATmega328 example above, you will see a number of lines starting with "#" which makes these lines redundant. They have only been included for completeness.

* An external programmer (e.g. "upload.using=arduino:arduinoisp") can be specified using the programmer "name" in the "programmers.txt" file. If this option is chosen, the "upload.protocol=" and "upload.speed=" entries MUST be commented out. If you do not do this, the "upload.protocol=" and "upload.speed=" entries will override the "upload.using=" entry. If "upload.using=" is used, the "Upload" button on the IDE will function exactly the same as the "Upload using programmer" selection from the "File" menu.

If you choose to use "upload.protocol=" and "upload.speed=", only the "Upload using programmer" menu item will work correctly. This is because the default action of the IDE "Upload" button is to upload using a bootloader and to this end, the IDE inserts a "-D" command into the AVRDUDE command line which prevents the erasure of the Flash memory. This is fine when a bootloader is being used as the bootloader is programming the code into Flash but, if an external programmer is specified, the Flash must be erased before the code is programmed.

For example, the "uno" board definition only uses "upload.protocol=arduino" and "upload.speed=115200" because this definition is for use with a bootloader. "arduino" is a default protocol for serial uploading to a bootloader.

"arduino:" is a pointer to the Arduino environment. If you do not specify "arduino:" before an entry for a core, bootloader or variants file, for example, the IDE will look for it in your "Projects" folder first. If you specify "arduino:" the IDE will only look in the Arduino IDE environment.

OK, let's have a look at the entries and see what they do. I have split then entries into sections, Upload, Bootload and Build to make things simpler:

"# Upload": The upload section tells the IDE how to "upload" a sketch to the target AVR device. If the target AVR has a serial bootloader installed, the protocol is "arduino" (Serial Upload). If there is no bootloader, the protocol will be whatever the external programmer uses. In the example above, the ArduinoISP_Multi sketch on an Arduino UNO is the programmer so we use "stk500v1" protocol. The final entry is the speed that we need to use to communicate with the target AVR device or programmer. If the "upload.protocol" is an "STK" protocol, the "Upload" button on the IDE will override the selected programmer anyway.

Please see the notes above for the "upload.using=" entry.

"# Bootload": This section defines how we install a bootloader onto the target AVR device. This is always going to be done using a programmer so none of the "Upload" information applies here. The programmer type will be the one you, the user, selects from the IDE menu. During bootloading the fuses and lock bits set/reset and the bootloader hex file is programmed onto the device.

"# Build": These entries tell the IDE necessary information for compiling the sketches for this AVR device:

build.mcu=atmega328p - the MCU(AVR) type

uno.build.f_cpu=16000000L- the clock speed it will run at (This does NOT define the AVR clock speed, it is simply a reference to what the clock speed is set to by the fuses)

uno.build.core=arduino:arduino - the core files to be used during compiling

uno.build.variant=standard - the pin arrangement for the board/AVR. The "standard" entry is for the Arduino UNO pin arrangement (20 x I/O pins). The "atmega328-22" is for 8MHz AVRs where the crystal pins become additional I/O pins (22 x I/O pins).

If you compare the 2 definitions above it is quite easy to see where changes have been made. If "upload.protocol" = arduino the Serial Interface will be used. If "upload.protocol" = anything else the corresponding protocol will be used with an external programmer.

The observant among you will have noticed that the "ATmega328" definition still uses the "build.mcu" type atmega328p which would normally bring up an error with an external programmer, or for that matter, the IDE but the ArduinoISP_Multi sketch takes care of this problem with the ArduinoISP option. See Chapter 15 for workarounds.

The only difficult thing about creating your own board definitions is making sure that your facts are facts. Fuses are the biggest stumbling block and no one can configure fuse settings without thoroughly reading and understanding the "Fuses" section of the AVR's data sheet. You may get away with the odd, small error but be warned!

Warning SignIf you accidentally set the "RSTDISBL" fuse, you will "brick" your AVR and only a High Voltage Proframmer will "un-brick" it. "RSTDISBL" or "RESET DISABLE" does just that, it disables the RESET pin and without it you will not be able to upload or program the AVR. As tempting as it may seem to, for instance, try to use the RESET pin on an ATtiny85 as a 6th I/O pin, DON'T DO IT!

Do your research and if you want to use a bootloader make sure it is the one for your chosen implementation. Most serious AVR programmers don't use bootloaders and write the code to the start of the Flash memory thus gaining extra program space and doing away with the start-up delay when the bootloader runs.

If you are using a "virgin AVR" i.e. one that has never been used before, the "lock" fuses are all disabled so, unless you have a particular need to protect areas of Flash memory such as bootloader code, there is no need to set the "lock" fuse bits.

By the way, "unlock" and "lock" bits are the same fuses, they are presented separately as the "unlock" bits are set/reset prior to programming and then the "lock" bits are set/rest when programming has finished. By programming, we mean bootloading but bootloading without a bootloader is used to set/reset the fuses.

See Chapter 5 for where to put your board definitions.