Portable WinAVR Quick Start Guide

Erik Lins, chip45.com

Last modified: 13-Jul-2008, E.Lins

Portable WinAVR is based on the regular WinAVR suite of software development tools for the Atmel AVR microprocessor series and is preconfigured to run directly from any removable medium (e.g. USB memory stick) without prior installation.

Take your favorate AVR development environment to any PC with free USB port, take it to the lab's PC, where normally no WinAVR is installed, take it to a customer and perform software corrections in the field, evaluate a new WinAVR version prior to installing it permanently... etc.

1.0 Availablility

Portable WinAVR is available at www.chip45.com/Portable_WinAVR as:

ZIP archive with Portable WinAVR distribution
ZIP archive with sample projects

1.1 ZIP File

Download the Portable WinAVR ZIP file from the above mentioned location and extract it to the root directory of your target drive. No further installation is necessary.

The ZIP file with the sample projects is optional. If desired extract this ZIP file also to the target drive root directory.

1.2 Preloaded USB Memory Stick

The USB memory stick is preloaded with the above mentioned Portable WinAVR ZIP file and sample projects ZIP file.

In addition to these files, the following directories are preloaded:

Portable\TTERMPRO		Tera Term (Pro) is a free terminal program for Windows. It supports VT100 emulation, telnet connection, serial port connection, and so on.
Portable\Datasheets		This folder contains several Atmel application notes and datasheets as well as other useful documentation.

No installation is required, just connect the USB memory stick to a PC USB port!

2.0 Package Content

As the name implies Portable WinAVR can be taken along on any removable (or non-removable) medium to any Windows-PC and runs without installation. All necessary files for compiling AVR code are included in the ZIP file or on the memory stick.

2.1 File System Layout

The original WinAVR file system layout (see chapter 2.2 of the WinAVR User Manual for details) can be found under

<drive>:\Portable\WinAVR-20090313

which is the install directory of WinAVR. <drive> refers to the drive letter of your removable media and is determined by the below listed batch script files automatically.

2.2 Batch Script Files

The following batch script files are installed in the root directory of the target drive.

[Portable WinAVR] Programmers Notepad.bat		This batch file starts the Programmers Notepad editor/ide, which is a very goods source editing tool with integrated project handling and comfortable access to the compiler toolchain (build, program, etc.). The batch file also does some checks and settings in advance: The Portable WinAVR location is searched and some environment variables are set (see below for details), prior to starting the Programmers Notepad. If no Portable WinAVR distribution is found, the batch process terminates without starting anything.
[Portable WinAVR] Makefile Generator.bat		This batch file starts the Makefile generator, which provides a graphical user interface for selecting various project options and finally generates a high quality Makefile. The batch file also does the previously mentioned checks prior to starting the program.
[Portable WinAVR] Command Shell.bat		This batch file opens a Windows command shell, which provides text based access to the WinAVR toolchain. The batch file also does the previously mentioned checks prior to starting the shell, i.e. inside this shell all necessary environment variables are set for running Portable WinAVR.
[Portable WinAVR] Avrdude Graphical Frontend.bat		This batch file starts the graphical user interface (GUI) for the avrdude ISP programming software, which can be used to set fusebits of the AVR microcontrollers and/or read and write eeprom and flash memory through various ISP adapters. The current version of the avrdude GUI is in an alpha stage and is included as a preview. Use at your own risk!
[Portable WinAVR] AVR Insight.bat		This batch file starts the graphical user interface (GUI) for the GNU debugger gdb. AVR Insight has not yet been tested with the Portable WinAVR distribution and was just included for completeness!
[Portable WinAVR] View Quick Start Guide.bat		This batch file starts this Quick Start Guide either with Firefox or Internet Explorer browser.
[Portable WinAVR] View Licenses.bat		This batch file opens notepad.exe with a copy of the license text, which is shown and one has to agree to during regular WinAVR installation.
Note: The above batch script files call Portable\bin\makeportable.bat which tries to find the Portable WinAVR directory and sets various environment variables required by WinAVR. Then the respective application is started. The command shell window remains open during the application runs and must not be closed - otherwise also the application will be terminated!

2.3 Supplementary Files

Portabel\here.it.is

This is an empty file, which is used by the following batch files to identify the location of the Portable WinAVR distribution.

2.3 Changes to WinAVR Files

When downloading the full ZIP file, the following files of the original WinAVR distribution were modified or added, respectively.

<drive>:\Portable\WinAVR\pn\tools\WinAVR.xml

This file contains the settings for the Tools menu of the Programmers Notepad editor. Two new tool entries were added:
- "Make fusebits" for programming a working set of fusebits into the AVR - provided, that the Makefile contains a fusebits section. This is the case for all chip45.com programs, but might not be the case for other programs.
- "Make chip45boot" programs the application into a target MCU with preloaded chip45boot bootloader.

Note: These changes are not necessary for regular WinAVR functionality. They are just required by certain code examples, which assume a preloaded bootloader.

See www.chip45.com/chip45boot.

2.4 Environment Variables

The above addressed batch script files set the following environment variables, which are necessary for proper toolchain operation:

