all our stuff. Please note that I said ‘we’ — yes, you and
me! Because of the miracle of the Internet, we will be
able to use the same toolbox. The AVR_Toolbox
(metaphorically shown in Figure 1) is an open source
project hosted on Google Code [http://code.google.
com/p/avrtoolbox/] where you will be able to access all
sorts of AVR tools discussed in Smiley’s Workshops.
Anyone can download the code and since this is a “we”
project, if you want to participate (and aren’t crazy), I’d be
happy (even grateful) for your help. I especially need
feedback on typos and bugs, so if you see any problems,
be sure and post something in the ‘issues’ page.
AVR_Toolbox is a work in progress and always will be. We
expect to get better with time; likewise, we expect our
tools to get better.
Documenting With Doxygen
Doxygen [ http://www.stack.nl/~dimitri/doxygen/] is a
software documentation system that helps you write
comments in your source code that can be scanned to
produce documents in a variety of formats; most relevant
here are HTML (shown in Figure 2) and Windows Help
files (.html and .chm). Doxygen can do a lot of stuff and
the AVR_Toolbox documentation is only one way to do
things — one way that might evolve over time as we learn
more about it.
One good reason to use doxygen is that it allows us
to keep the documentation in one place tied directly to
the source code. If we change the code, we’ve got the
documentation right there in the code, making it easy to
change it also. If you keep your documents in a separate
manual and you make a change in the code, you’ll write a
note to yourself to remember to change the manual and
then (if you’re like me) you’ll lose the note. With doxygen,
you can even keep a to-do list directly linked to the code
(shown in Figure 8).
Since we discussed the SPI last month, we will
convert those functions into a library that we will
document with doxygen to illustrate the principles
involved. First, we create the documentation for our main
page using the doxygen \mainpage directive:
\image html AVR_Toolbox.gif
<center>Visit us at: http://www.smileymicros.com
\mainpage SPI (Serial Peripheral Interface)
This code was designed to allow the user to
create multiple SPI links using either
bit-banged software or regular AVR hardware SPI.
The user first selects a SPI number from a list
that can be expanded as needed:
//#define SPIx // place holder
SMILEY’S WORKSHOP ☺
■ FIGURE 2. Doxygen generated HTML main page.
After selecting and SPI number, then the user
selects either software or hardware for that
The user accesses the following functions:\n
uint8_t spi0_master_rw8(uint8_t to_slave);\n
uint16_t spi0_master_rw16(uint16_t to_slave);\n
Which are alia’s for the software or hardware
This code was tested for SPI0 in both software
and hardware modes on the ATmega169, ATmega328,
and ATmega644 (TODO)
\todo 1. Test it for the ATmega644.
\todo 2. Retest with the Arduino board.
\todo 3. Improve the comments before letting
this puppy loose!
\author Joe Pardue
\date October 29, 2010
Doxygen will find this section and turn it into an html
file that looks like Figure 2.
The first thing to notice about the code is that the
section we want doxygen to look at is delimited with /*!
and */. Most of the doxygen commands use a backslash
(‘\’) character such as \mainpage. There are many
doxygen commands, but we will only use a small subset
of them to keep things simple. [The source code file is in
the Workshop30.zip available from Nuts & Volts.]
After you install doxygen, you will find doxywizard.exe
January 2011 59