WebbotLib AVR library
WebbotLib It just does it
  C++ documentation  C documentation

My first program

Now that our environment has been set up correctly we can concentrate on writing some code.
We will start by writing a simple program that sends the text 'Hello World' out of the serial port every second. Ok - I know that sounds very dull - but finding out how to get your Robot to send messages back to your computer is essential when you want to start debugging your own programs.
Start up Project Designer and select File New as we want to create a new project. Select the board you are using from the list available. You will then be asked the details about the sort of battery you are using to power the board. You will now see something like the following (for the AxonII):-
HelloWorld1.jpg
Note that its good practise to disable the devices you aren't using as the generated code will be smaller. No point making the code more complex than we need - right?
You can do this by ticking the box against the device in the list at the bottom of the screen. All devices can be disabled, except for the clock, and this is much easier than deleting things as we may want to put them back later. Note that you can only delete devices that you've added - you can't delete devices that are built onto the board but you can disable them. We won't be using the push button or the marquee (the segmented LED) in this project so we will disable them:-
HelloWorld2.jpg
Next we will look at the settings of the UART. In my case I will be using 'uart1' as on the AxonII this has a USB connector making it much easier to connect to my PC.
If no UART is listed for your board then you need to create one. You can do this by opening the 'Communications' folder on the left hand side and then drag the 'UART' entry into your list of devices and you will see a window like this:-
HelloWorld3.jpg
If you are using an existing UART then just double click on it in the list of used devices to see the same window. So whether you are using an existing UART or you have created a new one then make a note of the baud rate as we will need that later when setting up the PC end of things.
You may be wondering why all of the UARTs don't already come as built in devices. This is because on most micro-controllers each individual pin can be used for many different purposes. So if you are running out of I/O pins but aren't using all of the UARTs then you may want to use the UART pins as standard I/O pins instead. The only reason why things like UART1 on the Axon series are built in is because they've got extra hardware and a USB connector attached to them - so WebbotLib stops you from trying to use them for other things as that may risk blowing up this additional hardware
We have now got the devices we need set up so the only thing left to do in Project Designer is to save the project and generate the code. Select Tools Generate... from the menu. Project Designer will then ask you where you want to save the project. You should store each project in a new directory. In the 'Save' window create a new directory somewhere and then give the project a name in the 'File name:' field. For example: I have created a new folder called 'HelloWorld' and I have named my project as 'HelloWorld':-
HelloWorld4.jpg
Once the project has been saved you will be prompted to enter some information for the code generation step:-
HelloWorld5.jpg
The first field allows us to select from the drop down where we want any text output to be sent to by default. Since we are going to be outputting the text "Hello World" then we select the UART we want to send the text out of.
The second field allows us to select where WebbotLib will send any error messages to. We can leave this field blank if we want - but we may as well send them out to the PC over the UART as well.
The first tick box indicates whether or not you want an AVRStudio project file to be created or not. This box may be greyed out if you don't have AVRStudio installed or if there is already an AVRStudio file in the project folder.
The second tick box dictates whether your code will be compiled with optimisation. Leave it un-checked for now.
The third tick box allows us to choose between using C and C++. Tick the box to use C++.
The final field allows you to select the folder where WebbotLib has been installed. The code generation process uses this to detect whether you are using Version 1 or Version 2 of WebbotLib as well as adding the correct WebbotLib folder to the build process we will be doing next. Since this document is about WebbotLib Version 2 then I have selected a Version 2 folder.
The list box allows you to add in extra folders for locating other .H files. We wont be using it in this example so just click on the Ok button.
Project Designer remembers all of these settings so if you have to repeat the code generation process then it will show the settings you specified last time.
Use Windows Explorer to have a look at the folder where you saved the project. You will now see lots of files. This is what I can see in my HelloWorld folder:-
HelloWorld6.jpg
HelloWorld.prj - is the Project Designer project file
example.txt - this contains some example code. Initially the contents are identical to <Project>.cpp which in this case is HelloWorld.cpp. Why? Well we are going to modify HelloWorld.cpp to make it do what we want our project to do and if we did another code generation then we don't want Project Designer to delete all of the code we have typed in! But if we were to add extra devices then example.txt is a useful file to look at to see some example code of how to use that new device.
hardware.h - contains code to initialise your devices. Never change it by hand! Otherwise all of your changes will be lost next time you do a code generation.
HelloWorld.cpp - this is where all of your code will be added. We will do this in a minute.
makefile - This is a standard makefile to allow you to build your project on Windows, Mac or Unix. Again - you should never change this.
HelloWorld.aps - this is the AVRStudio project file. It is only created if you ticked the box during the code generation process.
You will also see a sub-folder called 'lib'. This contains a number of files that augment the standard library for your project. You should never change any of these. Just forget about them!
Add your own code
We have now created a project and we can compile it.
You can do this in a number of ways.
1. If you are using AVRStudio then you can start it up and load the HelloWorld.aps AVRStudio file. and build the project.
2. Alternatively you can open a command prompt window and navigate to your HelloWord folder and just type in: make
The program should compile with no errors.
But wait - nowhere have we told anything that it should be writing the phrase "Hello World" over the UART.
To do this we will open up the main file (HelloWorld.cpp). It looks like this:-
#include "hardware.h"
 
