I remember spending countless hours compiling the Linux kernel back in my college days.  That experience helped me develop a taste for command line utilities and the productivity they bring to a developer workflow.  As you expand your horizons experimenting with AVR micro-controllers and Arduino boards, the time will come when you will need to compile the Arduino core libraries for a new or existing board.   The reasons could range from experimenting with a board at different frequencies to using other Atmel micro-controllers. This post covers how to add a new development board to the Arduino Template Express environment and then compile the libraries it supports.  This post is part of the Arduino Template Express (ATE) series. You may also be interested in these other posts:

1. Arduino Template Express – Installation
2. Arduino Template Express – Creating a Sketch
3. Arduino Template Express – Creating a Library
4. Arduino Template Express – Using ATTiny Micro-Controllers

Prerequisite

In order to follow this tutorial you will need to have installed Arduino Template Express (ATE).  You will also need msbuild installed and available in your application path together with a few add-ons.   To install ATE follow the Arduino Template Express – Installation.  Atmel Studio 6.1 is based on Microsoft Visual Studio. My expectation is msbuild 4.0 is installed with Atmel Studio when it installs the dotnet framework, but I cannot verify that is the case because I had Microsoft Visual Studio already installed when I installed Atmel Studio. To check if msbuild is installed open a command window and type the following command.

reg.exe query "HKLM\SOFTWARE\Microsoft\MSBuild\ToolsVersions\4.0" /v MSBuildToolsPath

If reg.exe comes back with unable to find the specified registry key or value, msbuild is not installed.  You will need to download the full Dotnet Framework 4.0 from Microsoft.  You will also need to install the msbuild community task and the msbuild extension pack.

Registering the New Board

Figure 1 contains a list of the libraries and boards supported by  Arduino Template Express (ATE).  For the purpose of this tutorial, I am going to add support for the Arduino Mega 1280 board.

Figure 1 – Supported Libraries

The task of compiling core libraries for a new board requires registration of the board in the boards.xml file and registering a reference to the new board in the project for each library you want compile.  Let’s take care of registering the Mega1280 board first.  Since the Mega2560 and the Mega1280 are very similar boards, I am going to use the entry for the Mega2560 as a model.  Follow these instructions:

1. Locate the directory where ATE is installed.  Typically USER\Documents\Arduino Template Express.  If you are not sure open a command window and type set | find “ATE_HOME”.  It will display the environment variable ATE_HOME which points to the location where ATE is installed.
2. Open %ATE_HOME%\boards.xml with your favorite editor.  Copy the <BoardList> entry for the Mega2560.  In the original file it begins on line 51 and ends on line 71.
3. Paste the entry and make the changes illustrated in listing 1.   I have used the description of the board provided in the Arduino site.

    <BoardList Include="Mega1280" >
        <Processor>ATmega1280</Processor>
        <Location>Mega1280</Location>
        <Variant>mega</Variant>
        <Vid>null</Vid>
        <Pid>null</Pid>
        <SkipFrequencies></SkipFrequencies>
        <SkipLibs></SkipLibs>
        <DefaultProgrammer>Mega1280BootLoader</DefaultProgrammer>
        <EnableForProjects>true</EnableForProjects>
        <EnableForLibCompilation>true</EnableForLibCompilation>
        <DefaultSpeed>16</DefaultSpeed>
        <BitmapName>external.mega1280</BitmapName>
        <DataPort>COM5</DataPort> <!-- Use the port supported in your environment -->
       <SupportedFrequencies>16</SupportedFrequencies>
       <Description>
       The Arduino Mega is a microcontroller board based on the ATmega1280 (datasheet).
       It has 54 digital input/output pins (of which 14 can be used as PWM outputs),
       16 analog inputs, 4 UARTs (hardware serial ports), a 16 MHz crystal oscillator,
       a USB connection, a power jack, an ICSP header, and a reset button.
       It contains everything needed to support the microcontroller; simply connect it
       to a computer with a USB cable or power it with a AC-to-DC adapter or battery
       to get started. The Mega is compatible with most shields designed for the
       Arduino Duemilanove or Diecimila.
       </Description>
     </BoardList>

