Raspi + ATmega328p + HaikuVM

[Alan]

My boss recently gave me a Raspberry PI and a Gertboard (IO Expander which connects to the PI gpio pins) to play with. The Gertboard features amongst other cool things an ATmega328P micro. With some connections and a custom avrdude it is possible to use the Raspi as a programmer for the ATmega chips in ICP mode. The custom avrdude and more info on the Gertboard can be found here:

https://projects.drogon.net/raspberry-pi/gertboard/

I've compiled, linked and uploaded the BlinkWithThread.java demo code to the ATmega flash with all seeming success, but the
program doesn't appear to run at all.

After fiddling for a while, I discovered that the HaikuVM.properties (in the arduino config) is set up with a clock of 16Mhz. The ATmega, however, is clocked at 12Mhz on the Gertboard. So I changed the clock line in the properties file and tried again - compiling, linking and flashing appears to work but the chip remains totally silent.

I've had success with the following C listing, so I'm pretty sure the Raspi -> ICP -> ATmega setup is working:

#define F_CPU 12000000L

#include <avr/io.h>
#include <util/delay.h>

int main(void)
{
   DDRD = 0xFF;   // PORTD is output
   PORTD = 0x00;   // LED's are off

   for (;;) {
      PORTD = 0x01;   // invert the pins
      _delay_ms(500); // wait half a second
      PORTD = 0x02;   // invert the pins
      _delay_ms(500); // wait half a second
   }

   return 0;
}

I've compiled the example above using avr-gcc, uploaded it and my LED started flashing without problems.

I've tried the same with the following BlinkWithThread.java code as found on the Haiku web site:

import static haiku.avr.lib.arduino.WProgram.*;

public class BlinkWithThread extends Thread {
    static byte ledPin = 13;            // LED connected to digital pin 13

    public void run()                   // run over and over again
    {
        while (true) {
            digitalWrite(ledPin, HIGH); // sets the LED on
            delay(1000);                // waits for a second
            digitalWrite(ledPin, LOW);  // sets the LED off
            delay(1000);                // waits for a second
        }
    }

    /**
     * @param args
     */
    public static void main(String[] args) {
        pinMode(ledPin, OUTPUT);        // sets the digital pin as output
        new BlinkWithThread().start();
    }
}

I've used the following commands to compile, link and upload the program to the ATmega:

haikuc BlinkWithThread.java
haikulink -v --Config arduino -o BlinkWithThread.hex BlinkWithThread
avrdude -p atmega328p -c gpio -v \ -U flash:w:target/cross/BlinkWithThread.hex

As I said, all appears to go well, but the program doesn't appear to be running on the ATmega. It just sits there silently.

Does this perhaps have something to do with the 12Mhz clock as opposed to the 16Mhz defualt?

Any help will be appreciated.

[genom2]

Hi Al,

a "Raspi + Gertboard to play with" sounds cool. I don't know if your boss is generous or sly. ;-)

1) I wonder. Where is haikuc runnning? On the Raspi? Has it this power? As described, haikuc needs javac. Does a javac exists for the Raspi? Which version of javac? Please send me the output (stdout + stderr) of all haiku commands you entered.

2) I wonder! For me:

haikuc BlinkWithThread.java
haikulink -v --Config arduino -o BlinkWithThread.hex BlinkWithThread

does not work. HaikuVM needs the right directory and full-path-name approach like this (where bob is only an example user):

cd haikuVM/myCProject

/home/bob/haikuVM/bin/haikuc /home/bob/haikuVM/examples/src/main/java/arduino/tutorial/BlinkWithThread.java
/home/bob/haikuVM/bin/haikulink -v --Config arduino -o BlinkWithThread.hex /home/bob/haikuVM/examples/src/main/java/arduino/tutorial/BlinkWithThread 

May be this is one reason for not having success.

3a) Thank you for your 'blinky.c' example. This code uses _delay_ms(..) which is implemented as a busy-wait delay loop. May be we have to start with HaikuVM as simple as this 'blinky.c' example. Therefore I suggest to fall back to a basic and simple busy-wait example for AVR which you will find in './haikuVM/examples/src/main/java/avr/tutorial/BlinkSimple.java'. Caution: First you have to edit and change it to your needs because this example assumes that the LED is on PORTB.

