Getting acquainted: blinking LEDs

In this tutorial you get acquainted with the Dwengo board. Step by step you'll learn how to install the programming environment and the compiler, how to use the programmer and finally how to install and run your first program on the Dwengo board.

Requirements

1. One Dwengo board
2. One Dwengo programmer
3. Enclosed USB cable
4. Internet connection

Installation of the software

We'll start by downloading and installing the C18-compiler . For this you need to register at the website of Microchip. This free evaluation version of the C18-compiler contains all the functionality we need. The full version also contains code optimisations which create smaller and faster programs, but these are not required when using the Dwengo board.

Next, download the free Microchip MPLAB IDE programming environment and install it. In this tutorial we used version 8.33. This version also contains the package HI-TECH C Pro, which we don't need however.

In order to make the programming easier and more intuitive, Dwengo developed a library that hides the low-level details of the PIC18F4550 microcontroller. In the tutorials we will gratefully use this library.

To use the library, you only have to download the zip file and extract it. The lib file in this extracted folder should be moved to the folder C:\MCC18\lib, while the header files should be moved to the folder C:\MCC18\h. For more background information about the Dwengo library we refer to our Dwengo library page.

Your first project

Step 1: creating the project

We will create a project that allows to control the LEDs of the Dwengo board. Start the MPLAB IDE. Next, open the Project Wizard in the Project menu. Click Next and select the correct Device: PIC18F4550.

Click Next again and select the C18 Toolsuite. Make sure the location of the C18-compiler is correct and change it if needed.

Click Next once again and provide a name (for example BlinkingLeds) and a location for your new project. Click Next a last time and then Finish. You have now created your first project. Note that we skipped step 4, Add existing files to your project.

Finally add the dwengo.lib to your project. This makes the functionality of the Dwengo library available to your project.

Step 2: writing the code

The next step is the creation of a new C-code file. For this you go to the Project menu and choose Add New File to Project. Choose a name for your new file and make sure the new file has the extension .c (for example BlinkingLeds.c), recall you will be writing C-code.

This file will be automatically added to the Source Files of the project. You can see an overview of the added files by enabling the Project option in the menu View.

Now you can write C-code in the code file you just created. The simple program we are going to write consists of two parts:

1. Adding libraries you wish to use, the so-called header-files
2. The code itself in the main loop: the main-function

We only need three libraries for making the LEDs of the Dwengo board blink. These are the basic files you will need in all your projects. The first library, dwengoConfig.h, makes sure your microcontroller is correctly configured. The second library, dwengoBoard.h, defines intuitive names for the different connectors of the microcontroller, correspondingly with the functionality on the Dwengo board. Finally the last library, dwengoDelay.h, contains the functions we will need to make the program wait for a certain amount of time. This way we are able to adjust the blinking speed. The libraries are included with the following code:

#include <dwengoConfig.h>
#include <dwengoBoard.h>
#include <dwengoDelay.h>

Now you have come to the part of writing the main loop, the main-function, of the program:

void main(void) {
  initBoard();
  while (TRUE) {
    LEDS = 0b11111111;   // LED0-7 on
    delay_ms(200);
    LEDS = 0b00000000;   // LED0-7 off
    delay_ms(200);
  }
}

Each time the microcontroller is turned on, the main function will be executed. This is done sequentially, i.e. line by line, similar to most classical programming languages (for example Java, C, C++, Basic, ...). In contrast to classic programs though, we do not want the program to end. Rather, the microcontroller should keep performing its function until the power is switched off. To this end, the main loop is repeated infinitely using the while (TRUE) statement. The main function can thus be split in two components. Line 2 does the initialization, which is done only once, just after power-on. Lines 4-7 are the main loop which is repeated continuously once the initialization is completed. This arrangement is typical for all embedded programs.

In the above example all 8 LEDs are addressed using an 8 bit number. A 1 in this number turns on the corresponding LED, a 0 turns it out. It is possible to turn each LED seperately on or off (without influencing the other LEDs). De LEDs are numbered from 0 to 7. Turing on and off LED0 is done by the following commands:

LED0 = 1;
LED0 = 0;

To adjust the blinking speed, place a delay between turning the LEDs on and off. In the above example we a delay of 200 ms.

If you register, you can download the complete program at the bottom of this page. For this you have to be logged in.

Step 3: compilation of the program

Now that you have written your first lines of code, you surely want to test your Dwengo board. For this you have to transform your code to binary code that can be executed by the microcontroller. This process is called compilation. The process requires that you add a linker script to the project. Go the the menu Project, choose Add Files to Project and navigate to the location where the Microchip C18-compiler is installed (the default path is C:\MCC18). In the folder C:\MCC18\bin\LKR you can find the file 18f4550_g.lkr which has to be inserted into the project.

If everything went well, the linker script should be listed under Linker Scripts. Now you can compile the project by going to the menu Project and clicking Build All. When the compilation was successful, Build Succeeded will appear on the screen.

If you executed one of the previous steps incorrectly, you will see Build Failed. You will have to find out what went wrong. For simple programs such as this one, the most common mistakes are typing errors. If you are sure that all the previous steps are done correctly (no typing mistakes, added the linker script) and you always get the following error:
Error - could not find file 'c018i.o'
it is possible that MPLAB IDE is unable to find the C18 libraries and linker scripts. To solve this, you can perform the following steps:

1. Navigate in the menu Project to Build Options
2. Select Directories
3. Choose Include Search Path in Show directories for
4. Click New and add the path to the h folder of the C18 library, usually this is C:\MCC18\h
5. Choose Library Search Path in Show directories for
6. Click New and add the path to the lib folder, usually this is C:\MCC18\lib (see figure)
7. Finally choose Linker-Script Search Path in Show directories for
8. Click New and add the path to the lkr folder, usually this is C:\MCC18\bin\LKR
9. Click Apply and OK

Then try to recompile the project again, normally everything should be fine now.

Step 4: programming and testing the program

You are now ready to program the Dwengo board with your application. For this you need the Dwengo programmer. Connect the programmer to the computer with the USB cable. Next connect the programmer to the Dwengo board. Make sure that the programmer is connected correctly (see figure)!

In the Programmer menu under Select Programmer, choose the PICkit2. If you connected the programmer and the Dwengo board correctly, PICkit 2 Ready appears on the screen. Moreover, the Power LED on the Dwengo board will light up to indicate that the board is powered on.

To program the board, select Program in the Programmer menu. A few moments later the board is programmed. To test the board you can now reset the board through MPLAB: choose the Programmer menu option and click Hold in Reset followed by Release from Reset. Now you can see all 8 LEDs blink on the Dwengo board.

Step 5: detachment, code adjustments, further experiments

After you have programmed the Dwengo board, you can detach the programmer from the board. You will notice that the LEDs stop blinking. After all the board no longer receives any power. Attach the board directly to the computer with the USB cable. The LEDs will start blinking again.

You have successfully finished your first tutorial. You can now start experimenting on you own.

Perhaps you could try to adjust the speed of blinking. If you have altered the code, you can recompile (Build all) and program the board with your new version. Of course you will have to attach the programmer to the board. After making the physical connection, click Connect in the Programmer menu. Only then will the PICkit 2 Ready message appear on the screen.