"Another library? It's gotta add something special or else I won't be using it - I only just got familiar with the last one." Quite Right! Neither would I.
"Man - look at the size of this manual! It's big and big = complicated" I would rather say that the manual is 'comprehensive'. It covers enough detail for those who are adding new functionality to it who need to understand the detail - but, for the novice, we also provide some much easier to use functions. So don't think that you need to understand all of this manual. For example: the timer.h module contains a lot of low level stuff which is probably only of interest to people writing new motor drivers for the library. But if all you want to do is use an existing motor driver then you don't need to understand timer.h at all. Consequently: for each header file I have attempted to categorise each function as to whether it's an advanced function or not. Newbies can skip the 'advanced functions'. Of course my decision as to what is advanced or not is somewhat arbitrary. I have also made the decision to release ALL detail to ALL people - newbie or not. The other alternative would be to have a separate small manual for newbies and a larger one for more advanced folk - but where do you draw the line?
Why have I invested an enormous amount of my own time to come up with a new library? Well it's really down to my own frustrations with AVRlib (the competition?) as well as my experience with the kind of programming questions posted to the Society of Robots (SoR) forum.
AVRlib tries to be 'all things to all AVRs' and I am sure that this is true but I am not going to put it down. But the result is a library that is still very much tied into the hardware meaning that you (the programmer) need to have some understanding of each chip or board that uses it. This is fine for 'experienced' developers who can invest the time in understanding datasheets of both the processor (which are 100s of pages long) and of the board they are using (ie what pins from the processor can actually be used). But for newbies it is rather unhelpful.
In order to try and be more removed from the underlying hardware this library concentrates on the following AVRs:
This covers most set ups for the Society of Robots. If you want an extra chip added then let me know - and I will try to add support. Note that 8k chips like the ATMega8 have limited program space and so can only cope with small programs and may be dropped in the near future.
Here's a little example. Let's assume you are creating a program for the Axon which uses the ATMega640 processor. The processor has 8 i/o pins on Port L and so AVRlib will let you create a program that uses them. Only problem is that the Axon board doesn't actually have any header pins for Port L but you don't know that since your program will compile ok. With this library the program will not compile. Saves you time and hassle.
Other libraries give you a myriad of different ways just to set an output pin high (see iopin.h for more info). This may mean that it caters for your own particular coding preference but it creates code that becomes unreadable - especially if you have more than one developer each having their own preferred way of doing things. So it's flexible but chaotic.
The heart of all libraries (AVRlib and this one) is the WinAVR library. WinAVR is very low level and should be thought of like a device driver. Programmers should be shielded from it as far as possible otherwise they can do strange things. WinAVR defines lots of things like ports, registers and stuff and various bit definitions. But the two aren't linked together in any way. So using most libraries I can write code that is valid but complete nonsense e.g. sbi(PORTD,MUX1); where both parameters are valid but in combination they are not - the compiler doesn't know this and you can only debug the program by checking the datasheets. My library tries to rectify this (e.g. the above example will not compile).
My library goes further by disallowing all of the other ways of setting I/O pins. It may sound restrictive but the reason is to get all I/O to go through a central place. This would mean that it would be easy to log all I/O pin changes: either to a PC as AVR scenario files or to the SoR'scope. Dead easy to just turn it on for testing and off for production - no coding needed!
Standalone - no more copying files into your own project
WinAVR is a nice library - it just defines stuff in 'h' files and you can include as many of them as you like but it wont generate any code unless you reference something it has defined. Also: because it is just a bunch of 'h' files then you can point your makefile, or AVRStudio, to the base folder of the library and that's it. AVRlib is a bit more temperamental because it has some C files as well as the H files. Most newbies just end up copying the C files into their own project just to get it to compile. If you now download a new version of AVRlib then you have real problems. The compiler is probably picking up the 'h' files from the new AVRlib but is using the old 'c' files that you copied into the project. So now you have to recopy the new C files into every project.
I have tried to solve this by providing pre-compiled libraries for each of the covered devices. Each library will work irrespective of the processor speed. e.g. there is only one library for ATMega168 and this will work for 1MHz, 8Mhz and 20Mhz clock speeds. Examples are given later as to how you instruct the complier to use the correct library.
Portability across outputs
If you are still unconvinced then here is another reason for this library. Let's say you've made your robot and written the code. Now you want to change some of the servos for DC motors controlled via a UART on a motor controller board such as the Sabretooth. Big change? For some libraries then 'Yes' but not with my library.