Note that for the graphic that is displayed with the board when the new project wizard is launched I have specified external.mega1280.  This tells the wizard to look in the %ATE_HOME%\Graphics for a file named external.mega1280.png.  The size of the picture must be 150×150 pixels and the format must be png.  Figure 2, illustrates the picture of the board used.  Save it to %ATE_HOME%\Graphics and make sure it is named external.mega1280.png.

Figure 2 – Mega1280 Board

Next step is to take care of the default programmer for the Mega1280.  I declare Mega1280BootLoader to be default programmer.  A development board can be configured to support multiple programmers (bootloader,ISP,custom,etc) and the desired programmer activated from the sketch project.  Search for Mega2560BootLoader.  It should be around line 471.  Copy the content from line 471 to line 480 and paste it..  Listing 2, illustrates how the programmer entry should be changed.

   <Programmer Include="Mega1280BootLoader">
        <ComPort>COM5</ComPort> <!-- Use the port supported in your environment -->
        <Protocol>wiring</Protocol>
        <ComPortSpeed>115200</ComPortSpeed>
        <ProgTransfer>avrdude</ProgTransfer>
        <Verbosity>-v</Verbosity>
        <MiscParams></MiscParams>
        <SupportEEPROMTransfer>false</SupportEEPROMTransfer>
        <Comment></Comment>
    </Programmer>

Change the ComPort entry as needed in your environment.  The Programmer entry in listing 2 uses avrdude and the wiring protocol to program the board.  You could also use an ISP programmer if you are not going to use the bootloader.  When the option to upload a sketch is pressed in Atmel Studio, this is the entry that drives how the sketch is uploaded to the development board.  We are now ready to add the Mega1280 board to the Arduino core libraries to complete the process.

Adding the New Board to Target Libraries

The first library we are going to test is the ArduinoCore library.  Open the project %ATE_HOME%\Source\ArduinoCore\ArduinoCore.atsln.  Next open the file Scripts\TagetBoards.xml.  The TargetBoards.xml contains a list of all the boards supported by the ArduinoCore library.  When compiling all supported boards from the command line, the build script loops through the list of supported boards and makes each supported board the active board, changes variables and references according to each board profile and compiles the code.  Finally the compiled code is copied to the %ATE_HOME%\Source\_Stage\BoardName\Libs\Frequency.  Follow these steps to take care of the changes.

1. Create an entry for a new supported board and name it Mega1280 (the name must match the name used in the boards.xml).  Use the default programmer (Mega1280BootLoader)  and frequencies configure in boards.xml.
2. Modify the CurrentBoard entry (first one in the file) to also reference the Mega1280 development board.  This step is very important.  By making the Mega1280 the CurrentBoard, the core library will only be compiled for the Mega1280 when you invoke the MakeIt.bat script with the Compile parameter.  If you skip this step, you will need to call MakeIt.bat with the CompileAll parameter which will take a while since the code will be compiled for all boards and it will get to the Mega1280 based on its position in the list.  See Figure 3 for an illustration of how the beginning of the TargetBoards.xml file should look like after the changes are done.  Do not delete the list of all the other boards supported.  We are done with the changes, let’s go ahead and compile the code.

Figure 3 – TargetBoard.xml

Compiling Arduino Core

There is a “feature” of msbuild that prevents the scripts distributed with ATE 1.0.2 Beta 3 from running when there are spaces in the path.  I have a fix that will take care of this in the final ATE 1.0.2 release.  If you have ATE 1.0.2 Beta 3, copy the folder %ATE_HOME%\Source to the root of your C:\ drive, you will end up with a c:\source folder.  If you have a folder name source already in your c:\ drive you can provide any name you want as long as it does not have a space.  Follow these instructions:

1. Open a command window.  All prerequisites discussed at the beginning of the post need to be met for the rest of the instructions to work.
2. Go to the directory source\ArduinoCore\Scripts and type makeit compile.  This will compile only the current board, which we previously setup to be the Mega1280.  See Figure 4 for results of compilation.
   

   Figure 4 – Result of ArduinoCore compilation

3. After compilation is completed, check the directory source\_stage.  You will find a Mega1280 directory with sub-directories name Headers and Libs.  The Headers contains all headers files for the ArduinoCore and future libraries you compile for this board.  The Libs contains a sub-directory for every supported frequency for the board.  In this case 16 (representing 16mhz) is the only directory available.  Inside the 16 directory you will find the ArduinoCore libraries in release and debug modes.  See Figure 5.
   

   Figure 5 – Stage folder after compilation

4. Invoking the script makeit compileall will compile the ArduinoCore libraries for ALL boards supported.  This takes a long while and IS NOT required for this tutorial.
5. The last step requires copying the Mega1280 folder just created to the %ATE_HOME%\Boards folder.  This is the root folders from where Atmel Studio projects pickup libraries for linking sketches.  For instance, when you develop a sketch for the Mega1280 board, libraries are expected to be found at %ATE_HOME%\Boards\Mega1280\Libs\16 and headers are located at %ATE_HOME%\Boards\Mega1280\Headers.  The frequency at the end of the libs directory changes according to the value of the F_CPU variable.
6. To compile other libraries repeat the steps documented in the above section Adding New Board to Target Libraries.  In fact you can just copy the <CurrentBoard> and <SupportedBoard> entries created for the ArduinoCore library, see figure 3, and paste it into the targetboards.xml of the library you want to compile.  Then go to the source\LibraryIWantToComile\Scripts and run makeit.bat compile.  Look in the source\_stage\Mega1280\Libs\16 and you will find the debug and release versions of the compiled library.

Configuring a new board takes is a bit involved the first time you do it since you will need to configure tools, paths, etc. After you get the environment setup correctly and understand the mechanics of adding new boards and configuring projects to support it, adding future boards will take you a few minutes.

This article is no longer relevant.  Please follow the Arduino Template Express update to find a more mature offering to allow development of Arduino sketches in Atmel Studio 6.1.

The Arduino IDE is a good development environment to get started with microcontrollers.  It holds your hand and hides complexities that get in a novice way.  As you gain experience and want to use advance features such as refactoring, assembly language or binary libraries, working with the Arduino IDE just doesn’t cut it.  Moving to a more advance IDE is the next logical step for a mature Arduino user.  It is the equivalent of leaving your home to go to college. Jaycon Systems has a well written three part tutorial explaining how to configure Atmel Studio 6.0 to compile Arduino projects. I have taken a different approach to solve this problem and have created an installation script to accomplish the following;

1. Distribute a binary file for the core library (libcore).
2. Distribute binaries of the Arduino libraries (libEEprom, libEthernet, libFirmata, libLquidCrystal, libSD, libServo, libSoftwareSerial, libSPI, libStepper, libWire).
3. Distribute a solution with projects for all the libraries specified above so libraries can be recompile and redeployed as needed.
4. Distribute a project template for Arduino Sketch.  This allows you to do a new project and select Arduino Sketch from the list of available templates.
5. Distribute a project template for Arduino Lib.  This allows you to do a new project and select Arduino Library from the list of available templates.
6. Distribute a deployment scripts to write sketches to the destination chip.  This allows a one click deployment to the Arduino board.

The rest of this post covers the configuration of the installation script and the deployment scripts in the Atmel Studio environment.

Configuring Installation Script

In order to run the installation script, you need Arduino 1.0.1 or greater and Atmel Studio 6 or greater.  Both of these programs must be installed and running successfully.  The installation script is located at the Arduino Installer site at Codeplex.  It contains all the binaries and scripts required for the installation.  Follow these instructions carefully for a successful installation.