3b) May be, even the arduino configuration ('--Config arduino') is to heavy for Gertboard (especially the MicroKernel). Please add a more simple Gertboard Configuration in file 'HaikuVM.properties' like this:

#
# Gertboard Configuration
#
# More info on the Gertboard can be found here:
# https://projects.drogon.net/raspberry-pi/gertboard/
#
gertboard.Extends = avr
gertboard.Target = atmega328p
gertboard.MemorySize = 1540
gertboard.Clock = 12000000
gertboard.MicroKernel = haiku.avr.lib.simple010.HaikuMicroKernel
gertboard.Port = gpio
gertboard.Upload = avrdude -p atmega328p -c $(HAIKU_PORT) -U flash:w:$(HAIKU_OUTPUT)
#gertboard.Upload = avrdude -pm328p -cstk500v1 -P$(HAIKU_PORT) -b57600 -Uflash:w:$(HAIKU_OUTPUT):a

to be used with '--Config gertboard' (see below).

4) Then try again, this time with 'BlinkSimple.java':

cd haikuVM/myCProject

/home/bob/haikuVM/bin/haikuc /home/bob/haikuVM/examples/src/main/java/avr/tutorial/BlinkSimple.java
/home/bob/haikuVM/bin/haikulink -v --Config gertboard -o BlinkSimple.hex /home/bob/haikuVM/examples/src/main/java/avr/tutorial/BlinkSimple.java 

And upload.

[Alan]

Thanks for the verbose response.

I don't think the Gertboard has anything to do with the problems I'm experiencing - it is really only a simple IO expander that happens to have an ATmega328P on-board. I really only use the Raspi as a programmer for the ATmega on the Gertboard - the ATmega basically runs "standalone".

My toolchain is divided onto 2 machines: I use my Ubuntu 12.10 workstation with oracle jdk1.6.0_31 and avr-gcc 4.5.3. I have a modified avrdude on the Raspi to flash the hex file onto the ATmega via the Gertboard. I've coppied the BlinkWithThreads.java file to a local directory and removed the package declaration at the top of the file so BlinkWithThreads is in the default package. Here follows the commands I run on my workstation:

haikuc BlinkWithThreads.java
haikulink -v -o BlinkWithThreads.hex BlinkWithThreads

Then I copy the BlinkWithThreads.hex file to the Raspi and issue the following command (on the Raspi):

avrdude -p atmega328p -c gpio -v -U flash:w:BlinkWithThreads.hex

NOTE: the "-c gpio" switch is the modification to avrdude I mentioned earlier - the Raspi gpio pins is hooked up to the ATmega ICP mechanism and the gpio programmer switch bitbangs those pins to flash the hex file to the ATmega.

All steps succeed without complaints but the led simply won't blink. One thing I've noticed is that the pin1 of the ATmega goes high when the flash process completes. Maybe that's an indication of something? I've noticed something about "flashing leds on startup" in the haiku source tree - just can't remember where.

I'll give your suggestion a whirl and try a simpler example like the BlinkSimple.java that you've suggested. I didn't know how to compile your samples so thanks for sharing that with me.

I'll be back with my findings - for better or for worse.

PS: on "On the Raspi? Has it this power?" - YES - the power of the Raspi is shocking for such a tiny little device! I've set up JBoss AS 7.1.1 on the Raspi and it runs like a charm.

[Alan]

Thanks genom2, your suggestion to build the simpler AVR example paid off. Can't believe I'm watching Java code run on a micro! It borders on perverse! ;-)

I've been in love with the Java language for a while now. The haiku bug really bit the crap out of me! It would be nice if there was some document available describing the overall architecture of the toolchain. I know I can just look at the sources, but isn't there some sort of guide available which can help newcomers hit the ground running?

Anyways, thanks again. You've made my day.

[genom2]

Hello Alan,

thank you for your feedback.

I bet, in the meanwhile you manged to get 'avr.tutorial.Blink.java' to run, which uses Thread.sleep(..), which in turn relies on timer 0 overflow interrupt (resulting in non-busy-wait).

1) You ask for some guide. I plan to write a set of tutorials for the HaikuVM page. But I'll try to do it in small steps. One will be a tutorial about timing. To start with, I need a help-help situation ;-) :

How did you set TCCR0B in 'avr.tutorial.Blink.java' (which is originally written for 16MHz) to reflect the 12MHz of the Gertboard?

