1

Volume

ADVANCE ATMEL STUDIO PROJECT TEMPLATES V1.01

Omar Francisco

Installation Guide

ADVANCE ATMEL STUDIO PROJECT TEMPLATES

Installation Guide

Omar Francisco www.omarfrancisco.com

T able of Contents
Project Introduction .................................................................. 1 Road Map ................................................................................ 1 Prerequisites ............................................................................ 2 Installation ................................................................................ 2
Arduino Properties .......................................................................... 2 AVR Microcontroller Properties ....................................................... 3 What Has Setup Done For Me ........................................................ 4

Configuring Atmel Studio.......................................................... 6

Configuring Deploy.bat As External Tool ........................................ 6 Custom Toolbar .............................................................................. 7

Using Project Templates ........................................................ 11 Arduino 1.01 Sketch ............................................................... 12

Supporting Scripts ......................................................................... 13

Arduino 1.01 Static Library ..................................................... 16 C AVR Executable ................................................................. 17 C AVR Static Library .............................................................. 17 C++ AVR Executable ............................................................. 17 C++ AVR Static Library .......................................................... 17 Compiling Arduino Libraries ................................................... 20

A D V A N C E

T E M P L A T E

I N S T A L L E R

Chapter

Project Introduction
This chapter describes the goal and road map of this project.

he initial goal of this project was to provide a transition path to Arduino users to migrate from the Arduino IDE to Atmel Studio 6. The first release included two templates and the necessary binary infrastructure to allow users to create Arduino libraries and sketches in Atmel Studio 6. Since the first release the scope of the project has increased to include the following goals: 1. Provide a migration path for Arduino users to adopt Atmel Studio IDE. To achieve this goal a set of custom templates and binary libraries are provided to allow the creation of Arduino libraries and sketches from Atmel Studio. 2. Increase developer productivity. To achieve this goal the project provides a solution for one click deployment, command line builds and enhanced project templates to create native AVR C or C++ projects. 3. Promote unit testing as a practice. To achieve this goal a unit testing template is provided using a modified version of ArduinoUnit. Future releases will include additional support for unit testing.

Road Map
Table 1, illustrates a brief layout of the road map for this project.
Table 1

Release 1 2 3

Description Basic templates for Arduino libraries and Sketches Additional templates for AVR projects and Arduino unit testing Additional tools for unit testing and development workflow analysis.

A D V A N C E

T E M P L A T E

I N S T A L L E R

Prerequisites
In order to install the templates you need to have Atmel Studio 6 installed and must have run it at least once so it creates the Atmel Studio directories under your profile. You also need a copy of AVRDUDE version 5.10 or greater. You DO NOT need the Arduino IDE installed.

Installation
To install the project, run setup.exe. The setup process will walk you through the selection of different properties about your Arduino board and Atmel Studio. If you had version 1.0 installed, it will be replace with version 1.01.
Arduino Properties

The screen illustrated in Figure 1 appears after running setup.exe. This screen collects information pertinent to the Arduino board installation and the AVRDUDE software. Provide the following information.

Figure 1

The Arduino Board dropdown allows you to select the Uno, Mega, Diecimilla or Leonardo board. The selection of the board controls which pin profile is selected by setup.exe behind the scenes. The COM Port dropdown allows the selection of the port to which the Arduino board is normally connected. A port between COM1 and COM12 can be selected. The path to avrdude.exe is the path where AVRDUDE is installed. Note that having the Arduino IDE is not a requirement to install this project. If you have AVRDUDE
2

A D V A N C E

T E M P L A T E

I N S T A L L E R

installed as part of WinAVR or other programs, you can select it. The project was tested with AVRDUDE 5.10. Click next to proceed.
AVR Microcontroller Properties

Figure 2 illustrates the next screen in the setup process. This portion of the setup process collects general environment preferences that are recorded to increase your productivity when creating new projects.

Figure 2

