New user: "board descriptor file" - where?

Community Project Hub
1

Greetings,

New user, first post. Sorry for this if it's covered elsewhere. I would like to find the board configuration file for the nano, pro mini, and other boards.

I ask because I just tried the blink example program. In it it uses the constant LED_BUILTIN, and says "To make your life easier, we have a constant that is specified in every board descriptor file. This constant is LED_BUILTIN and allows you to control the built-in LED easily."

So, I'd like to see what other constants are defined there, and what else if contains. But I've searched and can't find it anywhere.

Where can I find these files?

Thanks,

jv

2

The term "board descriptor file" is not one we ever use in the Arduino world. The code you're looking for is in the "variant" files.

Here's how you can find the variant file for any board:

The first thing you need to do is locate the board's platform folder. The easiest way to do that is as follows:

  • Select a board from the hardware package you want to find from the Tools > Board menu
  • File > Examples > SPI > BarometricPressureSensor (or any other SPI example sketch)
  • Sketch > Show Sketch Folder
  • Move up folder levels until you reach the one that contains boards.txt

The next thing you need to do is find which variant your board uses. That is defined in boards.txt:

Open boards.txt in a text editor.

Find the section containing the configuration for the board you're interested in. For example, the Uno's section looks like this:

uno.name=Arduino Uno

uno.vid.0=0x2341
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

uno.upload.tool=avrdude
uno.upload.protocol=arduino
uno.upload.maximum_size=32256
uno.upload.maximum_data_size=2048
uno.upload.speed=115200

uno.bootloader.tool=avrdude
uno.bootloader.low_fuses=0xFF
uno.bootloader.high_fuses=0xDE
uno.bootloader.extended_fuses=0xFD
uno.bootloader.unlock_bits=0x3F
uno.bootloader.lock_bits=0x0F
uno.bootloader.file=optiboot/optiboot_atmega328.hex

uno.build.mcu=atmega328p
uno.build.f_cpu=16000000L
uno.build.board=AVR_UNO
uno.build.core=arduino
uno.build.variant=standard

Find the build.variant property of the board. For the Uno it is here:

uno.build.variant=standard

so you can see that the Uno uses the standard variant.

Now you need to find the variant. The variants are located under the variants subfolder of the platform folder. The variant name is defined by the folder name. So for the Uno you would look in the variants/standard folder.

The traditional location for the declarations of each variant is the pins_arduino.h file. That is where you would typically find the definition of LED_BUILTIN, etc. In some platforms, you will find that pins_arduino.h only contains this:

#include "variant.h"

and the declarations are located in variant.h instead.

The Nano and Pro Mini use the eightanaloginputs variant, but you'll find that that variant's pins_arduino.h file looks like this:

#include "../standard/pins_arduino.h"
#undef NUM_ANALOG_INPUTS
#define NUM_ANALOG_INPUTS           8

So you can see that the eightanaloginputs variant is identical to the standard variant, with the exception that the NUM_ANALOG_INPUTS macro is defined as 8 instead of 6.

In some 3rd party platforms, you might find something that looks like this:

someboard.build.variant:arduino:standard

This is using a cool feature that allows platforms to reference the variants of other platforms. So instead of the 3rd party platform needing to duplicate the variant code from another platform, it can just tell the Arduino IDE "get it from that other platform". More information on that here:
https://arduino.github.io/arduino-cli/platform-specification/#referencing-another-core-variant-or-tool

3

Wow, thank you so much for the quick and detailed reply! I'm stoked. Funny, I found the term "board descriptor file" here: https://www.arduino.cc/en/tutorial/blink which contains the sentence "To make your life easier, we have a constant that is specified in every board descriptor file."

Your explanation is precise and comprehensive, and I thank you!

jv

4

You're welcome. I'm glad if I was able to be of assistance.

I did see that in the Blink tutorial. If you do a search for: "board descriptor" arduino, you mostly just get that page and clones of that page. The other results use the term to refer to multiple different things. If you look at the definitive reference on this subject, the Arduino Platform Specification, there is no mention of "board descriptor file", nor anything close to that term.

It's very unfortunate that we have this meaningless technical jargon on our most important tutorial; the one most people start with. This is the sort of thing that has traditionally made the learning curve unnecessarily steep. Someone already knowledgeable in the subject could make a reasonable guess about what the term means, but a beginner who is already confused and overwhelmed would not, and then would be frustrated when even a Google search doesn't provide any help in understanding. Even with the correct terminology, I would prefer that the tutorial avoided mentioning this subject directly, since it's not something a beginner needs to think about. All a beginner needs to know is that LED_BUILTIN is the pin number of the built in LED.