How to organise your Arduino IDE...

The following only applies to Arduino IDE 1.5.x onwards:

When the Arduino IDE starts up it creates an inventory of, among other things, what hardware boards and AVR types are supported as well as a list of what libraries are available. This means that any changes such as adding a library or editing an entry in a board definition file will require a restart of the IDE.

By default,, the Arduino IDE stores its sketches, libraries, core files and support applications in what can be termed the "Arduino environment". The "Arduino environment" is contained within a folder called "Arduino-xxxx" which is created when you install the Arduino IDE using the Windows Installer.

On a Windows system, if you have used the "Windows Installer" package the default installation is in the "Program Files" ("Program Files(x86)" on 64bit systems) folder on the "C:\" drive. If you have installed your Arduino IDE in a different location or you have installed the "Windows ZIP file (for non-administrator install)" version you will need to establish where the "Arduino" folder is. Once you have done this, make a note of the location of the "Arduino" folder as this is where the "Arduino environment" resides.

By default, the Windows installer IDE version will create a Projects Folder in "C:\Users\<username>\Documents\Arduino" and it is here that your saved sketches will be saved. A folder called "libraries" is also created within the Projects Folder where you can save any downloaded libraries.

Remember that I am using the "Portable" version in this description!

From now on all references will be to the "Arduino Environment" folder. The simplest, although not the best, way to store your sketches etc. is in the default Arduino folder located in the  "Sketchbook" folder of the "portable" folder).

The Arduino IDE appears, on the surface, to only deal with Arduino Boards but, in truth, the IDE also supports a wide range of AVR and other devices, some that are used on Arduino Boards and many that are not. With a few exceptions, you can use the Arduino IDE with almost all of the AVR devices that you may come across but to show how easy it is to get caught out just try and bootload an ATmel 328 AVR.

There are two versions of the ATmega328, the ATmega328P and the ATmega328. The only difference between them is that the  "P" variant has the "picoPower" hardware for reduced power consumption in sleep mode. Because each AVR device has a unique internal ID, separate definitions are required. The IDE, as shipped, does not provide board defintions for the ATmega328 but, both the Arduino IDE and AVRDUDE DO recognise both the "P" and "non P" variant ID. Prior to IDE 1.5.x, only the "P" variant was recognised.

Uploading using the Serial Port is not affected as the "non P" variant can be treated as a "P" variant and the IDE does not check the ID during normal uploading. It is when bootloading is attempted that AVRDUDE and the IDE will reject the "non P" device. The way around this is to define a separate board definition for the ATmega328 non P variant.

C:\  // The root of your hard drive
Program Files  // The Program Files folder
Arduino  // The "Arduino environment"
drivers  // Driver files
examples  // The example sketches
hardware  // Definitions for board types, core files and programmers etc.  
java  // IDE support files
lib  // IDE support files
libraries  // The libraries for your projects
reference  // Reference files
tools  // Support files
arduino.exe  // The Arduino IDE application
cygiconv-2.dll  // Support file
cygwin1.dll  // Support file
libusb0.dll  // Support file
revisions.txt  // Application specific changes etc.
rxtxSerial.dll  // Support file
uninstall.exe  // The Unistall application

As you can see there's quite a lot in the Arduino folder but luckily we are only interested in the "hardware" and "libraries" folders. The hardware folder contains 2 other folders named "arduino" and "tools" and it is the "arduino" sub-folder that we will be looking at from now on. The "tools" folder is where the compiler resides but this is of no interest at this point in the tutorials..

If you make no changes to the way the Arduino IDE works, your sketches will be saved in the default "Sketchbook location" and any libraries you download to support your sketches will have to be installed in the "libraries" folder of your Arduino environment.

This is a very messy way of doing things and it has some serious pitfalls as any sketches and libraries you install will be mixed in with everything else. If you were to re-install the Arduino IDE all of your files would be overwritten and your downloaded libraries would be lost unless you took the precaution of saving them first. It also can also make the Arduino IDE menus very hard to work with.

Always close the Arduino IDE before making any changes to the configuration files. Changes will only take effect when the IDE is re-started! ALWAYS make a copy of the original file!

Clearing the Unwanted "examples" from the "Open" menu...

If you do not want to see the built-in "example" sketches such as "Blink", you can remove them from the "Open" menu. To do this, close the Arduino IDE if it is open and go to the "examples" folder and rename the folder to "original_examples" or whatever you choose. DO NOT just remove the example sketches from the "examples" folder because the IDE will hang on start-up if it finds an empty "examples" folder. When you re-open the Arduino IDE, all you will see in the "Open" menu will be your sketches.

Tidying up the "Tools/Board" and "Tools/Programmer" menu items:

The "Tools/Board" menu contains all the Arduino board types available for the IDE and it is doubtful that you will need all of them. Decide which boards you will use or are likely to use in the future and edit the definitions 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

