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 setting up the programming environment. First download the free Microchip MPLAB IDE 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.

Next, download and install 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.

During the installation of the C18-compiler, indicate that you are using the MPLAB IDE. This ensures that the C18-compiler is immediately recognised when starting up the MPLAB IDE.

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.

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 C18-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 C18-code in the code file you just created. The simple program we are going to write consists of four parts:

1. Adding libraries you wish to use, the so-called header-files
2. Configure the microcontroller by configuring the fuses
3. Define macros to make the code more readable
4. The code itself in the main loop: the main-function

We only need two libraries for making the LEDs of the Dwengo board blink. A first library, p18f4550.h, contains all the functions needed to address the registers of the microcontroller. The second library, delays.h, contains the functions we will need to make the program wait for a number of cycles. This way we are able to adjust the blinking speed. The libraries are included with the following code:

#include <p18f4550.h>
#include <delays.h>

Next you will have to correctly configure the microcontroller's internal settings by setting the so-called fuses. A standard set of fuses, suitable for most applications, is provided here with comments (preceded by a double slash):

// Fuses configuration
#pragma config PLLDIV = 5       // Divide by 5 (20 MHz oscillator input)
#pragma config FOSC = HSPLL_HS  // HS oscillator, PLL enabled, HS used by USB
#pragma config IESO = OFF       // Oscillator Switchover mode disabled
#pragma config PWRT = OFF       // PWRT disabled
#pragma config BOR = OFF        // Brown-out Reset enabled in hardware only (SBOREN is disabled)
#pragma config WDT = OFF        // HW Disabled - SW Controlled
#pragma config WDTPS = 32768    // 1:32768
#pragma config MCLRE = ON       // MCLR pin enabled; RE3 input pin disabled
#pragma config LVP = OFF        // Disable low-voltage programming
#pragma config CCP2MX = ON      // Config3h
#pragma config PBADEN = OFF     // PORB digital IO on powerup

For some of these fuses you may whish to use alternate values. Others depend on specific properties of the Dwengo board (for instance the clock frequency of the on-board oscillator) and will be the same for all your projects with the Dwengo board. You can find more information on the meaning of the different fuses in the document Commonly used configuration bits for the Dwengo board.

The C programming language allows one to define several things in advance by using macros to improve readability. This is especially important for large projects. In this project we define the macro TRUE as 1 so that we can use this later in the main loop. During the compilation of the project, the compiler will automatically replace all instances of TRUE in the code with the value 1.

#define TRUE 1

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

void main(void) {
  TRISD = 0x00;           // Configure PORTD-pins as outputs
  while (TRUE) {
    PORTD = 0b11111111;   // LED0-7 on
    Delay10KTCYx(240);    // TCx = 83.333ns, 1 ms = 12000 TCx, 200 ms = 2400 KTCx
    PORTD = 0b00000000;   // LED0-7 off
    Delay10KTCYx(240);
  }
}

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 schematics of the the Dwengo board you can see that the 8 LEDs are connected to pins RD0 up to RD7. All these pins are addressed through the PORTD register, each bit in this 8-bit register corresponds to one pin. Before a pin can be used as an output, you have to configure it as such. This is done with the aid of a TRIS register: setting a bit to 1 here makes the corresponding pin float its output, i.e. it will not force a 0 or 1 value. This makes the pin usuable as an input. Since we use all 8 RD-pins as outputs, we can set the complete TRISD register to 0. Next we make an infinite loop that continues to execute the following actions:

1. write 1 to all 8 RD-pins by configuring PORTD as such, this turns on all 8 LEDs.
2. wait for 200 ms
3. write 0 to all 8 RD-pins by configuring PORTD as such, this turns all 8 LEDs off.
4. wait for 200 ms

The waiting time is determined by the Delay10KTCYx function in the Delays.h library. The clock is set to 48 MHz through the fuses. Each instruction cycle takes 4 clock cycles. This time is indicated with TCYx. In other words, TCYx equals 1/12,000,000 which is equal to 83.33 ns. So one millisecond takes 12,000 TCYx and 200 ms takes 2400 KTCYx (kilo-TCYx).

If you have purchased the Dwengo board, 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.