The Preferred Programmer allows you to select the programmer that you use the most in your environment. The supported programmers are USBTiny, AVRDragon and AVRISPMK2. What this selection does for you is to configure a default programmer in the deployment script of the different AVR templates provided by the project. You can always change the programmer in the deployment script of each individual project. Having a preferred programmer saves you time when creating a new project. The Programmer Mode is only pertinent to the AVR Dragon programmer. If you do not have the AVR Dragon you can leave this selection with the default, otherwise configure as necessary. You can change the Programmer Mode for the AVR Dragon any time in the deployment script of the project. The ATProgram.exe comes with Atmel Studio. It is required to use the AVR Dragon and AVRISPMK2 programmer. AVRDude supports the AVRISPMK2 programmer but requires additional USB drivers. The deployment script defaults to atprogram.exe when the AVRISPMK2 and AVR Dragon programmers are used and to AVRDUDE when the Arduino board and USBTiny programmers are used.

A D V A N C E

T E M P L A T E

I N S T A L L E R

The Preferred Microcontroller Speed is the default speed used to setup the F_CPU environment variable when a new project is created. You can look up the project properties and change this to you hearts content after the project is created. This saves you time when creating a new project since the F_CPU variable does not have to be set. Click install, blink twice and the setup program is done. Figure 3 illustrates the setup program after installation is complete.

Figure 3

Click the Close button and setup is done.

What Has Setup Done For Me

Setup.exe does many things to configure the environment to enhance the user experience. Here is a list of what setup has done: 1. Deploy 7 templates to c:\users\[user]\Documents\Atmel Studio\Templates\ProjectTemplates 2. Deploy 1 item template
at c:\users\[user]\Documents\Atmel Studio\Templates\ItemTemplates

3. Deploy a deploy.bat to c:\users\[user]\Documents\Atmel Studio\deploy.bat 4. Deploy the Arduino libcore library to c:\users\[user]\Documents\Atmel
Studio\Libs\ArduinoCore\

5. Deploy all Arduino headers for libcore to c:\users\[user]\Documents\Atmel

Studio\Headers\ArduinoCore

6. Deploy all Aduino libraries binaries that come with the Arduino IDE to
c:\users\[user]\Documents\Atmel Studio\Libs\Arduino\
4

A D V A N C E

T E M P L A T E

I N S T A L L E R

7. Deploy all Arduino library headers that come with the Arduino IDE to
c:\users\[user]\Documents\Atmel Studio\Headers\Arduino\

8. All project templates have been customized with paths relevant to your configuration. 9. F_CPU has been defined in Arduino templates as 16MHZ and for AVR templates as your favorite speed. 10. All project templates have a deployment option to deploy sketches or executable binaries to a target device and libraries to the c:\users\[user]\Documents\Atmel Studio\Headers\Public or c:\users\[user]\Documents\Atmel Studio\Headers\Arduino directories.

A D V A N C E

T E M P L A T E

I N S T A L L E R

Configuring Atmel Studio

If you are upgrading from a previous version of this project, you can skip this step. If not, you will need to configure the deploy.bat file as an external tool in Atmel Studio and configure a custom toolbar in order to do one click deployment.
Configuring Deploy.bat As External Tool

The configuration of the deployment script allows you to do deployment of sketches and libraries with one click or simple keyboard shortcut. Sketches and AVR programs are deployed to the Arduino board or target device using your favorite programmer (selected during setup). Personal libraries are deployed to the Public folder of the library directory created by the installation script while Arduino libraries are deployed to the Arduino directory in the library/header folder. 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 illustrated in Figure 4. 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 command is c:\users\[user]\Documents\Atmel Studio\deploy.bat 5. The Arguments are $(SolutionDir) $(ProjectDir) $(ProjectFileName). There is a space between each argument. 6. Select use Output window so you can see the outcome of the deployment script within Atmel Studio 7. 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 for the configuration of the custom toolbar.

A D V A N C E

T E M P L A T E

I N S T A L L E R

Figure 4 Custom Toolbar