The timer 0 overflow interrupt is handled in function 'TIMER0_OVF_vect' of file './haikuVM/simpleOS.c' and just increments variable 'timer0_interrupts'. From this variable the function millis() derives the milliseconds for Thread.sleep(..), Thread.wait(..), System.currentTimeMillis() and the internal Thread scheduler of HaikuVM. To give you a clue:

SIGNAL(TIMER0_OVF_vect)
{
    timer0_interrupts++;
}

julong millis()
{
    jmillis m;
    uint8_t oldSREG = SREG;
    cli();
    m = timer0_interrupts;
    SREG = oldSREG;
    return m * 128 / 125; // tweeked manual
}

How did you changed the factor 128 / 125 ( in function millis() ) to reflect the 12MHz of the Gertboard?

NOTE:
You have to remove the destination directory './haikuVM/myCProject/haikuVM/' after each change in source file './haikuVM/simpleOS.c' to have an effect.

2) Please, confirm if this Gertboard configuration is usable:

#
# Gertboard Configuration
#
# More info on the Gertboard can be found here:
# https://projects.drogon.net/raspberry-pi/gertboard/
#
gertboard.Extends = avr
gertboard.Target = atmega328p
gertboard.MemorySize = 1540
gertboard.Clock = 12000000
gertboard.MicroKernel = haiku.avr.lib.simple010.HaikuMicroKernel
gertboard.Port = gpio
gertboard.Upload = avrdude -p atmega328p -c $(HAIKU_PORT) -v -U flash:w:$(HAIKU_OUTPUT)

If so, I will add it to file 'HaikuVM.properties' permanently.

[Alan]

I'd sure like to be the help-help hand, but the micro is just a hobby of mine. I'm not too bad a Java/C/Perl coder, but when it comes to micros I'm still a bit of a virgin.

I did manage to write my own version of BlinkWithThreads with 2 instances of the thread flashing LEDs on 2 different pins at differing frequency. I coppied the 10Mhz intialization code for the timer from another of your samples and prayed that the LEDs blink... which they did. The timing is definately off but I was just happy that the micro's doing something.

I'm definately up for the challege to provide you with an answer: so I'm going to take some time to study the ATmega datasheet to see how the chip works, then I'll investigate your post again until I can come up with an answer. This is really just day 3 for me on the ATmega and the HaikuVM so please be patient.

On the Gertboard configuration that you suggested: I changed the gertboard.MicroKernel setting to

gertboard.MicroKernel = haiku.avr.lib.arduino.HaikuMicroKernelEx

... and the program still worked. I'm not sure if that's a surprize - in a previous post you recomended the HaikuMicroKernel since you suspected that the HaikuMicroKernelEx was too heavy for the chip.

Just one more question then I'll try and do my homework first: I noticed that the arduino examples uses code from WProgram to access the digital IO pins. Digging a little deeper I saw that the pinMode and digitalWrite methods use PORTB exclusively for digital IO. Is it possible to change that to PORTD? My dilema is that the Gertboard uses most of PORTB for in-circuit programming and an external clock - and I've had NO luck doing anything on PORTB. PORTD is wide open and all my Haiku success was thanks to that.

If you can give me a hint on where to look I'd be grateful.

[genom2]

Thank you for your homework offer. (I will be patient.)

1) Fast hint for your dilemma: You may merge 'avr/tutorial/Blink.java' with 'arduino/tutorial/BlinkWithThread.java' by changing 'digitalWrite(ledPin, HIGH);' into 'PORTD |= LED;' to be independent of my poor digitalWrite(..) implementation.

2) Alternatively, you may enhance my digitalWrite(..) implementation:

    public static void digitalWrite(byte pin, byte val) {
        if (pin>=8) {
            int bit = 1 << (pin - 8);
            if (val == LOW)
                PORTB &= ~(bit);
            else
                PORTB |= bit;
        } else {
            int bit = 1 << (pin);
            if (val == LOW)
                PORTD &= ~(bit);
            else
                PORTD |= bit;
        }
    }

[Alan]

I've done my homework and changed the millis() function on simpleOS.cpp.