PATH		The PATH variable is extended (prepended) by: <drive>:\Portable\WinAVR-20080620\bin <drive>:\Portable\WinAVR-20080620\utils\bin
GCC_ROOT, BINUTILS_ROOT, G++_ROOT		WinAVR normally retrieves these variables from the Windows registry. For running WinAVR without installation, they are set as environment variables to: <drive>:\Portable\WinAVR-20080620
If you have installed the sample projects ZIP file or have the preloaded USB memory stick, the following environment variable is set, too.
AVRLIB		The sample projects include the Procyon AVRlib by Pascal Stang, which needs this variable set to: <drive>:\Projects\avrlib

3.0 Getting Started

It doesn't take much to get the Portable WinAVR toolchain running, since no real installation is required. The necessary steps are described below. For further advice on the WinAVR tools (e.g. toolset background, C library, making software, programming targets, debugging, setting up a project) please read the WinAVR User Manual from chapter 3.0 on.

3.1 Setting Up Portable WinAVR

If you have a preloaded USB memory stick, you can skip these steps.

Download the Portable WinAVR ZIP file from the homepage (see above).
If desired, also download the sample projects ZIP file.
Extract the file(s) to the root directory of any drive (removable media, portable hard disk drive, USB memory stick or real hard disk) you prefer. (*)

(*) The ZIP files must be extracted to the root directory of the destination drive and not into any sub folder, otherwise the above mentioned batch script files will not be able to find the distribution.

3.2 Using a Simple Sample Project

For doing this, the sample project ZIP file has to be installed.

Start the Programmers Notepad editor with the batch script file: [Portable WinAVR] Programmers Notepad.bat.
Select Open Project(s) from the File menu.
Direct the file selection dialog to <drive>:\Projects\toggle.
Open toggle.pnproj.
If desired, open toggle.c or the Makefile from the project view on the left side.
Select make all from the Tools menu to compile to program.
This should have generated several new files in the toggle folder
If you have an ISP adapter connected to the PC and to a target or you have a target with preloaded bootloader, select make program from the Tools menu. (*)
To clean up the folder and delete all temporary files, select make clean from the Tools menu.

(*) The Makefile is preset to an ATmega8 target microcontroller connected to an STK500 compatible ISP programmer. If this is not the case with your setup, make program will not work proper. In this case you would have to change the Makefile. The sections MCU and AVRDUDE_xxxxx are good candidates for adjustments. Alternatively go to the next section, which describes how to set up a new project and generate a suitable Makefile.

3.3 Setting Up a New Project

Create a new folder <drive>:\Projects\myfirstproject - or chose any other name instead of myfirstproject.
Start the Makefile generator with the batch script file: [Portable WinAVR] Makefile Generator.bat.
From the menu Makefile you can select various target and programmer related options, which are changed or added to the Makefile automatically.
When you finished your selections, select Save As... from the File menu and save the Makefile into your new project folder.
Start the Programmers Notepad editor with the batch script file: [Portable WinAVR] Programmers Notepad.bat.
Select New > Project from the File menu and enter a name and select your project folder in the dialog.
The project area on the left side now shows the new project structure - which just shows the name of the project.
Right-click on the project name, select Add Files from the context menu and select the previously created Makefile and open it.
Now the Makefile is listed below your project name in the project view.
Since we need at least one source code file, select New > C / C++ from the File menu.
Enter code in the new editor window labeled <new>
Select Save As... from the File menu and save the file to you project folder. The name should match the Main file name... you entered when you created the Makefile!
Now the source code file should also be listed in the project view.
Select make all from the Tools menu to start compilation of your program.
If no errors occured you should have several new files in your project folder, including a .hex file, which is the file necessary for downloading into the target.
Select make program from the Tools menu to program youre target microcontroller. The respective programmer and target specific settings should have been done in the Makefile generator. You can restart the Makefile generator at any time, open the Makefile and apply new settings and save it again. Or adjust the Makefile from the Programmers Notepad by double-clicking in the project view and editing by hand.

3.4 Programmers Notepad File Extensions

Programmers Notepad uses mainly two file extensions for handling projects.

.pnproj		This is a normal project file. It contains the name of the project and the names and hierarchy of the files belonging to the project in an XML-like syntax.
.ppg		This is a project group file. A project group is composed of several individual projects. The file contains the name of the projects belonging to the project group in an XML-like syntax.

Note: Both file types must be opened with the Open Project(s)... command in the File menu! Opening those files with the normal Open command or doing a drag-and-drop operation into the Programmers Notepad window, will just open the file for editing and will not open the project hierarchy.

4.0 Portable WinAVR Project Background

4.1 Build Notes

Portable WinAVR is based on the current release of WinAVR-20070525. The Portable WinAVR folder contains the complete set of files of a regular WinAVR installation plus the above mentioned supplementary files (see 2.2). The original WinAVR files were not changed. All portability issues were (hopefully...) solved with the batch script files.

4.2 Credits

Thank you for using Portable WinAVR!

Thanks to Eric B. Weddington for building the original WinAVR toolset distribution.

Thanks to all other people contributing to WinAVR (see WinAVR User Manual chapter 10.3).

4.3 TODO / Open Topics

Work on the Portable WinAVR project started quite recently. Up to now only the basic toolset functions have been tested, like makefile generation, simple project handling with Programmers Notepad, compiling, linking, programming with avrdude, etc. Further testing of the more sophisticated tools is required, as well as testing with Windows versions other than XP.