Follow these steps to create a custom toolbar. 1. Go to View\Toolbar\Customize and create a new toolbar 2. Name the toolbar Productivity (any name will do). Hit OK and make sure the checkbox is selected. See Figure 5. 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 Tools\External Command1 (This is where you need to remember the position of the deploy command we previously created). 6. Add other commands as needed. In my case I have the Build Solution command added as well. See Figure 6. 7. Move the commands up and down as needed

A D V A N C E

T E M P L A T E

I N S T A L L E R

8. Click on the Keyboard button and select the Tools.ExternaldCommand1 9. Enter a shortcut for and press the Assign button. In my case, I configured the Tools.ExternalCommand1 as CTRL+SHIFT+P. See Figure 7. 10. Hit OK and we are done. You should see a toolbar similar to that of Figure 8. Position it in a convenient location in Atmel Studio. 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. Anyone of these three options should satisfy your workflow. In Chapter 2 well take a look at how to use each individual template deployed by the installation package.

Figure 5

A D V A N C E

T E M P L A T E

I N S T A L L E R

Figure 6

A D V A N C E

T E M P L A T E

I N S T A L L E R

Figure 7

Figure 8

10

A D V A N C E

T E M P L A T E

I N S T A L L E R

Chapter

Using Project Templates

This chapter discusses the different templates installed and how to get the most out of them.

n total 7 different templates have been installed in Atmel Studio. The templates address functionality for both Arduino and AVR projects. Figure 9 illustrates the list of templates you will see when you select the option to create a new project. All templates have similar structure and behavior. Well go through each individual template so you get a good understanding how it works and how you can customize it.

Figure 9

Before getting started go ahead and select each template so you can see its picture and description. The description includes the default CPU speed at which the F_CPU
11

A D V A N C E

T E M P L A T E

I N S T A L L E R

environment variable is set. This value comes from the Preferred Microcontroller Speed in the setup program. For Arduino templates the default is 16MHZ, for AVR it is whatever you selected. The version of all templates for this release is 2012-09-22.

Arduino 1.01 Sketch

Select the Arduino 1.0.1 Sketch template. The name of the sketch defaults to ArduinoSketch1, the number may be different if you already have other projects named ArduinoSketch## in the selected location. The solution name also defaults to ArduinoSketch1. Change the name as desired and click OK. Figure 10 illustrates the content of the project in the Solution Explorer window after its creation. All the supporting scripts are under a Script directory to get them out of the way until they are needed. If you compile the sketch you will get an error indicating undefined reference to main in file gcrt1.S line 52 column 1. There is a bug with Atmel Studio 6 that does not bring over additional libraries defined in a template. Atmel has confirmed this is bug number AVRSV2701 and they will eventually get to it. In the meantime open the project properties (ALT-F7), Select All Configurations and under Toolchain-AVR\GNU Linker/Libraries add libcore. Save the project properties. Figure 11 illustrates how the project properties will look like once you add the libcore library. The Library search path will reflect your personal directories. Compile the code one more time. There should be no more errors. Launch the terminal window tool from Atmel Studio or any other terminal solution you prefer. Connect to the COM port where the Figure 10 Arduino is running and you should see the message Hello World! followed by an incrementing number. The first lines of the display will contain a message with the project name, the active configuration [Debug|Release] and the time stamp when the Sketch was compiled. Figure 12 contains a snapshot of the sketch running in my PC. Pretty cool right?

12

A D V A N C E

T E M P L A T E

I N S T A L L E R

Figure 11

Figure 12

Lets discuss the role of the different scripts involved in the solution. Note the scripts do not get in your way while programming. You can safely ignore the Scripts folder and go about your business programming your solution.
Supporting Scripts

Figure 13 illustrates the pre and post build events in the project properties (ALT-F7). The Scripts\prebuild.bat is called during the Pre-build event. This script receives 7 parameters and is responsible for calling any other scripts that are required as part of the pre-build event and pass the set of parameters the script requires.

13

A D V A N C E

T E M P L A T E

I N S T A L L E R

Figure 13

