ASF Tutorial using ASF on a Custom or User Board

Created on: 20 April 2016

Part 3 of the ASF ARM Tutorial

How to create an ASF project in Atmel Studio 7 for a custom or user board.

In the previous part of this tutorial, we used an Atmel ARM Cortex SAM4N Xplained board and created a new ASF project for this specific board. This is fine for initial evaluation of a microcontroller and the ASF. Development is easy because the hardware on the board is defined in the Atmel Studio ASF project and initialized in the C code.

Most software will be developed using a custom board for a specific project or product rather than for an evaluation board. In this case it is necessary to know how to initialize the hardware and customise an ASF project for use with a custom board. This part of the tutorial shows how to create and use an ASF project in Atmel Studio 7 for a custom board.

Custom Board Hardware

It is not necessary to actually have a custom board to see how to create an Atmel Studio ASF user board project. The same evaluation board that was used in the previous part of the tutorial can be used again, even with a user board project.

A user board project is created in Atmel Studio instead of a project for a particular Atmel evaluation board or kit. This part of the tutorial will continue to use the Atmel SAM4N Xplained Pro board. The difference is that a user board ASF template will be selected instead of a SAM4N Xplained Pro ASF template during the creation of a new project in Atmel Studio. The hardware in the project will not be pre-defined and will have to be defined by the user.

Creating a User Board ASF Project in Atmel Studio

The following steps show how to create a new user board template ASF project in Atmel Studio, add ASF modules to the project and create a blinking LED C program using ASF functions.

1. Create a New ASF Project

Create a new ASF project as done in the previous part of this tutorial, but select User Board template in the Board Selection dialog box. The following images show how to create a user board template for the ATSAM4N16C ARM microcontroller.

Start by creating a new project – I am calling this one user_board_led_blink.

Select User Board template after filtering for the particular microcontroller on the board using the search field at the top of the dialog box.

2. Add the ASF Modules

In the ASF Wizard for the new project in Atmel Studio, select the project name at the top of the ASF Wizard dialog box. If ASF Wizard is not open, open it by selecting ASF → ASF Wizard from the top menu.

Notice that only the Generic board support driver module is automatically included in the user board project. In the Atmel board project in the previous part of this tutorial, the IOPORT module was automatically included.

Add the IOPORT service module and the Delay routines service module by searching for them in the Available Modules pane of ASF Wizard. The following image shows these two modules added to the project. Remember to click the Apply button after adding the two modules.

3. Add the C Code

Now that the ASF modules needed by the project have been added, we can write the C application code. Open the main.c file using the Solution Explorer pane.

3.1 Write the Application Code

Add the following code to main.c

#include <asf.h>

int main (void)
{
    /* Insert system clock initialization code here (sysclk_init()). */
    sysclk_init();
    board_init();
    
    WDT->WDT_MR = WDT_MR_WDDIS;                         // disable watchdog
    ioport_init();                                      // call before using IOPORT service
    ioport_set_pin_dir(LED0, IOPORT_DIR_OUTPUT);        // LED pin set as output
    ioport_set_pin_level(LED0, IOPORT_PIN_LEVEL_HIGH);  // switch LED off

    /* Insert application code here, after the board has been initialized. */
    while (1) {
        ioport_toggle_pin_level(LED0);
        delay_ms(1000);
    }
}

The above code is shown here in Atmel Studio.

The code should mostly look familiar as it flashes an LED in the same way as the code from the previous part of this tutorial did. The difference is the code between the board_init() function and the top of the while(1) loop.

3.2 Hardware Initialization

In the previous part of this tutorial, the ASF project was created for a specific board, so the hardware definitions for the board and initialization of the hardware were automatically added to the project when it was created. As this project is a user board project, the board hardware is not defined or initialized.

The following code disables the watchdog timer, initializes the IOPORT ASF module, sets the pin that LED 0 is on as an output pin and finally switches the LED off.

WDT->WDT_MR = WDT_MR_WDDIS;                         // disable watchdog
ioport_init();                                      // call before using IOPORT service
ioport_set_pin_dir(LED0, IOPORT_DIR_OUTPUT);        // LED pin set as output
ioport_set_pin_level(LED0, IOPORT_PIN_LEVEL_HIGH);  // switch LED off

These tasks and other board initialization were automatically added to the board_init() function in the previous project, so we could start using the hardware immediately. The above code should also have been put into the board_init() function for this project, but was left in main() this time to make the project simpler. Currently board_init() is an empty function in this project.

Using a different board:
If you are using a different board to the SAM4N Xplained Pro, then open the previous project and navigate to and open src\ASF\sam\boards\<board_name>\init.c to find the initialization code for your board in board_init(). Copy and modify the necessary initialization functions from this file for your user board project. If the board is an Atmel ARM Cortex board, then nothing should need to be changed for this simple project, except maybe the LED name which is called LED0, but has not yet been defined for this project.

3.3 Define the Hardware

In the case of a user board project we still have to define the hardware. This is done in the conf_board.h file which can be found using the Atmel Studio Solution Explorer. Use the Solution Explorer to navigate to and open this file found in src\config\conf_board.h and add the following code to the file.

#ifndef CONF_BOARD_H
#define CONF_BOARD_H

// clock resonators
#define BOARD_FREQ_SLCK_XTAL      (32768U)
#define BOARD_FREQ_SLCK_BYPASS    (32768U)
#define BOARD_FREQ_MAINCK_XTAL    (12000000U)
#define BOARD_FREQ_MAINCK_BYPASS  (12000000U)
#define BOARD_MCK                 CHIP_FREQ_CPU_MAX
#define BOARD_OSC_STARTUP_US      15625

// LED
#define LED0    IOPORT_CREATE_PIN(PIOB, 14)

#endif // CONF_BOARD_H

The code is shown in the file in Atmel Studio below.

The above code defines the clock resonator values and the pin that LED 0 is on. The LED 0 pin is defined as LED0 which is used in the application code in main().

Using a different board:
If you are using a different board than the SAM4N Xplained Pro, then open the previous project and this file from the previous project: src\ASF\sam\boards\<board_name>\<board_name>.h to find the clock resonator settings and LED definition for your board.

You will also need to find which port and pin number the LED that you want to use is on. The following line of code shows that the LED is on pin 14 of PORT B.

#define LED0    IOPORT_CREATE_PIN(PIOB, 14)

4. Build and Test the Project

As can be seen from this part of the tutorial, we had to add hardware definitions for the board and add hardware initialization code because this project is based on a user board ASF template.

Once the above code has been added, the project can be built and loaded to the board for testing. It works the same as the previous project, but the LED is toggled at 1 second intervals instead of at 400ms intervals.

Still to Come in this Tutorial Series

We have seen two ways of creating ASF projects in Atmel Studio. Not much has been said about the ASF modules and functions from these modules. A comparison between Atmel board ASF projects and user board ASF projects is presented in part 5 of this tutorial series. ASF modules and functions are also explained in more detail in each new part of the tutorial series as they are used.