Anatomy of boards.txt
First part is a unique identifier. In this case, it is atmega328bb. Notice that all entries will start with that. It can be anything, but it must not have spaces or non-ascii characters.
atmega328bb.name=Atmega328 on a Breadboard //This is the name that will appear in the IDE
atmega328bb.upload.protocol=arduino //The upload protocol is what AVRDUDE will use to program when click upload
atmega328bb.upload.maximum_size=32256 //This is how much space is left in flash after the bootloader
atmega328bb.upload.speed=57600 //The serial upload speed. This is set in your bootloader
atmega328bb.bootloader.low_fuses=0xE3 //The fuses are determined by how the AVR is configured....
atmega328bb.bootloader.high_fuses=0xDE //Use a fuse calculator or the datasheet. Obviously, these must actually be programmed in your chip already.
atmega328bb.bootloader.extended_fuses=0xFF //Here is a fuse calculator: AVR® Fuse Calculator – The Engbedded Blog
atmega328bb.bootloader.path=optiboot //This is location of the bootloader in the Arduino/Hardware/Bootloader folder
atmega328bb.bootloader.file=optiboot_atmega328.hex //This is the actual file in that folder used for the bootloader
atmega328bb.bootloader.unlock_bits=0x3F //See the datasheet for the unlock and lock bits
atmega328bb.bootloader.lock_bits=0x0F
atmega328bb.build.mcu=atmega328p //This is the mcu = parameter used by AVRDUDE. It must match a valid name used by AVRDUDE
atmega328bb.build.f_cpu=8000000L //The speed of your clock. Obviously the part must actually be programmed (using the fuses and bootloader) for this clock
atmega328bb.build.core=arduino //This tells the IDE which core to use. These are located in the arduino/hardware/arduino/cores folder.
atmega328bb.build.variant=standard //This is the "variant" that will be used. It points to a folder in the arduino/hardware/arduino/variants folder
So, let's look at these one by one:
atmega328bb.name=Atmega328 on a Breadboard
When you are in the IDE and you choose the Tools and then Board menu, this is the name that you will see. Make it something easy to identify. BTW, you can rearrang the order that these are listed in by just changing their order in the boards.txt file
atmega328bb.upload.protocol=arduino
This is the bootloader protocol. AVRDUDE will use this to upload your code when you click upload. It must match what your bootloader is actually using and it must match a protocol supported by AVRDUDE. And of course, the name must match exactly.
atmega328bb.upload.maximum_size=32256
This is the maximum size leftover in flash after the bootloader. This is what can be used for code. I have seen these numbers all over the place. If you want the most out of your code, use the correct numbers! For example, the optiboot bootloader is 512 bytes instead of 2K, but if you didn't change this number, the IDE will not use the extra 1536 bytes.
atmega328bb.upload.speed=57600
When you click upload, this is the speed the serial port will be set for to upload. You must have set this speed in your bootloader when you built it (or it must match what the bootloader you are using is set for.) Obviously, faster is better, but there is a limit to what is reliable and different configurations of clock, voltage, length of wires, and things like whether it is on a breadboard or not will affect this.
But again, you can't just change this. Your bootloader must be in agreement with this value.
atmega328bb.bootloader.low_fuses=0xE3 //The fuses are determined by how the AVR is configured....
atmega328bb.bootloader.high_fuses=0xDE //Use a fuse calculator or the datasheet. Obviously, these must actually be programmed in your chip already.
atmega328bb.bootloader.extended_fuses=0xFF
These fuse settings are used when you program by ISP (the ISP method will erase your entire chip, so the bootloader needs to be burned again, too) or choose Burn Bootloader. They are not used by the sketch upload. Make sure they are correct for your configuration. Either get the settings from whoever created the bootloader/board or use a fuse calculator if you are designing your own board and bootloader.
TODO: Verify that these are actually only used when you burn a bootloader. I doubt they are used when you upload a sketch. But verify!
atmega328bb.bootloader.path=optiboot
atmega328bb.bootloader.file=optiboot_atmega328.hex
bootloader.path must match the folder name for where your bootloader is located. This is used when you choose TOOLS||Burn Bootloader.
bootloader.file is the name of the file that will be burned to your chip
atmega328bb.bootloader.unlock_bits=0x3F //See the datasheet for the unlock and lock bits
atmega328bb.bootloader.lock_bits=0x0F
TODO: Find out the best way to explain these
atmega328bb.build.mcu=atmega328p //This is the mcu = parameter used by AVRDUDE. It must match a valid name used by AVRDUDE
atmega328bb.build.f_cpu=8000000L
build.mcu is a parameter used by AVRDUDE to match device signatures and to tell avr-gcc which headers to include from the winAVR toolchain. It must match valid names used by AVRDUDE and avr-gcc and must be spelled correctly. And of course, it must match the actual part that you are using.
TODO: Find a stable place with a list of these
build.f_cpu is used by avr-gcc to build your code properly. It must match the actual clock speed you are using
Also, these two parameters are used by the core, code, and libraries in order to set timers properly or to do conditional compiling where certain chips may have different register names for example. Don't mess with these unless you know what you are doing
atmega328bb.build.core=arduino //This tells the IDE which core to use. These are located in the arduino/hardware/arduino/cores folder.
atmega328bb.build.variant=standard
build.core is which 'core' is used by this board. The core is the main Arduino code which makes things like digitalWrite and AnalogRead actually work. Each one of these statements are actually a call to a function within the Arduino core files. If for some reason you have made modifications to the core files or have added more functions and support, you would create a new folder with your core in it and...
build.core is the name of the folder with your core files in it. This folder is located in arduino/hardware/arduino/cores
build.variant is the folder name that has your arduino_pins.h file in it. Thse are located in the arduino/hardware/arduino/variants folder. This header file describes your chip/board. It maps the different pins to their names used in Arduino. For example, when you refer to A1 (analog pin) the arduino_pins.h file is where A1 is translated into the actual port and pin registers.
Make sure that you are pointing to the correct core and variant folders for your chip/board. And make sure the folder exists in the right location!
That's it so far. There are other functions and parameters that can be added such as settings and parameters for when you choose things such as upload using programmer. These are actually pretty rare in the boards.txt files.
Oh one last bit...
Let's say you download files to support a new board/chip from the web. You need to look at it carefully and understand it before you start throwing files in your hardware folder. First, don't just copy the boards.txt file over. Instead open it and your original boards.txt file, and copy and paste over the entries that you are interested. Otherwise, everytime you do this, you will loose the changes you have already made to the boards.txt file.
I actually keep a file in the hardware folder named boards_master.txt and this is where I collect all the various configurations I have downloaded. The IDE doesn't see this file, so when I need something, I copy it out of that file and into my boards.txt file. I do this because every entry will show up in your boards menu and it can get difficult to quickly locate the board you want to program. I even removed all the original entries for boards I do not own or use. If I ever do need them, they are right there in my master file. I also like to take the board that I am currently using most often and move it up to the top, then the next most often below that. Makes it much easier to select.