The prebuild.bat script works in the same way in all templates. It also receives exactly the same set of parameters. So once you understand how this put together for this template, you will understand it for all the other templates as well. Open the prebuild.bat file. It invokes three additional scripts. The first is precaptureprops.bat, followed by pre-genfiles.bat and last pre-genmasterbuild.bat. Each script takes a different set of parameters based on what it does. Table 2 list what each script invoke during the pre-build event does. You can browse each individual file for more information.
Table 2

Script Pre-captureprops.bat

Description Capture the name of project, the name of the binary file generated by the compiler, the microcontroller type and the configuration to external files to be used by the deployment script during the deployment process. Generate the global.cpp file with the project information and current time stamp. This file is included in the template to illustrate the functionality you can have from Atmel Studio. You can expand this technique to support a version counter so each time you compile the counter goes up by one and you keep

Pre-genfiles.bat

14

A D V A N C E

T E M P L A T E

I N S T A L L E R

track of the version in the microcontroller memory. This is a good practice when you want need to know which version of your code a microcontroller is running. You can get rid of this feature by commenting the invocation to pregenfiles.bat in pre-build.bat and removing the global.cpp file from the project. Pre-genmasterbuild.bat This script generates the masterbuild.bat script. The masterbuild.bat script is responsible for providing support to compile and deploy the project from the command line using msbuild.

The post-build event calls the postbuild.bat script which does not do anything. You can make postbuild.bat call anything you want in order to support postbuild activities. The last two scripts to discuss is ld-program.bat and localdeploy.bat. When you press the deploy button in the productivity toolbar, the location of the project is passed to the deploy script. Using the path of the project the deploy.bat script calls the scripts\localdeploy.bat. This file is responsible for calling all scripts involved in the deployment activity. For this template the only script that needs to be called is ldprogram.bat. This script contains COM port information, speed and programmers information. It also has a variable named DEBUG_FLAG when set to ON, the deployment does not take effect, but you get to see the value of all the script properties. At the end of the process ld-program calls the proper programmer and passes the compiled files. The template illustrates how to integrate your sketch with assembly language. I admit the included assembly function is very lame, but the concept is powerful. The file build.xml is required to support compiling/deploying the project from the command line using the masterbuild.bat script.

15

A D V A N C E

T E M P L A T E

I N S T A L L E R

Arduino 1.01 Static Library

Select the Arduino 1.0.1 Static library. The name of the sketch defaults to ArduinoLib2, the number may be different if you already have other projects named ArduinoLib2 ## in the selected location. The solution name also defaults to ArduinoLib1. Change the name as desired and click OK. Figure 14 illustrates the content of the project in the Solution Explorer window after its creation. All the supporting scripts are under a Script directory to get them out of the way until they are needed. The behavior of the ld-program.bat script is different in the library template. Instead of deploying a sketch to the microcontroller, it deploys the compiled library and the supporting headers to the corresponding directory in the lib and header folders created during setup. In addition there is a ld-genunistall.bat responsible for generating a script to uninstall the libraries and the actual uninstall.bat script responsible for unistalling the libraries. This script are very convenient when testing libraries and cleaning up the environment. As with all other templates the build.xml and masterbuild.bat work together to provide compilation of the code from the command line. A reference to libcore needs to be addes the same as previously
Figure 14

discussed.

16

A D V A N C E

T E M P L A T E

I N S T A L L E R

C AVR Executable
The C AVR Executable is a template to work on AVR microcontrollers using a programmer such as AVR Dragon or USBTiny to program the chip directly. Programs with this template use the C language. The template supports the selection of the microcontroller at the beginning of the project or at any other time after the project is created. The option to deploy uses the AVRDUDE to transfer the binary file for the project using the preferred programmer selected during installation. The script ld-program.bat contains all the logic for the programming of the microcontroller. You have the opportunity to modify this file and use a programmer different than the one selected during installation. All other scripts behave similar to the description provided for the Arduino template.

C AVR Static Library