// Initialise the hardware
void appInitHardware(void) {
    initHardware();
}
 
// Initialise the software
TICK_COUNT appInitSoftware(TICK_COUNT loopStart){
    return 0;
}
 
// This is the main loop
TICK_COUNT appControl(LOOP_COUNT loopCount, TICK_COUNT loopStart) {
    return 0;
}
So what's all of that ?
When your program starts it first calls the 'appInitHardware' function. This in turn calls 'initHardware' which is in the generated 'hardware.h'. This initialises all of the devices you are using - so don't worry about it.
It then calls 'appInitSoftware' once - and this is where you can add any 'one-off' code. But we will leave it unchanged. The loopStart parameter parameter is the number of micro-seconds since the power switch was turned on.
Finally 'appControl' is called repeatedly - it is your main loop that is called over and over. So this is where we are going to output our message to the PC. You will see that two values are passed in: loopCount and loopStart. Although we won't be using them here then its worth mentioning what they are. 'loopCount' is just a number that increases by one every time and 'loopStart' is the current time-of-day ie the number of micro-seconds since the power switch was turned on.
You will also see that 'appControl' can return a value. This represents the frequency at which you want your appControl to be called - in microseconds. So returning a value of 1,000,000 will mean that your appControl will be called every 1,000,000µs (ie 1 second) whereas returning a value of 0 makes everything run with no delay.
So WebbotLib spends some of its time running your program (appControl) and another lump of time just 'hanging around' before calling your code again. Although not yet implemented by the library this means that we can calculate the amount of time each iteration through 'appControl' actually takes and so you could implement a 'CPU utilisation' graph similar to that in the Windows Task Manager.
Let's revisit what we want our program to do: "continually print 'Hello World' every second".
Well since its going to happen continually, rather than just once, then we are going to change the 'appControl' code as that's the only one that is called repeatedly.
During the code generation process we told Project Designer to set up the default output (stdout) to go via the UART - so that piece, along with the baud rate, has already been done for us. All we have to do is add the line:-
PRINTF(stdout,"Hello World\n");
into 'appControl' - the '\n' just adds a 'newline' at the end - so that each message starts on a new line on the PC.
The only other thing we have to do is make 'appControl' return a value of 1,000,000 so that it only happens every 1 second.
So let's see what our new version of appControl looks like:-
// This is the main loop
TICK_COUNT appControl(LOOP_COUNT loopCount, TICK_COUNT loopStart) {
    PRINTF(stdout,"Hello World\n");
    return 1000000;
}
Save the file and re-compile using 'make' or 'AVRStudio' as described above.
You now have a file in your HelloWorld folder called HelloWorld.hex which can be flashed to the board. (I can't cover how to do that here as it depends on your board as well as the hardware programmer you are using).
Testing the program
First of all we need to hook the board up to your PC. If you have used a board where the UART is a USB connector (such as uart 1 on the Axon or AxonII) then you can just use a USB cable.
However: if you are using a board, like the $50 Robot, then the UART cannot just be plugged into a RS232 port on the PC as the voltage levels are different and would blow up your micro-controller. You will need to use a piece of hardware called a level shifter, also known as TTL-RS232 convertor. You've been warned !
Once connected then run your favourite terminal emulation program such as HyperTerminal on Windows and set it up to use the same baud rate as the UART you selected in Project Designer.
Now turn on the board and you see the message "Hello World" displayed every second.
Tweak it
Let's now add the message "Start Up Complete" which prints out once when the board is first powered up.
We can't add this to appControl because that is called repeatedly. We can't add it into appInitHardware as that's where our hardware gets initialised - so the UART may not be up and running yet! The answer is to put it into appInitSoftware as that is only called once - after the hardware has been initialised.
// Initialise the software
TICK_COUNT appInitSoftware(TICK_COUNT loopStart){
    PRINTF(stdout, "Start Up Complete\n");
    return 0;
}
Compile it, upload it and test it.

Valid XHTML 1.0 Transitional