1. Download the installation package from Codeplex
2. Unzip in a directory of your choice.  For the purpose of this post I am going to assume you have decompressed the installation script at c:\arduino-install.
3. Open the file c:\arduino-install\install.bat with your favorite text editor and go to the :SetUserVariables label, around line number 31
4. By default the ATMEL_CPU is configured to ATmega328p, change this line if necessary to reflect your microcontroller.  Typical values are ATmega32u4 (Leonardo),  ATMega328p (Uno), ATmega2560 (Mega), ATmega168 (Diecimila).
5. The CPU_FREQUENCY and ARDUINO_VERSION do not need to be changed.  I have tested with the  Arduino 1.0.1 IDE successfully with these default values CPU_FREQUENCY=16000000 and ARDUINO_VERSION=100
6. Set the COM_PORT variable to the communication port you are using to communicate with the Arduino board.  The default is COM3.
7. Set the COM_PORT_SPEED variable to the proper value if necessary.  The default is 115200.
8. The VARIANT variable refers to the pin layout of the board.  Change it accordingly to reflect the type of board you have.  The values are standard (Uno, Diecimila), leonardo (Leonardo), etc.  The default value is standard.
9. Last setup the AVRDUDE_ROOT_DIR variable with the value of the root director where the avrdude is located.  This could be done from the Arduino installation or from Winavr.  Note that the avrdude.exe would be at AVRDUDE_ROOT_DIR\bin\avrdude.exe from the path you specify.
10. Save the file and open a command window.  Go to the directory c:\arduino-install and run install.bat.

After a few seconds you should see an output similar to that illustrated on Figure 1.  The installation script has done the following;

Figure 1 – Installation Results

1. Create directory structures at C:\users\YOUR_USER_NAME\Documents\Atmel Studio\Libs and Headers.
2. Under Libs there are three directories, ArduinoCore for the core library, Arduino for all the Arduino libraries and Public for your personal libraries.
3. Under Headers there are three directories, ArduinoCore for the core library headers, Arduino for the different Arduino library headers and Public for your personal library headers.
4. All binaries and header files have been deployed to these directories.
5. There is a file named deploy.bat located at c:\users\YOUR_USER_NAME\Documents\Atmel Studio.  This file is responsible for performing generic solution and project name clean up and then invoking the localdeploy.bat file that is located in the Arduino project directory and is part of the sketch template.
6. In the c:\users\YOUR_USER_NAME\Documents\Atmel Studio\Templates\ProjectTemplates there are two files.  Arduino Library.zip and Arduino Sketch.zip, these are the library and sketch templates for Atmel Studio.
7. At c:\users\YOUR_USER_NAME\Documents\Atmel Studio\ArduinoLibrariesSource a solution named ArduinoLibraries.atsln has been deployed with the source code for all the Arduino libraries so you can recompile them from within Atmel Studio if you wish to update the distributed binary libraries.

Configuring Deployment Script

The configuration of the deployment script allows you to do deployment of Arduino sketches with one click or keyboard shortcut.  Sketches are deployed to the Arduino board while libraries are deployed to the Public folder of the library directory created by the installation script.  Follow these instructions to configure the deployment script in Atmel Studio;

1. Open the External Tool manager from Tools/External Tools
2. Setup a new entry named &Deploy with the characteristics illustrates in Figure 2.
   

   Figure 2 – External Tool Definition

3. The & before the D, makes it a hot key while in the context of the Tools menu.  This means pressing ALT-T followed by D will launch the Deploy script.
4. The parameters must be $(SolutionDir) $(ProjectDir) $(ProjectFileName).  There is a space between each parameter.
5. Select use Output window so you can see the outcome of the deployment within Atmel Studio.
6. The top most entry is External Tool 1, the second one is External Tool 2 and so on.  Moving the entries up or down changes the External Tool to the command located at the target position.  If you have multiple external commands registered, keep track of the position where Deploy is located because we are going to need it later.