The C AVR Static Library is a template to develop libraries for AVR microcontrollers. Programs with this template use the C language. The behavior of the scripts associated with this template is similar to the behavior of scripts for the Arduino library template. The primary difference is the destination to which files are copied. For this template the files are copied to the Public folder of the Lib and Header folders.

C++ AVR Executable

The C++ AVR Executable is a template to work on AVR microcontrollers using a programmer such as AVR Dragon or USBTiny to program the chip directly. Programs with this template use the C++ language. The template supports the selection of the microcontroller at the beginning of the project or at any other time after the project is created. The option to deploy uses the AVRDUDE to transfer the binary file for the project using the preferred programmer selected during installation. The script ld-program.bat contains all the logic for the programming of the microcontroller. You have the opportunity to modify this file and use a programmer different than the one selected during installation. All other scripts behave similar to the description provided for the Arduino template.

C++ AVR Static Library

The C++ AVR Static Library is a template to develop libraries for AVR microcontrollers. Programs with this template use the C++ language. The behavior of the scripts is similar to the Arduino library template. The deployment script copies the files the Public folder of the Lib and Header folders.

17

A D V A N C E

T E M P L A T E

I N S T A L L E R

Arduino 1.01 Unit Test Sketch

Select the Arduino 1.0.1 Unit Test Sketch template. The name of the sketch defaults to UnitTest1, the number may be different if you already have other projects named UnitTest## in the selected location. The solution name also defaults to UnitTest1. Change the name as desired and click OK. Figure 15 illustrates the content of the project in the Solution Explorer window after its creation. All the supporting scripts are under a Script directory to get them out of the way until they are needed. If you compile the sketch you will get an error indicating undefined reference to main in file gcrt1.S line 52 column 1. There is a bug with Atmel Studio 6 that does not bring over additional libraries defined in a template. Atmel has confirmed this is bug number AVRSV-2701 and they will eventually get to it. In the meantime open the project properties (ALT-F7), Select All Configurations and under Toolchain-AVR\GNU Linker/Libraries add libcore. Save the project properties. Figure 11 illustrates how the project properties will look like once you add the libcore library. The Library search path will reflect your personal directories. The Unit Test template is one the most complex template of the group. It includes a modified version of the ArduinoUnit library as well as a supporting item template to create test suites. The template works with one test suite at the time. The maximun number of tests a suite can have is 128 (0-127). The file Suitecontrol.h controls which suite is run. Using masterbuild.bat from the command line compiles and deploy each individual test suite. This work is incomplte. The final solution will have the ability to capture the output of the test suite, disconnect the Arduino board so the next test suite can be uploaded. This will make it to the next release.
Figure 15 Unit Testing Workflow

Because of the memory limitations of the Arduino microcontroller, the workflow to test your code is a little different than the workflow you may have used when using unit testing frameworks such as JUnit or NUnit. The workflow for the ArduinoUnit is most effective when you work with one test suite, create unit tests until you run out of memory and then create a new test suite. Keep repeating this until you are done with all the tests. On each deployment to the Arduino only the test suite flagged in

18

A D V A N C E

T E M P L A T E

I N S T A L L E R

SuiteControl.h is deployed. It is to your advantage to package as many tests as possible in one single suite in order to maximize runtime execution and minimize number of deployments. Figure x, illustrates the unit testing workflow just described. Todo: include workflow graph
Creating Test Suites

To add a new test suite press (CTRL+SHIFT+A) or right click on the project and select Add\New Item. Select the Test Suite template and press OK. [Incomplete]

19

A D V A N C E

T E M P L A T E

I N S T A L L E R

Chapter

Compiling Arduino Libraries

This chapter discusses how to recompile the Arduino libraries.

n total 7 different templates have been installed in Atmel Studio. The templates address functionality for both Arduino and AVR projects. Figure 9 illustrates the list of templates you will see when you select the option to create a new project. All templates have similar structure and behavior. Well go through each individual template so you get a good understanding how it works and how you can customize it.

20