Within the "hardware/arduino" folder is a sub-folder named "avr" and within this folder is a text file called "boards.txt". Make a copy of the "boards.txt" file and save it as, for example, "boards.txt.original". Open the "boards.txt" file in a text editor and you will see all the board definitions that you see when you select a boards from the "Tools/Board" menu (an example of a definition is shown on the left. Definitions are separated by a line of "#" characters.

The "#" characters are basically the same as "//" in C++ and indicate that the text after the "#" can be ignored or can be treated as a comment.

Make sure that you do not delete any lines from a definition you are leaving in, just the whole definitions themselves.

Remove any board definitions that you do not want and save the modified boards.txt file. When you open the Arduino IDE, all you will see in the Tools/Board" menu are the entries you left.

Also in the "hardware/arduino/avr" folder is another text file called "programmers.txt". It is worth trimming this file as well as this is the definition file for the programmers that are listed in the "Tools/Programmer" menu. As above, make a backup copy of this file and then edit it to remove any unwanted programmer options.

If you make a mistake you can always start-over using the backup copies you made earlier. You did make the backups didn't you?

Properly organising your sketches and libraries:

I strongly recommend that you create a separate "Projects" folder or "Sketchbook location" as Arduino call it. This is a simple job and allows you to completely separate your sketches and libraries from the Arduino IDE environment. At a later stage we will look at another use for a separate Projects folder. I have my "Projects" folder on a Cloud Drive which is backed-up regularly so, the sketches and libraries that I have created/saved should be safe, I hope!

To create a Projects folder or "Sketchbook location", open the Arduino IDE and select "File/Preferences" which will open a window like this:

Preferences Window

Decide on a location for your Projects folder which will be easy to find and backup. I also follow the Arduino convention and separate the filenames with the "_" character so, as in my example, I have created a folder called "Arduino_Projects" on my local D:\ drive in my Dropbox folder.

Create your Projects folder and then, in the "Sketchbook location" text box, click the "Browse" button and navigate to the folder you created and select it. Click "OK" in the Preferences window and you will find that the Arduino IDE has created a folder called "libraries" in your new Projects folder. Are you getting the idea now?

At this point it is worth creating another folder in your Projects folder called "hardware" for later development. It isn't necessary unless you want to move on to working with other AVR types not covered by the IDE.

Close and re-open the Arduino IDE and, from now on, your sketches will be saved to your new Projects folder. If you have any existing sketches somewhere else, move them to your Projects folder. Remember that your sketches must be within a sub-folder of the same name for the IDE to recognise them. The "libraries" folder in your Projects folder is for any libraries that you download from the Internet and they will be separate from the Arduino libraries.

You can sub-divide your sketches into categories if you want to by placing your related sketches into folders. For example, I do a lot of development work on a variety of hardware devices so, all my RTC sketches go in a folder called "RTC_Sketches" and my Stepper Motor sketches go in a folder called "Stepper_Motor_Sketches" and so on. It makes finding and organising your sketches easy.

D:\Dropbox\Arduino_Projects  // The Projects folder
hardware  // create this folder for later
libraries  // Where you put your libraries
RTC_Sketches  // An example sketch category folder   
RTC_Sketch_1  // Sketch folder
RTC_Sketch_1.ino      // Sketch .ino file
RTC_Sketch_2
RTC_Sketch_2.ino  

The tree above is an example of what we've been talking about. If you only ever intend to work with "off the shelf" Arduino boards, such as the UNO, you really don't need to do much more. Just remember to put new, downloaded, libraries into the "libraries" folder in your "Projects" folder and save all your sketches in your "Projects" folder. However, if you want to get into programming AVR devices, writing your own libraries, using alternative programming tools etc. there is a lot more to learn. Don't be put off, it is actually quite easy once you understand the way the IDE works.

When the Arduino IDE starts up, it looks in specific locations for files it will need to enable it to work. One of these locations is the "Projects" folder you have specified in "Preferences". The IDE also expects to see, as a minimum, a "libraries"  folder in your "Projects" folder but, if it is not there, it will ignore it. The IDE also lists any sketches in your "Projects" folder in the "Open" file list on the IDE.

Whilst the IDE is looking in the expected folders, the IDE gathers specific files which contain information vital to the IDE's function. These files are as follows;

boards.txt Definitions of the board types, their programming needs, bootloader files. fuses etc.
platform.txt Rules for compiling and programming boards and AVR devices
preferences.txt Contains all the details of the IDE environment such as the last board type selected and the screen size
programmers.txt Definitions of programming tools such as AVRISP MKII or ArduinoISP

Adding board definitions for AVRs not catered for in the Arduino IDE:

Arduino enthusiasts move on to building their own stand-alone projects using the AVR devices on their own. This, in a lot of cases, requires new entries in the "boards.txt" file discussed above but, it is not necessary to add entries to the original "boards.txt" file in the IDE environment as we can create as many new "boards.txt" files as we wish to and the IDE will find them and collate them into one list for us.

Let's go back to the "hardware" folder it was suggested you create in your "Projects" folder. Within this folder we can create new sub-folders containing only those details pertaining to a particular AVR device type. For example, let's say we want to start working with ATtiny AVR devices, all we need to do is create a sub-folder in the "Projects/hardware" folder called, for instance, "attiny". Within this folder we can create an environment similar to that which exists within the Arduino IDE environment like this:

D:\Dropbox\Arduino_Projects   
  hardware
  attiny
      avr  
    cores  
    variants  
   boards.txt    
  atmega328
        avr  
     bootloaders    
     cores  
     variants  
     boards.txt  

As there are specific "core" files available for the ATtiny AVRs we can put these in the "cores" folder and the same goes for "variant" files if applicable. The "boards.txt" file will contain definitions for the required ATtiny AVR devices only. The IDE adds these definitions to those already entered in the IDE's "boards.txt" file so we end up with a "Tools/Board" menu list in the IDE containing Arduino boards and ATtiny AVRs. The same can be done for other AVRs such as the ATmega328 so we could create another sub-folder as shown on the left containing the bootloader, cores and variants folders as well as another "boards.txt" file defining ATmega328 devices and variants.

The only warning I would give at this point is DO NOT use a name for a device sub-folder that clashes with a folder name in the Arduino IDE environment.. For example I could have called my ATmega328 folder "atmega" but a folder with this name already exists within the IDE. This is just good practice!

You don't have to include folders such as "bootloader" and "cores" if they are empty. You could just have a "boards.txt" file in a sub-folder if you wish.

We'll talk about adding board definitions later on.

Workman