Let’s create a custom toolbar and add some commands that will facilitate the development experience.

1. Go to view\Toolbar\Customize and create a new toolbar.
2. Name the toolbar Productivity.  Hit OK and make sure the checkbox is selected.
   

   Figure 3 – Creating a Productivity toolbar

3. Select the Commands tab and select the Toolbar radio button.
4. In the drop down select the Productivity toolbar we just created.
5. Add the command Build\Build Solution
6. Add the command Tools\External Command1 (or whatever the name of the Deploy command is in your setup)
7. Move it up and down as needed.
   

   Figure 4 – Toolbar Commands

8. Click on the Keyboard button and select the Tools.ExternalCommand1
9. Enter a shortcut for it and press Assign.  In my case I configured the Tools.ExternalCommand1, which is the Deploy script as CTRL+SHIFT+P
   

   Figure 5 – External Tools Shortcut

10. Hit OK and we are done.  You should see a toolbar with the following information.
    

    Figure 6 – Productivity Toolbar

The option to deploy is available via a click on the Deploy button in the Productivity toolbar or via CTRL+T followed by D or via CTRL+SHIFT+P.  Any one of these three options should satisfy your workflow.

Creating Arduino Sketches

To create your first Arduino sketch in Atmel Studio 6, launch Atmel Studio, select File\New\Project.  The new project window appears similar to figure 7 with all the installed templates.

Figure 7- Atmel Studio With Arduino Templates

Select Arduino Sketch, change the name to TestSketch1, change the location if necessary and press OK.  A new solution is created with a project named TestSketch1.  The project has three files, with the following content;

1. main.cpp – contains code to blink the led on the Arduino board.  This is so you can have a quick block of functional code.
2. localdeploy.bat – this is the local deployment script.  This file is called by the deploy.bat script located in your c:\users\your_user_name\Documents\Atmel Studio\deploy.bat.  It gives you the opportunity to customize deployment for a particular sketch.  The localdeploy.bat is ready to deploy the hex file located in the Release directory, not debug.  This script reflects the port, speed and directory information provided to the installation script.  I have submitted internal enhancement request AVRSV-3699 to Atmel to have the $(Configuration) variable exported to indicate you are running in Release or Debug mode.  Until this issue is addressed the default hex file deployed is the one in the release directory. You can change the script to deploy from the Debug directory if necessary.
3. readme.txt – This file contains a list of the Arduino libraries, which files you need to include and which libraries you need to add to the linker.

Before compiling the code you need to open the project properties (ALT-F7),  select All Configurations and under Toolchain\AVR/GNU Linker\Libraries add libcore.  See Figure 8.  There is a bug in Atmel Studio 6 that does not include the libraries added to a project template.  I have submitted internal bug AVRSV-3701 to Atmel for this issue.  Note the Library search path is automatically populated with the directory structure where the libraries are located. After adding the library you can go ahead and compile the code, then press the deploy button in the Productivity Toolbar.  You will see avrdude copy the hex file to the Arduino board and the onboard LED start flashing.

Figure 8 – Add Core Library

Creating Arduino Libraries

To create an Arduino library, select File\New\Project and select the Arduino Library template from the list of available templates.  Name the library TestLib1 and change the directory as necessary.   A new directory is created with four files.

1. foo.h and foo.cpp contain a dummy class
2. localdeploy.bat is the deployment script responsible for deploying the library and header files to the Public directory of the Lib and Header created during installation.  As before only the Release version is deployed for the same reasons previously stated.
3. readme.txt contains a blank file.

If you need a reference to libcore in your library you must add it as explained for the sketch.  Deploying the library copies all the header files and *.a files to the Public directories.

Conclusion

Adopting Atmel Studio has the potential to increase your productivity and expose you to advance concepts such as mixed language programming (C/C++ and Assembly).  If you are a Microsoft developer familiar with Visual Studio, you will feel right at home in Atmel Studio 6.  Let me know if the script has been of assistance transitioning out of the Arduino IDE.