[HOWTO:] Anatomy of the boards.txt file for custom boards

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.

I decided to put together a post explaining how the boards.txt files work in the Arduino environment. This will help with a ton of questions people have when trying to use a different micro or building their own boards. It isn't complete and there are some areas that I am not 100% sure on, so I would appreciate some help to finish it and verify it.

Once we get it right, it should be stickyed in this forum (in my opinion.)

I also plan to write up some more tutorials on building a custom bootloader (well, modifying an existing one, actually - I'm not THAT smart), variants, cores, and whole-other platforms (like ARM, PIC, CHIPKIT etc...)

You might want to point out that the only supported values for F_CPU are 20000000UL, 16000000UL, and 8000000UL, The 20 MHz millis() clock will be slow by 0.4% due to truncation errors. Support for 20 MHz was only added around V1.0.

I found the list of supported devices. The names do not match. Arduino must be translating the names somehow... hmm...

They do match avr-gcc names, though:
http://www.nongnu.org/avr-libc/user-manual/using_tools.html

johnwasser:
You might want to point out that the only supported values for F_CPU are 20000000UL, 16000000UL, and 8000000UL, The 20 MHz millis() clock will be slow by 0.4% due to truncation errors. Support for 20 MHz was only added around V1.0.

Good point. I will add it.

When I go into the tutorial on modifying and creating custom cores, this could be addressed there, right?

the optiboot bootloader is 512K instead of 1M, but if you didn't change this number, the IDE will not use the extra 512K.

Snerk! Off by three orders of magnitude...

westfw:

the optiboot bootloader is 512K instead of 1M, but if you didn't change this number, the IDE will not use the extra 512K.

Snerk! Off by three orders of magnitude...

I am? How so? Definitely offer corrections if I made a mistake!

atmega328bb.bootloader.*

I'd point out that these are only relevant if you ever intend to use the "burn bootloader" command in the IDE.
I can imagine a third-party board that requires some incompatible procedure for burning the bootloader (say, PICKit?), that nevertheless uses boards.txt info for compile/upload. They might omit these...

You might want to point out that the only supported values for F_CPU are 20000000UL, 16000000UL, and 8000000UL

Platform and implementation dependent. I bet Due supports other clock speeds. So does Teensy3. I could release an XMega Arduino whose core supported random clock rates. Or a modified core for Uno that supports other clock rates.

atmega328bb.build.core=arduino // These are located in the arduino/hardware/arduino/cores folder.
atmega328bb.build.variant=standard // It points to a folder in the arduino/hardware/arduino/variants folder

These are the annoying ones at the moment, because it's not clear WHICH hardware directory is the base for finding the core or variant. There are about two possible location for boards.txt: /hardware/arduino/boards.txt and /hardware//boards.txt (I could swear that /hardware/boards.txt worked at one time, but I can't get it to work now.) Things are set up so that that an added extension can provide its own core and variant directories (for an entirely different board or processor), or use the ones from the Arduino install (if there are minor changes like a new clock speed.) But I think that the exact behavior has been changing. Where you used to be able to say "core=arduino" to get the core from the Arduino install, in later versions you need to say "core=arduino:arduino", or something like that...

Off by three orders of magnitude...

I am? How so? Definitely offer corrections if I made a mistake!

Should be "512Bytes instead of 2KBytes ... extra 1536 Bytes." (for optiboot on Uno vs atmegaboot on Duemilanove. Other cpu/bootloader combinations will have slightly different differences.)

Westfw, thank you! I am not expert, but what I have learned was from lots of experimentation. I definitely appreciate feedback, corrections, and input. Obviously, it is useless if it isn't accurate!

I have not seen the arduino:arduino thing. Is this in 1.5.2? Probably to support the Due (ARM controller) since I don't see how the version I am using could support it as-is. I noticed that there wasn't a realistic way to create a different platform without creating an entirely custom version of the IDE. I'll have to investigate the newer IDE a bit. I have been using only 1.0.3