julong millis()
{
    jmillis m;
        uint8_t oldSREG = SREG;
        // timer 0 prescale factor is 64 and the timer overflows at 256
        // disable interrupts while we read timer0_millis or we might get an
        // inconsistent value (e.g. in the middle of the timer0_millis++)
        cli();
        m = timer0_interrupts;
        SREG = oldSREG;
#if defined(__AVR_ATmega8__)
        return ((m * 256) + count36kHz) / 36;
        //return m * (clockCyclesPerMicrosecond() * 1000UL)/(64UL * 256UL);
#else
        return m * 512 / 375;    // For 12Mhz clock
        //return m * 128 / 125; // For 16Mhz clock
#endif
}

I've derived the 512 / 375 from this line of the code:

...
return m * (clockCyclesPerMicrosecond() * 1000UL)/(64UL * 256UL);
...

... which came down to this calculation:

(12 * 1000)/(64 * 256)

... which amounts to 375 / 512. I've tried that but the LED (from BlinkWithThread.java) seemed to blink in intervals of just under 2 seconds. So I tried the calcution for 16Mhz clock:

(16 * 1000)/(64 * 256)

... which yielded 125 / 128. The return in the source used 128 / 125 so it seemed that I had to swap my nominator and denominator in my 12Mhz version. Now the led blinks MUCH closer to 1 second intervals, only I have NO idea why that formula works. Do you have any information that explains it in mundane terms?

PS: here's the BlinkWithThreads.java source that I used for testing millis():

package avr.tutorial;

import static haiku.avr.AVRConstants.*;

/*
 * This program demonstrates how threads can be used to do multiple things
 * at a time and reusing code. We use the same Runnable instance to blink
 * 2 different LEDs at different frequencies.
 */

public class BlinkWithThreads implements Runnable {
    private static final int LED5 = (1 << 5);
    private static final int LED6 = (1 << 6);
    private static final int LEDMASK = LED5 | LED6;

    static {
        /* This sets up one of the timers - it seems like it
         * has an influence on Thread.sleep();
         */
        TCCR0B |= _BV(CS01) | _BV(CS00);
        TIMSK0 |= _BV(TOIE0);
        DDRD = LEDMASK;
    }

    public static int _BV(int bit) {
        return 1 << bit;
    }

    // Each instance has its own state
    private int led; 
    private int delayms;

    public BlinkWithThreads(int led, int delay) {
        this.led = led;
        this.delayms = delay;
    }

    public void run() {
        while (true) {
            PORTD |= led;
            delay(delayms);
            PORTD &= ~led;
            delay(delayms);
        }
    }

    private void delay(int ms) {
        try {
            Thread.sleep(ms);
        } catch (InterruptedException e) {
        }
    }

    private static void main(String[] args) {
        // Here we fire off 2 similar tasks but with different
        // state
        new Thread(new BlinkWithThreads(LED5, 1000)).start();
    }
}

[Alan]

Wait I think I understand the millis() function now:

Here's the general formula for calculating the factor for determining millis:

1/((1/1000)/((1/12000000)*64*256))

Or symbolically:

1/((1/1000)/((1/F_CPU)*PRESCALER_FACTOR*TIMER_INCREMENTS_TILL_OVERFLOW))

To put it in words:

The timer input clock runs at 12Mhz or 12 million times per second, thus

1/12000000

The prescaler is set to 64, so the counter will only be incremented once after

(1/12000000)*64

An overflow will occur only after every 256 of the above:

(1/12000000)*64*256

What we want to know is how many times

(1/12000000)*64*256

...'es must occur in 1/1000ths of a second, thus we get:

((1/1000)/((1/12000000)*64*256))

Now we know how many interrupts happen in a millisecond, which resolves to:

375 / 512

To get the final result, we have to use inversion:

1/((1/1000)/((1/12000000)*64*256))

...which yields:

1 137/375 

or 

(375 + 137)/375 

or 

512/375

How does mathematical inversion work? Can anyone translate this into words for me please?

Sorry if the question seems stupid. Should've paid attention to the blackboard instead of the sexy math teacher's shwiggle.

Shwiggle, n:
The amusing rotation of one's bottom while writing on a blackboard or sharpening a pencil.

[genom2]

Thank you for your calculations. I can't remember inversion but I do remember shwiggle, n! ;-)
In the next version of HaikuVM (coming out soon) the line:

return m * 128 / 125; // For 16Mhz clock

will be substituted by

return m * MILLIS_DIVIDEND / MILLIS_DIVISOR;

and #define MILLIS_DIVIDEND and #define MILLIS_DIVISOR will be pre-calculated automatically from haikulink like this (sketch):