I have never seen an example of the boards.txt file in the usersketch folder. I guess it makes sense though, since make will search different folders for includes and typically includes the one most local to the program. I wouldn't be surprised if you could simply put arduino_pins.h right in your sketch folder and include it directly in your program. I don't see an advantage of detailing how to do that. I don't think there is a difference really (well, unless you did something like having two different versions of the files in two locations.) And THAT is why I am not sure it would be a good idea to demonstrate it. Too easy to screw something up, when the normal location inside the install/hardware/arduino folder is better (IMO)

I'll make the corrections regarding the bootloader. Thanks again!

BTW, is my statement true that the IDE would not be able to use the bytes saved by the optiboot? Would it actually refuse to compile, or would it do it, upload it, but just warn you? I've never written code that took up the entire memory or got that close to know for sure how it would behave.

Retroplayer:
BTW, is my statement true that the IDE would not be able to use the bytes saved by the optiboot? Would it actually refuse to compile, or would it do it, upload it, but just warn you? I've never written code that took up the entire memory or got that close to know for sure how it would behave.

Doesn't the board.txt uplode.maximum entry for the selected board entry dictate to the compiler the available flash memory?

Uno:
uno.upload.maximum_size=32256
Duemilanove:
atmega328.upload.maximum_size=30720

Lefty

Yes, but I am not sure if it would simply generate a warning (if it were set too low for example) or would compile and upload anyway.

The difference between the duemilanove and Uno is that the Uno used the optiboot bootloader and the Duemilanove uses the old arduino bootloader. That is the difference between the two maximums. Let's say you made a board, and put the optiboot bootloader in it, but copied your boards.txt entry from the duemilanove. You would actually have more more memory avaiable for code.

What I don't know is if the IDE would actually just upload it anyway (but warn about it.) I suppose I just test it by changing boards.txt some ridiculously low number and see what happens.

I tried it. It won't compile. It spits out this:

Binary sketch size: 13,504 bytes (of a 8,192 byte maximum)
processing.app.debug.RunnerException: Sketch too big; see http://www.arduino.cc/en/Guide/Troubleshooting#size for tips on reducing it.
	at processing.app.Sketch.size(Sketch.java:1658)
	at processing.app.Sketch.build(Sketch.java:1591)
	at processing.app.Sketch.exportApplet(Sketch.java:1613)
	at processing.app.Sketch.exportApplet(Sketch.java:1599)
	at processing.app.Editor$DefaultExportHandler.run(Editor.java:2380)
	at java.lang.Thread.run(Thread.java:619)

I changed the max size to 8192 in my entry for the atmega2560 and tried to upload a sketch I knew was over 10K

I have not seen the arduino:arduino thing. Is this in 1.5.2?

I have a bunch of optiboot variants defined in ~billw/Arduino/hardware/optiboot-extensions/boards.txt
That directory contains no other files or sub-directories; the new "boards" are supposed to exactly parallel the existing boards.txt, but assume that everything has optiboot rather than (whatever.)
It's full of lines like:

atmega1284o.build.core=arduino:arduino
atmega1284o.build.variant=arduino:standard

It seems to work correctly with 0022, 1.0 and 1.0.2, but NOT with 1.5.2 (sigh.)
If I leave out the colons:

atmega8x.build.core=arduino
atmega8x.build.variant=standard

I get build errors when it can't find arduino.h (or WProgram.h in 0022, I guess.)

being about to add boards without modifying the "master" boards.txt is very important, IMO. I'll have to figure out how it works in 1.5.2...

Where can I find those files so that I can look at them and see if I can figure it out and add it to my tutorial?

Here...

boards.txt (8.8 KB)

is there any solution for IDE v1.6.6?

The 1.6.5+ capabilities for 3rd party extensions have better official documentation:

I'm using 1.6.6 now and in my boards.txt I have .build.core=arduino-tiny-841:tiny
and it is using the core from
Program Files (x86)\Arduino\hardware\arduino-tiny-841\avr\cores\tiny
This also worked with the 1.6.5 IDE.

@Retro - did you ever confirm this TODO?

"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!"