private static void findScale(long f_cpu) {
    double b=(128.0*16000000)/(125.0*f_cpu);
    double best=Double.MAX_VALUE;

    int dividend=1;
    int divisor=1;
    for (int i = 1; i< 1000; i++) {
        for (int j = 1; j< 1000; j++) {
            double t=1.0*i/j;
            double err=(t-b)*(t-b);
            if (best>err) {
                best=err;
                dividend=i;
                divisor=j;
            }
        }
    }
    System.out.printf("%d: %d / %d = %f (%f %f)\n", f_cpu, dividend, divisor, 1.0*dividend/divisor, b, 16000000.0/f_cpu);
}

Assuming the prescaler is set to 64. Any suggestions?

[Alan]

Oh yes, of course! Haiku is part compiler! Yes, it would be great to have a more flexible timing component. That way the users of Haiku aren't restricted to specific hardware configuration. I'm thinking of swithcing from PIC Micros to AVR and I'm used to clocking the PIC at 20Mhz. I don't even own a 16Mhz crystal. Your findScale method makes the VM timing transparent to the end-users which is great. All they need to know is to set the correct clock frequency in HaikuVM.properties. The rest is taken care of.

I don't understand the findScale algorithm just yet but I'll fire up my Netbeans IDE and run it in a debugger to see how it works. Would be nice to have the same flexibility on the prescaler option, especially since 64 is not perfect for all values of F_CPU. I'll get back to you on that one.

I've recently discovered great tutorials on AVR timers:

http://www.avrfreaks.net/index.php?name=PNphpBB2&file=viewtopic&t=50106

You mentioned that you'd like to write a tutorial on timing in HaikuVM - perhaps you could write a tutorial that compliments that one. Those tutorials are aimed at the C language, but perhaps you can give some insight on how HaikuVM uses the AVR's timer modules. Another curiosity is on HaikuVM and interrupts and how to use them.

I'm going to experiment with simpleOS.c (and related source) with other timer options such as CTC using the 16 bit timer. That would give me very accurate timing and I'll learn a lot about HaikuVM internals.

Yet again, thanks for this. I'm really having a blast with HaikuVM!

[Alan]

Oh there is something I wanted to ask: I'm planning on creating a Netbeans project over your HaikuVM sources. This will consist of a couple of Java and C++ projects - since Haiku seems to be a conglomeration of multiple single-purpose projects. Can you perhaps shed some light on the directories in haikuVM and what they are for?

bin
bootstrap
config
examples
haikuBench
haikufier
haikuRT
haikuVM
hardware
lib
myCProject <-- I've met this one already.

Can you perhaps provide a short description of each of these directories and how they relate? It would be really helpful to understand how the build system works and how all the submodules are related.

On and one more thing: is it possible to run haikuVM on a PC. I've seen pc directories throughout the source, but I don't have any idea how to run it on a PC. Any advice?

[genom2]

Because you bombed me for explanations ;-) , I put a preview into the WEB:
http://haiku-vm.sourceforge.net/preview.html

See the timeline on the right to find new things. (Version 1.0.2 is not for download yet.)
Any suggestions are welcome!

[Alan]

Sorry for bombing - I do that when I'm really excited about something. The questionares will taper off as things becomes clear.

Thanks for all your help. I'll try to figure things out for myself from now on.

[genom2]

1) No, I need(!) your (and others) questionnaires to make progress on the documentation. To know where to focus on first. So please stay tuned with your criticism!

2) You mentioned to set up a Netbeans IDE project. I have no experience with Netbeans IDE but may be, this tiddler is of some help http://haiku-vm.sourceforge.net/#Eclipse . If you have success with Netbeans IDE may I ask you for sending equivalent screenshots to me? I would like to share this by publishing them side by side to the Eclipse tiddler.

3) Yes, there are "pc" directories. This is experimental and "PC" is more like a working title for any desktop PC (here Windows or Linux). The idea is to use Windows or Linux as a targets too (instead of a microcontroller). It's not to challenge the real JavaVM with its HotSpot compiler. It's more for debugging purposes. This will not work in version 1.0.1 because "avr-gcc" is used as a constant literal in the makefiles (instead of "gcc" or better $(HAIKU_GCC) to be defined flexible in HaikuVM.properties). In the future something like this should work:

/home/bob/haikuVM/bin/haiku -v --Config unix /home/bob/haikuVM/examples/src/main/java/arduino/tutorial/HelloWorld.java
or
C:/haikuVM/bin/haiku -v --Config pc C:/haikuVM/examples/src/main/java/arduino/tutorial/HelloWorld.java

producing "Hello World" at output on the console.

Today I do debugging with "Microsoft Visual C++ 2005" (yes, I know it's outdated) right on top of 'myCProject'. For this, some projekt properties have to be set:
- Console program
- data alignment has to be set to 1
- Preprocessor definitions like so: WIN32;_DEBUG;_CONSOLE;NO_MICRO=1
(I think thats it.)
After running

C:/haikuVM/bin/haiku -v --Config arduino C:/haikuVM/examples/src/main/java/arduino/tutorial/HelloWorld.java

(you see I'm using contra intuitive "--Config arduino" and not as expected "--Config pc") HelloWorld.java prints a line because it uses

UDR0 = b;

to write any Character (to be find in haiku.avr.lib.arduino.HaikuMicroKernelEx). This is how an AVR writes a byte to its UART register.
Java bytecode uses PUTSTATIC to write to a static variable here UDR0. For bytes PUTSTATIC is refined to PUTSTATIC_B in HaikuVM (by haikulink). Take a look at PUTSTATIC_B in file 'bytecodes.h':

BEGCODE(PUTSTATIC_B)
#if NO_MICRO
    setMemory8((jbyte*)GETCODEADR2(), top.s1.b);
#else
    *(jbyte*)GETCODEADR2()=top.s1.b;
#endif
    popTop();
ENDCODE

You see, if NO_MICRO is set it's redirected to setMemory8(..) which is defined in file 'MemoryAccess.c'. Here, in setMemory8(..), a tailor made hook

        case UDR0_IDX:    putchar(value); break;

causes it to print the value as char, which was to be achieved.

Hoping you are not dying because of information overload.

[Alan]

I'm immune to information overload. ;-) It's part of beign moderately obsessive-compulsive. I have a vivid imagintation and insatiable curiosity, and currently haikuVM on the AVR is my newest coolest toy!

I've started reading a book on JVM internals. It'll help me make sense of what's expected from a JVM and will help me debug mentally through haikuVM and haikuRT - those are the modules I chose to begin with creating Netbeans projects. I'm not sure I've done that correctly - I really only wanted to use the IDE to browse the code - not integrate fully with the haiku build system. I'll check out your Ecclipse instructions to find commonalities.

It makes me all fuzzy inside to know that I'm finally contributing - although indirectly - to an open source project. I've been an avid user of open source since I got my hands on a copy of Redhat 6, but never really had the opportunity to contribute back to the awesome community. Thanks for giving me that chance!

On documentation itself: I'm a visual kinda guy - diagrams say so much more than endless strings of characters. If you'd like, I could contribute some to the project as my understanding of the internals improve. It's my belief that a project is as successful as the quality of its documenation.

Thanks again for all your support - each response gives just the right information.

[genom2]

It would be fantastic, if you contributed some diagrams to the project! I'm all agog to see the dusk of "endless strings of characters"! ( This was another kind of selfmade haiku ;-) )

BTW: Did you see my two simple diagrams and are they of some help to you? (Is this what a "visual kinda guy" is looking for?):
http://haiku-vm.sourceforge.net/preview.html#[[Your%20Project%20on%20Disk%20and%20on%20the%20Micro]]

[Alan]

Proof that pictures says so much more! Just one look, and the runtime structure of the haiku system is clear.

Those are the kind of diagrams I had in mind - but I was personally thinking in the lines of the project- and code structure. I've recently started playing with UML and design patterns and I've found that it gives me an immense boost into what I'm actually modeling. But whether something like UML is a fit for haikuVM... only lots of time and study will tell.

I'm sorry I haven't noticed the long list of links in the sidebar of the site. My mind tends to draw away from long lists of unstructured text. There appears to be a wealth of information in there but my eyes literally swims between all those letters. I'd suggest more "less" in the site design where those articles are categorized. But without complaining further, I'll take a look at the content and make a suggestion.

Have you seen the primefaces web site? Now that is supperbly clean and easy to navigate:

www.primefaces.org

PS: got lots of homework now. I'm going to shut my hole for a couple of days and do something.